This chapter describes the main CFITSIO routines that can be used to perform the most common types of operations on FITS files.
void fits_report_error(FILE *stream, int status) void fits_get_errstatus(int status, char *err_text) float fits_get_version(float *version)
The first routine prints out information about any error that has occurred. Whenever any CFITSIO routine encounters an error it usually writes a message describing the nature of the error to an internal error message stack and then returns with a positive integer status value. Passing the error status value to this routine will cause a generic description of the error and all the messages from the internal CFITSIO error stack to be printed to the specified stream. The stream parameter is usually set equal to "stdout" or "stderr".
The second routine simply returns a 30-character descriptive error message corresponding to the input status value.
The last routine returns the current CFITSIO library version number.
int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status) int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status) int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status) int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status) int fits_create_file(fitsfile **fptr, char *filename, int *status) int fits_close_file(fitsfile *fptr, int *status)
These routines open or close a file. The first fitsfile parameter in these and nearly every other CFITSIO routine is a pointer to a structure that CFITSIO uses to store relevant parameters about each opened file. You should never directly read or write any information in this structure. Memory for this structure is allocated automatically when the file is opened or created, and is freed when the file is closed.
The mode parameter in the fits_open_xxxx set of routines can be set to either READONLY or READWRITE to select the type of file access that will be allowed. These symbolic constants are defined in fitsio.h.
The fits_open_file routine opens the file and positions the internal file pointer to the beginning of the file, or to the specified extension if an extension name or number is appended to the file name (see the later section on “CFITSIO File Names and Filters” for a description of the syntax). fits_open_data behaves similarly except that it will move to the first HDU containing significant data if a HDU name or number to open is not explicitly specified as part of the filename. It will move to the first IMAGE HDU with NAXIS greater than 0, or the first table that does not contain the strings ‘GTI’ (a Good Time Interval extension) or ‘OBSTABLE’ in the EXTNAME keyword value. The fits_open_table and fits_open_image routines are similar except that they will move to the first significant table HDU or image HDU, respectively if a HDU name of number is not specified as part of the input file name.
When opening an existing file, the filename can include optional arguments, enclosed in square brackets that specify filtering operations that should be applied to the input file. For example,
myfile.fit[EVENTS][counts > 0]
opens the table in the EVENTS extension and creates a virtual table by selecting only those rows where the COUNTS column value is greater than 0. See section 5 for more examples of these powerful filtering capabilities.
In fits_create_file, the filename is simply the root name of
the file to be created. You can overwrite an existing file by
prefixing the name with a ‘!’ character (on the Unix command line this
must be prefixed with a backslash, as in `\!file.fit').
If the file name ends with .gz the file will be compressed
using the gzip algorithm. If the
filename is stdout or "-" (a single dash character)
then the output file will be piped to the stdout stream. You can
chain several tasks together by writing the output from the first task
to stdout and then reading the input file in the 2nd task from
stdin or "-".
The routines listed in this section operate on Header-Data Units (HDUs) in a file.
_______________________________________________________________ int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status) int fits_get_hdu_num(fitsfile *fptr, int *hdunum)
The first routines returns the total number of HDUs in the FITS file, and the second routine returns the position of the currently opened HDU in the FITS file (starting with 1, not 0).
__________________________________________________________________________
int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status)
int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status)
int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname,
int extver, int *status)
These routines enable you to move to a different HDU in the file. Most of the CFITSIO functions which read or write keywords or data operate only on the currently opened HDU in the file. The first routine moves to the specified absolute HDU number in the FITS file (the first HDU = 1), whereas the second routine moves a relative number of HDUs forward or backward from the currently open HDU. The hdutype parameter returns the type of the newly opened HDU, and will be equal to one of these symbolic constant values: IMAGE_HDU, ASCII_TBL, or BINARY_TBL. hdutype may be set to NULL if it is not needed. The third routine moves to the (first) HDU that matches the input extension type, name, and version number, as given by the XTENSION, EXTNAME (or HDUNAME) and EXTVER keywords. If the input value of extver = 0, then the version number will be ignored when looking for a matching HDU.
_________________________________________________________________ int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status)
Get the type of the current HDU in the FITS file: IMAGE_HDU, ASCII_TBL, or BINARY_TBL.
____________________________________________________________________
int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys,
int *status)
int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous,
int current, int following, > int *status)
The first routine copies the current HDU from the FITS file associated with infptr and appends it to the end of the FITS file associated with outfptr. Space may be reserved for morekeys additional keywords in the output header. The second routine copies any HDUs previous to the current HDU, and/or the current HDU, and/or any HDUs following the current HDU, depending on the value (True or False) of previous, current, and following, respectively. For example,
fits_copy_file(infptr, outfptr, 0, 1, 1, &status);
will copy the current HDU and any HDUs that follow it from the input to the output file, but it will not copy any HDUs preceding the current HDU.
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 the following symbolic constant values:
BYTE_IMG = 8 ( 8-bit byte pixels, 0 - 255)
SHORT_IMG = 16 (16 bit integer pixels)
LONG_IMG = 32 (32-bit integer pixels)
LONGLONG_IMG = 64 (64-bit integer pixels)
FLOAT_IMG = -32 (32-bit floating point pixels)
DOUBLE_IMG = -64 (64-bit floating point pixels)
The second and third 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 in this routine gives the maximum number dimensions that may be returned (i.e., the dimension of the naxes array)
__________________________________________________________
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_write_pixnull(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *array, void *nulval, 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. There are 2 different ’write’ pixel routines: The first simply writes the input array of pixels to the FITS file. The second is similar, except that it substitutes the appropriate null pixel value in the FITS file for any pixels which have a value equal to *nulval (note that this parameter gives the address of the null pixel value, not the value itself). Similarly, when reading an image, 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.
The fpixel parameter in these routines is an array which gives the coordinate in each dimension of the first pixel to be read or w