5.5 Primary Array or IMAGE Extension I/O Routines

These routines read or write data values in the primary data array (i.e., the first HDU in a FITS file) or an IMAGE extension. There are also routines to get information about the data type and size of the image. Users should also read the following chapter on the CFITSIO iterator function which provides a more `object oriented' method of reading and writing images. The iterator function is a little more complicated to use, but the advantages are that it usually takes less code to perform the same operation, and the resulting program often runs faster because the FITS files are read and written using the most efficient block size.

C programmers should note that the ordering of arrays in FITS files, and hence in all the CFITSIO calls, is more similar to the dimensionality of arrays in Fortran rather than C. For instance if a FITS image has NAXIS1 = 100 and NAXIS2 = 50, then a 2-D array just large enough to hold the image should be declared as array[50][100] and not as array[100][50].

The `datatype' parameter specifies the data type of the `nulval' and `array' pointers and can have one of the following values: TBYTE, TSBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TULONGLONG, TFLOAT, TDOUBLE. Automatic data type conversion is performed if the data type of the FITS array (as defined by the BITPIX keyword) differs from that specified by 'datatype'. The data values are also automatically scaled by the BSCALE and BZERO keyword values as they are being read or written in the FITS array.

1

Get the data type or equivalent data type of the image. The first routine returns the physical data type of the FITS image, as given by the BITPIX keyword, with allowed values of BYTE_IMG (8), SHORT_IMG (16), LONG_IMG (32), LONGLONG_IMG (64), FLOAT_IMG (-32), and DOUBLE_IMG (-64). The second routine is similar, except that if the image pixel values are scaled, with non-default values for the BZERO and BSCALE keywords, then the routine will return the 'equivalent' data type that is needed to store the scaled values. For example, if BITPIX = 16 and BSCALE = 0.1 then the equivalent data type is FLOAT_IMG. Similarly if BITPIX = 16, BSCALE = 1, and BZERO = 32768, then the the pixel values span the range of an unsigned short integer and the returned data type will be USHORT_IMG.

  int fits_get_img_type / ffgidt
      (fitsfile *fptr, > int *bitpix, int *status)

  int fits_get_img_equivtype / ffgiet
      (fitsfile *fptr, > int *bitpix, int *status)

2

Get the number of dimensions, and/or the size of each dimension in the image . The number of axes in the image is given by naxis, and the size of each dimension is given by the naxes array (a maximum of maxdim dimensions will be returned).

  int fits_get_img_dim / ffgidm
      (fitsfile *fptr, > int *naxis, int *status)

  int fits_get_img_size / ffgisz
      (fitsfile *fptr, int maxdim, > long *naxes, int *status)

  int fits_get_img_sizell / ffgiszll
      (fitsfile *fptr, int maxdim, > LONGLONG *naxes, int *status)

  int fits_get_img_param / ffgipr
      (fitsfile *fptr, int maxdim, > int *bitpix, int *naxis, long *naxes,
       int *status)

  int fits_get_img_paramll / ffgiprll
      (fitsfile *fptr, int maxdim, > int *bitpix, int *naxis, LONGLONG *naxes,
       int *status)

3

Create a new primary array or IMAGE extension with a specified data type and size. If the FITS file is currently empty then a primary array is created, otherwise a new IMAGE extension is appended to the file.

  int fits_create_img / ffcrim
      ( fitsfile *fptr, int bitpix, int naxis, long *naxes, > int *status)

  int fits_create_imgll / ffcrimll
      ( fitsfile *fptr, int bitpix, int naxis, LONGLONG *naxes, > int *status)

4

Copy an n-dimensional image in a particular row and column of a binary table (in a vector column) to or from a primary array or image extension.

The 'cell2image' routine will append a new image extension (or primary array) to the output file. Any WCS keywords associated with the input column image will be translated into the appropriate form for an image extension. Any other keywords in the table header that are not specifically related to defining the binary table structure or to other columns in the table will also be copied to the header of the output image.

The 'image2cell' routine will copy the input image into the specified row and column of the current binary table in the output file. The binary table HDU must exist before calling this routine, but it may be empty, with no rows or columns of data. The specified column (and row) will be created if it does not already exist. The 'copykeyflag' parameter controls which keywords are copied from the input image to the header of the output table: 0 = no keywords will be copied, 1 = all keywords will be copied (except those keywords that would be invalid in the table header), and 2 = copy only the WCS keywords.

  int fits_copy_cell2image
      (fitsfile *infptr, fitsfile *outfptr, char *colname, long rownum,
       > int *status)

  int fits_copy_image2cell
      (fitsfile *infptr, fitsfile *outfptr, char *colname, long rownum,
       int copykeyflag > int *status)

5

Write a rectangular subimage (or the whole image) to the FITS data array. The fpixel and lpixel arrays give the coordinates of the first (lower left corner) and last (upper right corner) pixels in FITS image to be written to.

  int fits_write_subset / ffpss
      (fitsfile *fptr, int datatype, long *fpixel, long *lpixel,
       DTYPE *array, > int *status)

6

Write pixels into the FITS data array. 'fpixel' is an array of length NAXIS which gives the coordinate of the starting pixel to be written to, such that fpixel[0] is in the range 1 to NAXIS1, fpixel[1] is in the range 1 to NAXIS2, etc. The first pair of routines simply writes the array of pixels to the FITS file (doing data type conversion if necessary) whereas the second routines will substitute the appropriate FITS null value for any elements which are equal to the input value of nulval (note that this parameter gives the address of the null value, not the null value itself). For integer FITS arrays, the FITS null value is defined by the BLANK keyword (an error is returned if the BLANK keyword doesn't exist). For floating point FITS arrays the special IEEE NaN (Not-a-Number) value will be written into the FITS file. If a null pointer is entered for nulval, then the null value is ignored and this routine behaves the same as fits_write_pix.

  int fits_write_pix / ffppx
      (fitsfile *fptr, int datatype, long *fpixel, LONGLONG nelements,
       DTYPE *array, int *status);

  int fits_write_pixll / ffppxll
      (fitsfile *fptr, int datatype, LONGLONG *fpixel, LONGLONG nelements,
       DTYPE *array, int *status);

  int fits_write_pixnull / ffppxn
      (fitsfile *fptr, int datatype, long *fpixel, LONGLONG nelements,
       DTYPE *array, DTYPE *nulval, > int *status);

  int fits_write_pixnullll / ffppxnll
      (fitsfile *fptr, int datatype, LONGLONG *fpixel, LONGLONG nelements,
       DTYPE *array, DTYPE *nulval, > int *status);

7

Set FITS data array elements equal to the appropriate null pixel value. For integer FITS arrays, the FITS null value is defined by the BLANK keyword (an error is returned if the BLANK keyword doesn't exist). For floating point FITS arrays the special IEEE NaN (Not-a-Number) value will be written into the FITS file. Note that 'firstelem' is a scalar giving the offset to the first pixel to be written in the equivalent 1-dimensional array of image pixels.

  int fits_write_null_img / ffpprn
      (fitsfile *fptr, LONGLONG firstelem, LONGLONG nelements, > int *status)

8

Read a rectangular subimage (or the whole image) from the FITS data array. The fpixel and lpixel arrays give the coordinates of the first (lower left corner) and last (upper right corner) pixels to be read from the FITS image. Undefined FITS array elements will be returned with a value = *nullval, (note that this parameter gives the address of the null value, not the null value itself) unless nulval = 0 or *nulval = 0, in which case no checks for undefined pixels will be performed.

  int fits_read_subset / ffgsv
      (fitsfile *fptr, int  datatype, long *fpixel, long *lpixel, long *inc,
       DTYPE *nulval, > DTYPE *array, int *anynul, int *status)

9

Read pixels from the FITS data array. 'fpixel' is the starting pixel location and is an array of length NAXIS such that fpixel[0] is in the range 1 to NAXIS1, fpixel[1] is in the range 1 to NAXIS2, etc. The nelements parameter specifies the number of pixels to read. If fpixel is set to the first pixel, and nelements is set equal to the NAXIS1 value, then this routine would read the first row of the image. Alternatively, if nelements is set equal to NAXIS1 * NAXIS2 then it would read an entire 2D image, or the first plane of a 3-D datacube.

The first 2 routines will return any undefined pixels in the FITS array equal to the value of *nullval (note that this parameter gives the address of the null value, not the null value itself) unless nulval = 0 or *nulval = 0, in which case no checks for undefined pixels will be performed. The second 2 routines are similar except that any undefined pixels will have the corresponding nullarray element set equal to TRUE (= 1).

  int fits_read_pix / ffgpxv
      (fitsfile *fptr, int  datatype, long *fpixel, LONGLONG nelements,
       DTYPE *nulval, > DTYPE *array, int *anynul, int *status)

  int fits_read_pixll / ffgpxvll
      (fitsfile *fptr, int  datatype, LONGLONG *fpixel, LONGLONG nelements,
       DTYPE *nulval, > DTYPE *array, int *anynul, int *status)

  int fits_read_pixnull / ffgpxf
      (fitsfile *fptr, int  datatype, long *fpixel, LONGLONG nelements,
       > DTYPE *array, char *nullarray, int *anynul, int *status)

  int fits_read_pixnullll / ffgpxfll
      (fitsfile *fptr, int  datatype, LONGLONG *fpixel, LONGLONG nelements,
       > DTYPE *array, char *nullarray, int *anynul, int *status)

10

Copy a rectangular section of an image and write it to a new FITS primary image or image extension. The new image HDU is appended to the end of the output file; all the keywords in the input image will be copied to the output image. The common WCS keywords will be updated if necessary to correspond to the coordinates of the section. The format of the section expression is same as specifying an image section using the extended file name syntax (see "Image Section" in Chapter 10). (Examples: "1:100,1:200", "1:100:2, 1:*:2", "*, -*").

  int fits_copy_image_section / ffcpimg
      (fitsfile *infptr, fitsfile *outfptr, char *section, int *status)