This section lists the more important CFITSIO routines which operate on FITS images.
_______________________________________________________________ int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status) int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status) int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes, int *status) int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix, int *naxis, long *naxes, int *status)
Get information about the currently opened image HDU. The first routine returns the datatype of the image as (defined by the BITPIX keyword), which can have symbolic constant values of BYTE_IMG (8), SHORT_IMG (16), LONG_IMG (32), FLOAT_IMG (-32), and DOUBLE_IMG (-64). The 2nd and 3rd routines return the number of dimensions in the image (from the NAXIS keyword), and the sizes of each dimension (from the NAXIS1, NAXIS2, etc. keywords). The last routine simply combines the function of the first 3 routines. The input maxdim parameter gives the maximum number dimensions to be returned.
__________________________________________________________ int fits_create_img(fitsfile *fptr, int bitpix, int naxis, long *naxes, int *status)
Create an image HDU by writing the required keywords which define the structure of the image. The 2nd through 4th parameters specified the datatype, the number of dimensions, and the sizes of the dimensions. The allowed values of the bitpix parameter are listed above in the description of the fits_get_img_type routine. If the FITS file pointed to by fptr is empty (previously created with fits_create_file) then this routine creates a primary array in the file, otherwise a new IMAGE extension is appended to end of the file following the other HDUs in the file.
______________________________________________________________ int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel, long nelements, void *array, int *status); int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel, long nelements, void *nulval, void *array, int *anynul, int *status)
Read or write all or part of the FITS image. fpixel is an array which gives the coordinate in each dimension of the first pixel to be read or written, and nelements is the total number of pixels to read or write. array is the address of an array which either contains the pixel values to be written, or will hold the values of the pixels that are read. When reading, array must have been allocated large enough to hold all the returned pixel values. This routine starts at the fpixel location and then reads or writes the nelements pixels, continuing on successive rows of the image if necessary. For example, to write an entire 2D image, set fpixel[0] = fpixel[1] = 1, and nelements = NAXIS1 * NAXIS2. Or to read just the 10th row of the image, set fpixel[0] = 1, fpixel[1] = 10, and nelements = NAXIS1. The datatype parameter specifies the datatype of array, which need not be the same as the datatype of the FITS image itself. If the datatypes differ then CFITSIO will convert the data as it is read or written. The following symbolic constants are allowed for the value of datatype: TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT, and TDOUBLE.
FITS images can in principle contain undefined pixels which have no assigned value; CFITSIO will substitute the value given by nulval for any undefined pixels in the image, unless nulval = NULL, in which case no checks will be made for undefined pixels when reading the FITS image. Note that nulval gives the address of the value, not the value itself.
_________________________________________________________________ int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel, long *lpixel, DTYPE *array, > int *status) int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel, long *lpixel, long *inc, void *nulval, void *array, int *anynul, int *status)
Read or write a rectangular section of the FITS image. These are very similar to fits_write_pix and fits_read_pix except that you specify the last pixel coordinate (the upper right corner of the section) instead of the number of pixels to be read. The read routine also has an inc parameter which can be used to read only every inc-th pixel along each dimension of the image. Normally inc[0] = inc[1] = 1 to read every pixel in a 2D image. To read every other pixel in the entire 2D image, set fpixel[0] = fpixel[1] = 1, lpixel[0] = NAXIS1, lpixel[1] = NAXIS2, and inc[0] = inc[1] = 2. Or, to read the 8th row of a 2D image, set fpixel[0] = 1, fpixel[1] = 8, lpixel[0] = NAXIS1, lpixel[1] = 8, and inc[0] = inc[1] = 1.