C USING IMG FROM C

C functions, that are equivalent to the Fortran subroutines, are available for those who prefer this language (indeed using IMG from C can seem more natural as IMG returns pointers to data). The major changes in the interface (compared with the Fortran specifications) are that the names of functions change from img_something or hdr_something to imgSomething and hdrSomething and that “strings” which are returned or can be passed as arrays also have a length argument.

C.1 IMG C functions

Where the parts in "[]" are optional or not always available. [N] indicates the number of dimensions of the data you want to access and the necessary nx, ny and nz arguments should be passed.

The ordering of array dimensions is different in C to Fortran, so for instance the Fortran array ARRAY(NX,NY,NZ) is equivalent to the C array ARRAY[NZ][NY][NX], but usually this is of little importance since images are not of fixed sizes (so you’re unlikely to hard code any array dimensions) and you’re far more likely to use the data via a pointer to the first element. Since C arrays also always start at 0 (rather than 1 as is the default in Fortran) the index of an element say [y][x] is nx $\times$ y $+$ x. In 3-D this becomes [z][y][x] — nx $\times$ ny $\times$ z $+$ nx $\times$ y $+$ x.

The data type of the image is specified by replacing the [X] part of the name by one of the following character codes:

C.2 HDR C functions

C.3 Examples of using IMG from C

C.3.1 Accessing an existing image

This section shows a C version of the mean program from §2.1.

The following notes refer to the numbered statements:

(1)

The file img.h contains prototypes of all the IMG and HDR functions.

(2)

As in the Fortran case this program needs to be created as a function with an int * argument. This is a replacement for the main function. Note that the function is named the same as the eventual program except for the trailing underscore. The underscore is required as this function will be called from a Fortran subroutine (you should also note that this “trick” may not be the same from machine to machine, to do this portably you should use the CNF (SUN/209) macros as in the full example of mean.c).

As before an interface file - mean.ifl - is also required to complete the program.

C.3.2 Creating a new image

This example (flat.c) shows how to create a new image. It also sets all the elements of the image to 1.0.

C.3.3 Modifying an image

This example shows how to access an existing image and modify its values.

C.3.4 Modifying a copy of an image

This example (add.c) copies the input image and then modifies the copy.

C.3.5 Getting images as workspace

This example (shadow.c) shows how to create temporary images. The HDS (SUN/92) manual describes some reasons why you might consider using temporary images rather than “malloc’d” memory in your programs.

C.3.6 Using “images” which are not 2-dimensional

This section just shows some example calls that access spectra and data-cubes.

C.3.7 Accessing images using different data types

So far all the example shown access the image data assuming a type of float. IMG can also access data in other useful types. A list of these is shown in §C.1. Among the possible calls are:

Requirements for data types and dimensionalities can be mixed as in:

C.3.8 Accessing multiple images

This example (proc.c) shows how IMG can access more than one image per function call:

(1)

Note that the variable ip is declared as an array of pointers to float.

(2)

After this call each of the elements of ip is set to point to a different image. The advantage of such a call is that all the images are guaranteed to be the same shape and data type.

C.3.9 Handling “bad” data

The way that you handle “bad” values in your data is similar to that used in Fortran, see §4.1.6, however, the bad data values themselves are now defined in the img.h file and have names to reflect the C data types.

C.4 Examples of using HDR from C

C.4.1 Reading header items

This example (hdrread.c) shows how to read the value of a header item.

(1)

A character “string” is declared to contain the value of the header item.

(2)

The size of the string is passed as an additional argument when calling hdrIn (this argument is not present in the Fortran version).

C.4.2 Writing header items

This example (hdrwrite.c) shows how to write a header item to an image.

(1)

Note the extra argument which is set to 0. This indicates that a single string ("Fred Bloggs") has been passed. This could also have been set to the value 12, the string length. This argument is of more significance when dealing with multiple images.

C.4.3 Accessing header items using different data types

All the possible types of header items that can be accessed are described in §C.2. Among the possible calls are:

C.4.4 Accessing header items by index

This example (hdrlist.c) shows how to access header items by index.

(1)

Note the extra arguments (30 & 80) that pass the maximum length of the output strings.

C.4.5 Reading and writing header items from/to many images

It is possible to read and write header items from/to many images in one call and some examples follow. Note that arrays of strings can only be passed using fixed string length. It is not possible to use arrays of pointers to char forming a ragged array. When using a character array you should pass a pointer to the first element not the actual array (as the HDR routines expect to see char *).

This example shows how to read the same header item from two images at the same time.

(1)

The address to the first element of the RA and DEC arrays is passed. This could have been written as &RA[0][0] and &DEC[0][0].

This example shows how to write values to the same header item of two images.

C.5 Compiling and linking C programs

Compiling and linking a C program is very similar to the methods described (in §6), except that you must compile the source code before the linking stage.

If your program source file is named prog.c, and it only depends on IMG, then the commands: