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 oftens 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 datatype of the `nulval' and `array' pointers and can have one of the following values: TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, 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, number of dimensions, and/or the size of each dimension in the image . The datatype is determined by the bitpix parameter which has allowed values of BYTE_IMG (8), SHORT_IMG (16), LONG_IMG (32), FLOAT_IMG (-32), and DOUBLE_IMG (-64). 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_type / ffgidt
      (fitsfile *fptr, > int *bitpix, int *status)

  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_param / ffgipr
      (fitsfile *fptr, int maxdim, > int *bitpix, int *naxis, long *naxes,
       int *status)

2

Create a new primary array or IMAGE extension with a specified datatype 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)

3

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)

4

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 routine simply writes the array of pixels to the FITS file (doing datatype conversion if necessary) whereas the second routine 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, long nelements,
       DTYPE *array, int *status);

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

5

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, long firstelem, long nelements, > int *status)

6

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)

7

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 routine 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 routine is similar except that any undefined pixels will have the corresponding nullarray element set equal to TRUE.    

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

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