This chapter describes the basic routines in the CFITSIO user interface that provide all the functions normally needed to read and write most FITS files. It is recommended that these routines be used for most applications and that the more advanced routines described in the next chapter only be used in special circumstances when necessary.
The following conventions are used in this chapter in the description of each function:
1. Most functions have 2 names: a long descriptive name and a short concise name. Both names are listed on the first line of the following descriptions, separated by a slash (/) character. Programmers may use either name in their programs but the long names are recommended to help document the code and make it easier to read.
2. A right arrow symbol (>) is used in the function descriptions to separate the input parameters from the output parameters in the definition of each routine. This symbol is not actually part of the C calling sequence.
3. The function parameters are defined in more detail in the alphabetical listing in Appendix B.
4. The first argument in almost all the functions is a pointer to a structure of type `fitsfile'. Memory for this structure is allocated by CFITSIO when the FITS file is first opened or created and is freed when the FITS file is closed.
5. The last argument in almost all the functions is the error status parameter. It must be equal to 0 on input, otherwise the function will immediately exit without doing anything. A non-zero output value indicates that an error occurred in the function. In most cases the status value is also returned as the value of the function itself.
void fits_get_errstatus / ffgerr (int status, > char *err_text)
int fits_read_errmsg / ffgmsg (char *err_msg)
void fits_report_error / ffrprt (FILE *stream, status)
void fits_write_errmark / ffpmrk (void) void fits_clear_errmark / ffcmrk (void) void fits_clear_errmsg / ffcmsg (void)
int fits_open_file / ffopen (fitsfile **fptr, char *filename, int iomode, > int *status) int fits_open_diskfile / ffdkopen (fitsfile **fptr, char *filename, int iomode, > int *status) int fits_open_data / ffdopn (fitsfile **fptr, char *filename, int iomode, > int *status) int fits_open_table / fftopn (fitsfile **fptr, char *filename, int iomode, > int *status) int fits_open_image / ffiopn (fitsfile **fptr, char *filename, int iomode, > int *status)
The iomode parameter determines the read/write access allowed in the
file and can have values of READONLY (0) or READWRITE (1). The filename
parameter gives the name of the file to be opened, followed by an
optional argument giving the name or index number of the extension
within the FITS file that should be moved to and opened (e.g.,
myfile.fits+3
or myfile.fits[3]
moves to the 3rd extension within
the file, and myfile.fits[events]
moves to the extension with the
keyword EXTNAME = 'EVENTS').
The fits_open_diskfile routine is similar to the fits_open_file routine except that it does not support the extended filename syntax in the input file name. This routine simply tries to open the specified input file on magnetic disk. This routine is mainly for use in cases where the filename (or directory path) contains square or curly bracket characters that would confuse the extended filename parser.
The fits_open_data routine is similar to the fits_open_file routine except that it will move to the first HDU containing significant data, if a HDU name or number to open was not explicitly specified as part of the filename. In this case, it will look for the first IMAGE HDU with NAXIS greater than 0, or the first table that does not contain the strings `GTI' (Good Time Interval extension) or `OBSTABLE' in the EXTNAME keyword value.
The fits_open_table and fits_open_image routines are similar to fits_open_data except they will move to the first significant table HDU or image HDU in the file, respectively, if a HDU name or number is not specified as part of the filename.
IRAF images (.imh format files) and raw binary data arrays may also be opened with READONLY access. CFITSIO will automatically test if the input file is an IRAF image, and if, so will convert it on the fly into a virtual FITS image before it is opened by the application program. If the input file is a raw binary data array of numbers, then the data type and dimensions of the array must be specified in square brackets following the name of the file (e.g. 'rawfile.dat[i512,512]' opens a 512 x 512 short integer image). See the `Extended File Name Syntax' chapter for more details on how to specify the raw file name. The raw file is converted on the fly into a virtual FITS image in memory that is then opened by the application program with READONLY access.
Programs can read the input file from the 'stdin' file stream if a dash character ('-') is given as the filename. Files can also be opened over the network using FTP or HTTP protocols by supplying the appropriate URL as the filename.
The input file can be modified in various ways to create a virtual file (usually stored in memory) that is then opened by the application program by supplying a filtering or binning specifier in square brackets following the filename. Some of the more common filtering methods are illustrated in the following paragraphs, but users should refer to the 'Extended File Name Syntax' chapter for a complete description of the full file filtering syntax.
When opening an image, a rectangular subset of the physical image may be opened by listing the first and last pixel in each dimension (and optional pixel skipping factor):
myimage.fits[101:200,301:400]
will create and open a 100x100 pixel virtual image of that section of
the physical image, and myimage.fits[*,-*]
opens a virtual image
that is the same size as the physical image but has been flipped in
the vertical direction.
When opening a table, the filtering syntax can be used to add or delete
columns or keywords in the virtual table:
myfile.fits[events][col !time; PI = PHA*1.2]
opens a virtual table in which the TIME column
has been deleted and a new PI column has been added with a value 1.2
times that of the PHA column. Similarly, one can filter a table to keep
only those rows that satisfy a selection criterion:
myfile.fits[events][pha > 50]
creates and opens a virtual table
containing only those rows with a PHA value greater than 50. A large
number of boolean and mathematical operators can be used in the
selection expression. One can also filter table rows using 'Good Time
Interval' extensions, and spatial region filters as in
myfile.fits[events][gtifilter()]
and
myfile.fits[events][regfilter( "stars.rng")]
.
Finally, table columns may be binned or histogrammed to generate a
virtual image. For example, myfile.fits[events][bin (X,Y)=4]
will
result in a 2-dimensional image calculated by binning the X and Y
columns in the event table with a bin size of 4 in each dimension. The
TLMINn and TLMAXn keywords will be used by default to determine the
range of the image.
A single program can open the same FITS file more than once and then treat the resulting fitsfile pointers as though they were completely independent FITS files. Using this facility, a program can open a FITS file twice, move to 2 different extensions within the file, and then read and write data in those extensions in any order.
int fits_create_file / ffinit (fitsfile **fptr, char *filename, > int *status) int fits_create_diskfile / ffdkinit (fitsfile **fptr, char *filename, > int *status)
An error will be returned if the specified file already exists, unless the filename is prefixed with an exclamation point (!). In that case CFITSIO will overwrite (delete) any existing file with the same name. Note that the exclamation point is a special UNIX character so if it is used on the command line it must be preceded by a backslash to force the UNIX shell to accept the character as part of the filename.
The output file will be written to the 'stdout' file stream if a dash character ('-') or the string 'stdout' is given as the filename. Similarly, '-.gz' or 'stdout.gz' will cause the file to be gzip compressed before it is written out to the stdout stream.
Optionally, the name of a template file that is used to define the structure of the new file may be specified in parentheses following the output file name. The template file may be another FITS file, in which case the new file, at the time it is opened, will be an exact copy of the template file except that the data structures (images and tables) will be filled with zeros. Alternatively, the template file may be an ASCII format text file containing directives that define the keywords to be created in each HDU of the file. See the 'Extended File Name Syntax' section for a complete description of the template file syntax.
The fits_create_diskfile routine is similar to the fits_create_file routine except that it does not support the extended filename syntax in the input file name. This routine simply tries to create the specified file on magnetic disk. This routine is mainly for use in cases where the filename (or directory path) contains square or curly bracket characters that would confuse the extended filename parser.
int fits_close_file / ffclos (fitsfile *fptr, > int *status) int fits_delete_file / ffdelt (fitsfile *fptr, > int *status)
int fits_file_name / ffflnm (fitsfile *fptr, > char *filename, int *status) int fits_file_mode / ffflmd (fitsfile *fptr, > int *iomode, int *status) int fits_url_type / ffurlt (fitsfile *fptr, > char *urltype, int *status)
The following functions perform operations on Header-Data Units (HDUs) as a whole.
int fits_movabs_hdu / ffmahd (fitsfile *fptr, int hdunum, > int *hdutype, int *status) int fits_movrel_hdu / ffmrhd (fitsfile *fptr, int nmove, > int *hdutype, int *status) int fits_movnam_hdu / ffmnhd (fitsfile *fptr, int hdutype, char *extname, int extver, > int *status)
int fits_get_num_hdus / ffthdu (fitsfile *fptr, > int *hdunum, int *status)
int fits_get_hdu_num / ffghdn (fitsfile *fptr, > int *hdunum)
int fits_get_hdu_type / ffghdt (fitsfile *fptr, > int *hdutype, int *status)
int fits_copy_file / ffcpfl (fitsfile *infptr, fitsfile *outfptr, int previous, int current, int following, > int *status)
int fits_copy_hdu / ffcopy (fitsfile *infptr, fitsfile *outfptr, int morekeys, > int *status)
int fits_copy_header / ffcphd (fitsfile *infptr, fitsfile *outfptr, > int *status)
int fits_delete_hdu / ffdhdu (fitsfile *fptr, > int *hdutype, int *status)
These routines read or write keywords in the Current Header Unit (CHU). Wild card characters (*, ?, or #) may be used when specifying the name of the keyword to be read: a '?' will match any single character at that position in the keyword name and a '*' will match any length (including zero) string of characters. The '#' character will match any consecutive string of decimal digits (0 - 9). When a wild card is used the routine will only search for a match from the current header position to the end of the header and will not resume the search from the top of the header back to the original header position as is done when no wildcards are included in the keyword name. The fits_read_record routine may be used to set the starting position when doing wild card searchs. A status value of KEY_NO_EXIST is returned if the specified keyword to be read is not found in the header.
int fits_get_hdrspace / ffghsp (fitsfile *fptr, > int *keysexist, int *morekeys, int *status)
The second routine returns the keyword value as a character string (a literal copy of what is in the value field) regardless of the intrinsic data type of the keyword. The third routine returns the entire 80-character header record of the keyword, with any trailing blank characters stripped off.
If a NULL comment pointer is supplied then the comment string will not be returned.
int fits_read_key / ffgky (fitsfile *fptr, int datatype, char *keyname, > DTYPE *value, char *comment, int *status) int fits_read_keyword / ffgkey (fitsfile *fptr, char *keyname, > char *value, char *comment, int *status) int fits_read_card / ffgcrd (fitsfile *fptr, char *keyname, > char *card, int *status)
int fits_read_record / ffgrec (fitsfile *fptr, int keynum, > char *card, int *status) int fits_read_keyn / ffgkyn (fitsfile *fptr, int keynum, > char *keyname, char *value, char *comment, int *status)
int fits_find_nextkey / ffgnxk (fitsfile *fptr, char **inclist, int ninc, char **exclist, int nexc, > char *card, int *status)
VELOCITY= 12.3 / [km/s] orbital speed int fits_read_key_unit / ffgunt (fitsfile *fptr, char *keyname, > char *unit, int *status)
Selected keywords may be excluded from the returned character string. If the second parameter (nocomments) is TRUE (nonzero) then any COMMENT, HISTORY, or blank keywords in the header will not be copied to the output string.
The 'exclist' parameter may be used to supply a list of keywords that are to be excluded from the output character string. Wild card characters (*, ?, and #) may be used in the excluded keyword names. If no additional keywords are to be excluded, then set nexc = 0 and specify NULL for the the **header parameter.
int fits_hdr2str (fitsfile *fptr, int nocomments, char **exclist, int nexc, > char **header, int *nkeys, int *status)
int fits_write_key / ffpky (fitsfile *fptr, int datatype, char *keyname, DTYPE *value, char *comment, > int *status) int fits_update_key / ffuky (fitsfile *fptr, int datatype, char *keyname, DTYPE *value, char *comment, > int *status)
int fits_write_key_null / ffpkyu (fitsfile *fptr, char *keyname, char *comment, > int *status) int fits_update_key_null / ffukyu (fitsfile *fptr, char *keyname, char *comment, > int *status)
int fits_write_comment / ffpcom (fitsfile *fptr, char *comment, > int *status) int fits_write_history / ffphis (fitsfile *fptr, char *history, > int *status)
int fits_write_date / ffpdat (fitsfile *fptr, > int *status)
int fits_write_record / ffprec (fitsfile *fptr, char *card, > int *status)
int fits_update_card / ffucrd (fitsfile *fptr, char *keyname, char *card, > int *status)
int fits_modify_comment / ffmcom (fitsfile *fptr, char *keyname, char *comment, > int *status)
VELOCITY= 12.3 / [km/s] orbital speed int fits_write_key_unit / ffpunt (fitsfile *fptr, char *keyname, char *unit, > int *status)
int fits_modify_name / ffmnam (fitsfile *fptr, char *oldname, char *newname, > int *status)
int fits_delete_record / ffdrec (fitsfile *fptr, int keynum, > int *status) int fits_delete_key / ffdkey (fitsfile *fptr, char *keyname, > int *status)
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 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, 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.
int fits_get_img_type / ffgidt (fitsfile *fptr, > int *bitpix, int *status) int fits_get_img_equivtype / ffgiet (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_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)
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)
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 tranlated 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)
int fits_write_subset / ffpss (fitsfile *fptr, int datatype, long *fpixel, long *lpixel, DTYPE *array, > int *status)
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);
int fits_write_null_img / ffpprn (fitsfile *fptr, LONGLONG firstelem, LONGLONG nelements, > int *status)
int fits_read_subset / ffgsv (fitsfile *fptr, int datatype, long *fpixel, long *lpixel, long *inc, DTYPE *nulval, > DTYPE *array, int *anynul, int *status)
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 (= 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)
CFITSIO now transparently supports 2 types of image compression:
1) The entire FITS file may be externally compressed with the gzip or Unix compress algorithm, producing a *.gz or *.Z file, respectively. When reading compressed files of this type, CFITSIO first uncompresses the entire file into memory before performing the requested read operations. Output files can be directly written in the gzip compressed format if the user-specified filename ends with `.gz'. In this case, CFITSIO initially writes the uncompressed file in memory and then compresses it and writes it to disk when the FITS file is closed, thus saving user disk space. Read and write access to these compressed FITS files is generally quite fast; the main limitation is that there must be enough available memory (or swap space) to hold the entire uncompressed FITS file.
2) CFITSIO also supports a newer image compression format in which the image is divided into a grid of rectangular tiles, and each tile of pixels is individually compressed. The compressed tiles are stored in rows of a variable length array column in a FITS binary table, but CFITSIO recognizes that the binary table extension contains an image and treats it as if it were an IMAGE extension. This tile-compressed format is especially well suited for compressing very large images because a) the FITS header keywords remain uncompressed for rapid read access, and because b) it is possible to extract and uncompress sections of the image without having to uncompress the entire image. This format is also much more effective in compressing floating point images (using a lossy compression algorithm) than simply compressing the image using gzip or compress.
A detailed description of this format is available at:
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/ compression/compress_image.html
The N-dimensional FITS image can be divided into any desired rectangular grid of compression tiles. By default the tiles are chosen to correspond to the rows of the image, each containing NAXIS1 pixels. For example, a 800 x 800 x 4 pixel data cube would be divided in to 3200 tiles containing 800 pixels each by default. Alternatively, this data cube could be divided into 256 tiles that are each 100 X 100 X 1 pixels in size, or 4 tiles containing 800 x 800 X 1 pixels, or a single tile containing the entire data cube. Note that the image dimensions are not required to be an integer multiple of the tile dimensions, so, for example, this data cube could also be divided into 250 X 200 pixel tiles, in which case the last tile in each row would only contain 50 X 200 pixels.
Currently, 3 image compression algorithms are supported: Rice, GZIP, and PLIO. Rice and GZIP are general purpose algorithms that can be used to compress almost any image. The PLIO algorithm, on the other hand, is more specialized and was developed for use in IRAF to store pixel data quality masks. It is designed to only work on images containing positive integers with values up to about 2**24. Other image compression algorithms may be supported in the future.
The 3 supported image compression algorithms are all 'loss-less' when applied to integer FITS images; the pixel values are preserved exactly with no loss of information during the compression and uncompression process. Floating point FITS images (which have BITPIX = -32 or -64) are first quantized into scaled integer pixel values before being compressed. This technique produces much higher compression factors than simply using GZIP to compress the image, but it also means that the original floating value pixel values may not be precisely returned when the image is uncompressed. When done properly, this only discards the 'noise' from the floating point values without losing any significant information. The amount of noise that is discarded can be controlled by the 'noise_bits' compression parameter.
No special action is required to read tile-compressed images because all the CFITSIO routines that read normal uncompressed FITS images can also read images in the tile-compressed format; CFITSIO essentially treats the binary table that contains the compressed tiles as if it were an IMAGE extension.
When creating (writing) a new image with CFITSIO, a normal uncompressed FITS primary array or IMAGE extension will be written unless the tile-compressed format has been specified in 1 of 2 possible ways:
1) At run time, when specifying the name of the output FITS file to be created at run time, the user can indicate that images should be written in tile-compressed format by enclosing the compression parameters in square brackets following the root disk file name. The `imcopy' example program that included with the CFITSIO distribution can be used for this purpose to compress or uncompress images. Here are some examples of the extended file name syntax for specifying tile-compressed output images:
myfile.fit[compress] - use the default compression algorithm (Rice) and the default tile size (row by row) myfile.fit[compress GZIP] - use the specified compression algorithm; myfile.fit[compress Rice] only the first letter of the algorithm myfile.fit[compress PLIO] name is required. myfile.fit[compress R 100,100] - use Rice compression and 100 x 100 pixel tile size myfile.fit[compress R 100,100;2] - as above, and also use noisebits = 2
2) Before calling the CFITSIO routine to write the image header keywords (e.g., fits_create_image) the programmer can call the routines described below to specify the compression algorithm and the tiling pattern that is to be used. There are 3 routines for specifying the various compression parameters and 3 corresponding routines to return the current values of the parameters:
int fits_set_compression_type(fitsfile *fptr, int comptype, int *status) int fits_set_tile_dim(fitsfile *fptr, int ndim, long *tilesize, int *status) int fits_set_noise_bits(fitsfile *fptr, int noisebits, int *status) int fits_get_compression_type(fitsfile *fptr, int *comptype, int *status) int fits_get_tile_dim(fitsfile *fptr, int ndim, long *tilesize, int *status) int fits_get_noise_bits(fitsfile *fptr, int *noisebits, int *status)
3 symbolic constants are defined for use as the value of the `comptype' parameter: GZIP_1, RICE_1, or PLIO_1. Entering NULL for comptype will turn off the tile-compression and cause normal FITS images to be written.
The 'noisebits' parameter is only used when compressing floating point images. The default value is 4. Decreasing the value of noisebits will improve the overall compression efficiency at the expense of losing more information.
A small example program called 'imcopy' is included with CFITSIO that can be used to compress (or uncompress) any FITS image. This program can be used to experiment with the various compression options on existing FITS images as shown in these examples:
1) imcopy infile.fit 'outfile.fit[compress]' This will use the default compression algorithm (Rice) and the default tile size (row by row) 2) imcopy infile.fit 'outfile.fit[compress GZIP]' This will use the GZIP compression algorithm and the default tile size (row by row). The allowed compression algorithms are Rice, GZIP, and PLIO. Only the first letter of the algorithm name needs to be specified. 3) imcopy infile.fit 'outfile.fit[compress G 100,100]' This will use the GZIP compression algorithm and 100 X 100 pixel tiles. 4) imcopy infile.fit 'outfile.fit[compress R 100,100; 4]' This will use the Rice compression algorithm, 100 X 100 pixel tiles, and noise_bits = 4 (assuming the input image has a floating point data type). Decreasing the value of noisebits will improve the overall compression efficiency at the expense of losing more information. 5) imcopy infile.fit outfile.fit If the input file is in tile-compressed format, then it will be uncompressed to the output file. Otherwise, it simply copies the input image to the output image. 6) imcopy 'infile.fit[1001:1500,2001:2500]' outfile.fit This extracts a 500 X 500 pixel section of the much larger input image (which may be in tile-compressed format). The output is a normal uncompressed FITS image. 7) imcopy 'infile.fit[1001:1500,2001:2500]' outfile.fit.gz Same as above, except the output file is externally compressed using the gzip algorithm.
These routines perform read and write operations on columns of data in FITS ASCII or Binary tables. Note that in the following discussions, the first row and column in a table is at position 1 not 0.
Users should also read the following chapter on the CFITSIO iterator function which provides a more `object oriented' method of reading and writing table columns. 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.
int fits_create_tbl / ffcrtb (fitsfile *fptr, int tbltype, LONGLONG naxis2, int tfields, char *ttype[], char *tform[], char *tunit[], char *extname, int *status)
int fits_get_num_rows / ffgnrw (fitsfile *fptr, > long *nrows, int *status); int fits_get_num_rowsll / ffgnrwll (fitsfile *fptr, > LONGLONG *nrows, int *status); int fits_get_num_cols / ffgncl (fitsfile *fptr, > int *ncols, int *status);
The input column name template may be either the exact name of the column to be searched for, or it may contain wild card characters (*, ?, or #), or it may contain the integer number of the desired column (with the first column = 1). The `*' wild card character matches any sequence of characters (including zero characters) and the `?' character matches any single character. The # wildcard will match any consecutive string of decimal digits (0-9). If more than one column name in the table matches the template string, then the first match is returned and the status value will be set to COL_NOT_UNIQUE as a warning that a unique match was not found. To find the other cases that match the template, call the routine again leaving the input status value equal to COL_NOT_UNIQUE and the next matching name will then be returned. Repeat this process until a status = COL_NOT_FOUND is returned.
The FITS Standard recommends that only letters, digits, and the underscore character be used in column names (with no embedded spaces). Trailing blank characters are not significant. It is recommended that all the column names in a given table be unique within the first 8 characters, and strongly recommended that the names be unique within the first 16 characters.
int fits_get_colnum / ffgcno (fitsfile *fptr, int casesen, char *templt, > int *colnum, int *status) int fits_get_colname / ffgcnn (fitsfile *fptr, int casesen, char *templt, > char *colname, int *colnum, int *status)
The 'repeat' parameter returns the vector repeat count on the binary table TFORMn keyword value. (ASCII table columns always have repeat = 1). The 'width' parameter returns the width in bytes of a single column element (e.g., a '10D' binary table column will have width = 8, an ASCII table 'F12.2' column will have width = 12, and a binary table'60A' character string column will have width = 60); Note that this routine supports the local convention for specifying arrays of fixed length strings within a binary table character column using the syntax TFORM = 'rAw' where 'r' is the total number of characters (= the width of the column) and 'w' is the width of a unit string within the column. Thus if the column has TFORM = '60A12' then this means that each row of the table contains 5 12-character substrings within the 60-character field, and thus in this case this routine will return typecode = TSTRING, repeat = 60, and width = 12. The number of substings in any binary table character string field can be calculated by (repeat/width). A null pointer may be given for any of the output parameters that are not needed.
The second routine, fit_get_eqcoltype is similar except that in the case of scaled integer columns it returns the 'equivalent' data type that is needed to store the scaled values, and not necessarily the physical data type of the unscaled values as stored in the FITS table. For example if a '1I' column in a binary table has TSCALn = 1 and TZEROn = 32768, then this column effectively contains unsigned short integer values, and thus the returned value of typecode will be TUSHORT, not TSHORT. Similarly, if a column has TTYPEn = '1I' and TSCALn = 0.12, then the returned typecode will be TFLOAT.
int fits_get_coltype / ffgtcl (fitsfile *fptr, int colnum, > int *typecode, long *repeat, long *width, int *status) int fits_get_coltypell / ffgtclll (fitsfile *fptr, int colnum, > int *typecode, LONGLONG *repeat, LONGLONG *width, int *status) int fits_get_eqcoltype / ffeqty (fitsfile *fptr, int colnum, > int *typecode, long *repeat, long *width, int *status) int fits_get_eqcoltypell / ffeqtyll (fitsfile *fptr, int colnum, > int *typecode, LONGLONG *repeat, LONGLONG *width, int *status)
int fits_get_col_display_width / ffgcdw (fitsfile *fptr, int colnum, > int *dispwidth, int *status)
int fits_read_tdim / ffgtdm (fitsfile *fptr, int colnum, int maxdim, > int *naxis, long *naxes, int *status) int fits_read_tdimll / ffgtdmll (fitsfile *fptr, int colnum, int maxdim, > int *naxis, LONGLONG *naxes, int *status)
int fits_decode_tdim / ffdtdm (fitsfile *fptr, char *tdimstr, int colnum, int maxdim, > int *naxis, long *naxes, int *status) int fits_decode_tdimll / ffdtdmll (fitsfile *fptr, char *tdimstr, int colnum, int maxdim, > int *naxis, LONGLONG *naxes, int *status)
int fits_write_tdim / ffptdm (fitsfile *fptr, int colnum, int naxis, long *naxes, > int *status) int fits_write_tdimll / ffptdmll (fitsfile *fptr, int colnum, int naxis, LONGLONG *naxes, > int *status)
int fits_insert_rows / ffirow (fitsfile *fptr, LONGLONG firstrow, LONGLONG nrows, > int *status) int fits_delete_rows / ffdrow (fitsfile *fptr, LONGLONG firstrow, LONGLONG nrows, > int *status) int fits_delete_rowrange / ffdrrg (fitsfile *fptr, char *rangelist, > int *status) int fits_delete_rowlist / ffdrws (fitsfile *fptr, long *rowlist, long nrows, > int *status) int fits_delete_rowlistll / ffdrwsll (fitsfile *fptr, LONGLONG *rowlist, LONGLONG nrows, > int *status)
int fits_insert_col / fficol (fitsfile *fptr, int colnum, char *ttype, char *tform, > int *status) int fits_insert_cols / fficls (fitsfile *fptr, int colnum, int ncols, char **ttype, char **tform, > int *status) int fits_delete_col / ffdcol(fitsfile *fptr, int colnum, > int *status)
int fits_copy_col / ffcpcl (fitsfile *infptr, fitsfile *outfptr, int incolnum, int outcolnum, int create_col, > int *status);
int fits_modify_vector_len / ffmvec (fitsfile *fptr, int colnum, LONGLONG newveclen, > int *status)
The following routines write or read data values in the current ASCII or binary table extension. If a write operation extends beyond the current size of the table, then the number of rows in the table will automatically be increased and the NAXIS2 keyword value will be updated. Attempts to read beyond the end of the table will result in an error.
Automatic data type conversion is performed for numerical data types (only) if the data type of the column (defined by the TFORMn keyword) differs from the data type of the array in the calling routine. ASCII and binary tables support the following data type values: TSTRING, TBYTE, TSBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TFLOAT, or TDOUBLE. Binary tables also support TLOGICAL (internally mapped to the `char' data type), TCOMPLEX, and TDBLCOMPLEX.
Individual bits in a binary table 'X' or 'B' column may be read/written to/from a *char array by specifying the TBIT datatype. The *char array will be interpreted as an array of logical TRUE (1) or FALSE (0) values that correspond to the value of each bit in the FITS 'X' or 'B' column. Alternatively, the values in a binary table 'X' column may be read/written 8 bits at a time to/from an array of 8-bit integers by specifying the TBYTE datatype.
Note that within the context of these routines, the TSTRING data type corresponds to a C 'char**' data type, i.e., a pointer to an array of pointers to an array of characters. This is different from the keyword reading and writing routines where TSTRING corresponds to a C 'char*' data type, i.e., a single pointer to an array of characters. When reading strings from a table, the char arrays obviously must have been allocated long enough to hold the whole FITS table string.
Numerical data values are automatically scaled by the TSCALn and TZEROn keyword values (if they exist).
In the case of binary tables with vector elements, the 'felem' parameter defines the starting element (beginning with 1, not 0) within the cell (a cell is defined as the intersection of a row and a column and may contain a single value or a vector of values). The felem parameter is ignored when dealing with ASCII tables. Similarly, in the case of binary tables the 'nelements' parameter specifies the total number of vector values to be read or written (continuing on subsequent rows if required) and not the number of table cells.
The first routine simply writes the array of values to the FITS file (doing data type conversion if necessary) whereas the second routine will substitute the appropriate FITS null value for all elements which are equal to the input value of nulval (note that this parameter gives the address of nulval, not the null value itself). For integer columns the FITS null value is defined by the TNULLn keyword (an error is returned if the keyword doesn't exist). For floating point columns 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 the first routine. The third routine simply writes undefined pixel values to the column. The fourth routine fills every column in the table with null values, in the specified rows (ignoring any columns that do not have a defined null value).
int fits_write_col / ffpcl (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem, LONGLONG nelements, DTYPE *array, > int *status) int fits_write_colnull / ffpcn (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem, LONGLONG nelements, DTYPE *array, DTYPE *nulval, > int *status) int fits_write_col_null / ffpclu (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem, LONGLONG nelements, > int *status) int fits_write_nullrows / ffprwu (fitsfile *fptr, LONGLONG firstrow, LONGLONG nelements, > int *status)
Any column, regardless of it's intrinsic data type, may be read as a string. It should be noted however that reading a numeric column as a string is 10 - 100 times slower than reading the same column as a number due to the large overhead in constructing the formatted strings. The display format of the returned strings will be determined by the TDISPn keyword, if it exists, otherwise by the data type of the column. The length of the returned strings (not including the null terminating character) can be determined with the fits_get_col_display_width routine. The following TDISPn display formats are currently supported:
Iw.m Integer Ow.m Octal integer Zw.m Hexadecimal integer Fw.d Fixed floating point Ew.d Exponential floating point Dw.d Exponential floating point Gw.d General; uses Fw.d if significance not lost, else Ew.d
where w is the width in characters of the displayed values, m is the minimum number of digits displayed, and d is the number of digits to the right of the decimal. The .m field is optional.
int fits_read_col / ffgcv (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem, LONGLONG nelements, DTYPE *nulval, DTYPE *array, int *anynul, int *status) int fits_read_colnull / ffgcf (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem, LONGLONG nelements, DTYPE *array, char *nullarray, int *anynul, int *status)
These routines all parse and evaluate an input string containing a user defined arithmetic expression. The first 3 routines select rows in a FITS table, based on whether the expression evaluates to true (not equal to zero) or false (zero). The other routines evaluate the expression and calculate a value for each row of the table. The allowed expression syntax is described in the row filter section in the `Extended File Name Syntax' chapter of this document. The expression may also be written to a text file, and the name of the file, prepended with a '@' character may be supplied for the 'expr' parameter (e.g. '@filename.txt'). The expression in the file can be arbitrarily complex and extend over multiple lines of the file. Lines that begin with 2 slash characters ('//') will be ignored and may be used to add comments to the file.
int fits_find_rows / fffrow (fitsfile *fptr, char *expr, long firstrow, long nrows, > long *n_good_rows, char *row_status, int *status)
int fits_find_first_row / ffffrw (fitsfile *fptr, char *expr, > long *rownum, int *status)
int fits_select_rows / ffsrow (fitsfile *infptr, fitsfile *outfptr, char *expr, > int *status )
int fits_calc_rows / ffcrow (fitsfile *fptr, int datatype, char *expr, long firstrow, long nelements, void *nulval, > void *array, int *anynul, int *status)
int fits_calculator / ffcalc (fitsfile *infptr, char *expr, fitsfile *outfptr, char *parName, char *parInfo, > int *status)
int fits_calculator_rng / ffcalc_rng (fitsfile *infptr, char *expr, fitsfile *outfptr, char *parName, char *parInfo, int nranges, long *firstrow, long *lastrow > int *status)
int fits_test_expr / fftexp (fitsfile *fptr, char *expr, > int *datatype, long *nelem, int *naxis, long *naxes, int *status)
The following routines either compute or validate the checksums for the CHDU. The DATASUM keyword is used to store the numerical value of the 32-bit, 1's complement checksum for the data unit alone. If there is no data unit then the value is set to zero. The numerical value is stored as an ASCII string of digits, enclosed in quotes, because the value may be too large to represent as a 32-bit signed integer. The CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the checksum for the entire HDU. Storing the complement, rather than the actual checksum, forces the checksum for the whole HDU to equal zero. If the file has been modified since the checksums were computed, then the HDU checksum will usually not equal zero. These checksum keyword conventions are based on a paper by Rob Seaman published in the proceedings of the ADASS IV conference in Baltimore in November 1994 and a later revision in June 1995. See Appendix B for the definition of the parameters used in these routines.
int fits_write_chksum / ffpcks (fitsfile *fptr, > int *status)
int fits_update_chksum / ffupck (fitsfile *fptr, > int *status)
int fits_verify_chksum / ffvcks (fitsfile *fptr, > int *dataok, int *hduok, int *status)
int fits_get_chksum/ /ffgcks (fitsfile *fptr, > unsigned long *datasum, unsigned long *hdusum, int *status)
int fits_encode_chksum / ffesum (unsigned long sum, int complm, > char *ascii);
unsigned long fits_decode_chksum / ffdsum (char *ascii, int complm, > unsigned long *sum);
The following routines help to construct or parse the FITS date/time strings. Starting in the year 2000, the FITS DATE keyword values (and the values of other `DATE-' keywords) must have the form 'YYYY-MM-DD' (date only) or 'YYYY-MM-DDThh:mm:ss.ddd...' (date and time) where the number of decimal places in the seconds value is optional. These times are in UTC. The older 'dd/mm/yy' date format may not be used for dates after 01 January 2000. See Appendix B for the definition of the parameters used in these routines.
int fits_get_system_date/ffgsdt ( > int *day, int *month, int *year, int *status )
int fits_get_system_time/ffgstm (> char *datestr, int *timeref, int *status)
int fits_date2str/ffdt2s (int year, int month, int day, > char *datestr, int *status)
int fits_time2str/fftm2s (int year, int month, int day, int hour, int minute, double second, int decimals, > char *datestr, int *status)
int fits_str2date/ffs2dt (char *datestr, > int *year, int *month, int *day, int *status)
int fits_str2time/ffs2tm (char *datestr, > int *year, int *month, int *day, int *hour, int *minute, double *second, int *status)
The following utility routines may be useful for certain applications.
float fits_get_version / ffvers ( > float *version)
void fits_write_errmsg / ffpmsg (char *err_msg)
void fits_uppercase / ffupch (char *string)
void fits_compare_str / ffcmps (char *templt, char *string, int casesen, > int *match, int *exact)
This routine is similar to the ANSI C 'strtok' function:
The first call to fits_split_names has a non-null input string. It finds the first name in the string and terminates it by overwriting the next character of the string with a null terminator and returns a pointer to the name. Each subsequent call, indicated by a NULL value of the input string, returns the next name, searching from just past the end of the previous name. It returns NULL when no further names are found.
char *fits_split_names(char *namelist)
The following example shows how a string would be split into 3 names:
myfile[1][bin (x,y)=4], file2.fits file3.fits ^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ 1st name 2nd name 3rd name
int fits_test_keyword / fftkey (char *keyname, > int *status) int fits_test_record / fftrec (char *card, > int *status)
int fits_null_check / ffnchk (char *card, > int *status)
int fits_get_keyname / ffgknm (char *card, > char *keyname, int *keylength, int *status)
int fits_parse_value / ffpsvc (char *card, > char *value, char *comment, int *status)
int fits_make_keyn / ffkeyn (char *keyroot, int value, > char *keyname, int *status)
int fits_make_nkey / ffnkey (int value, char *keyroot, > char *keyname, int *status)
int fits_get_keytype / ffdtyp (char *value, > char *dtype, int *status)
Class Value Keywords TYP_STRUC_KEY 10 SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED, GROUPS, PCOUNT, GCOUNT, END XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP, and the first 4 COMMENT keywords in the primary array that define the FITS format. TYP_CMPRS_KEY 20 The experimental keywords used in the compressed image format ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn, ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK TYP_SCAL_KEY 30 BSCALE, BZERO, TSCALn, TZEROn TYP_NULL_KEY 40 BLANK, TNULLn TYP_DIM_KEY 50 TDIMn TYP_RANG_KEY 60 TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX TYP_UNIT_KEY 70 BUNIT, TUNITn TYP_DISP_KEY 80 TDISPn TYP_HDUID_KEY 90 EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL TYP_CKSUM_KEY 100 CHECKSUM, DATASUM TYP_WCS_KEY 110 WCS keywords defined in the the WCS papers, including: CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn CDj_is, PVj_ms, LONPOLEs, LATPOLEs TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn, TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn, iCRPns, jiCDn, jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn (i,j,m,n are integers, s is any letter) TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs, DATE-OBS TYP_COMM_KEY 130 COMMENT, HISTORY, (blank keyword) TYP_CONT_KEY 140 CONTINUE TYP_USER_KEY 150 all other keywords int fits_get_keyclass / ffgkcl (char *card)
int fits_binary_tform / ffbnfm (char *tform, > int *typecode, long *repeat, long *width, int *status) int fits_binary_tformll / ffbnfmll (char *tform, > int *typecode, LONGLONG *repeat, long *width, int *status)
int fits_ascii_tform / ffasfm (char *tform, > int *typecode, long *width, int *decimals, int *status)
int fits_get_tbcol / ffgabc (int tfields, char **tform, int space, > long *rowlen, long *tbcol, int *status)
int fits_parse_template / ffgthd (char *templt, > char *card, int *keytype, int *status)
The input templt character string generally should contain 3 tokens: (1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string. The TEMPLATE string must adhere to the following format:
The keytype output parameter indicates how the returned CARD string should be interpreted:
keytype interpretation ------- ------------------------------------------------- -2 Rename the keyword with name = the first 8 characters of CARD to the new name given in characters 41 - 48 of CARD. -1 delete the keyword with this name from the FITS header. 0 append the CARD string to the FITS header if the keyword does not already exist, otherwise update the keyword value and/or comment field if is already exists. 1 This is a HISTORY or COMMENT keyword; append it to the header 2 END record; do not explicitly write it to the FITS file.
EXAMPLES: The following lines illustrate valid input template strings:
INTVAL 7 / This is an integer keyword RVAL 34.6 / This is a floating point keyword EVAL=-12.45E-03 / This is a floating point keyword in exponential notation lval F / This is a boolean keyword This is a comment keyword with a blank keyword name SVAL1 = 'Hello world' / this is a string keyword SVAL2 '123.5' this is also a string keyword sval3 123+ / this is also a string keyword with the value '123+ ' # the following template line deletes the DATE keyword - DATE # the following template line modifies the NAME keyword to OBJECT - NAME OBJECT
The user passes an array of patterns to be matched. Input pattern number i is pattern[i][0], and output pattern number i is pattern[i][1]. Keywords are matched against the input patterns. If a match is found then the keyword is re-written according to the output pattern.
Order is important. The first match is accepted. The fastest match will be made when templates with the same first character are grouped together.
Several characters have special meanings:
i,j - single digits, preserved in output template n - column number of one or more digits, preserved in output template m - generic number of one or more digits, preserved in output template a - coordinate designator, preserved in output template # - number of one or more digits ? - any character * - only allowed in first character position, to match all keywords; only useful as last pattern in the list
i, j, n, and m are returned by the routine.
For example, the input pattern "iCTYPn" will match "1CTYP5" (if n_value is 5); the output pattern "CTYPEi" will be re-written as "CTYPE1". Notice that "i" is preserved.
The following output patterns are special:
"-" - do not copy a keyword that matches the corresponding input pattern
"+" - copy the input unchanged
The inrec string could be just the 8-char keyword name, or the entire 80-char header record. Characters 9 - 80 in the input string simply get appended to the translated keyword name.
If n_range = 0, then only keywords with 'n' equal to n_value will be considered as a pattern match. If n_range = +1, then all values of 'n' greater than or equal to n_value will be a match, and if -1, then values of 'n' less than or equal to n_value will match.
int fits_translate_keyword( char *inrec, /* I - input string */ char *outrec, /* O - output converted string, or */ /* a null string if input does not */ /* match any of the patterns */ char *patterns[][2],/* I - pointer to input / output string */ /* templates */ int npat, /* I - number of templates passed */ int n_value, /* I - base 'n' template value of interest */ int n_offset, /* I - offset to be applied to the 'n' */ /* value in the output string */ int n_range, /* I - controls range of 'n' template */ /* values of interest (-1,0, or +1) */ int *pat_num, /* O - matched pattern number (0 based) or -1 */ int *i, /* O - value of i, if any, else 0 */ int *j, /* O - value of j, if any, else 0 */ int *m, /* O - value of m, if any, else 0 */ int *n, /* O - value of n, if any, else 0 */ int *status) /* IO - error status */
char *patterns[][2] = {{"TSCALn", "BSCALE" }, /* Standard FITS keywords */ {"TZEROn", "BZERO" }, {"TUNITn", "BUNIT" }, {"TNULLn", "BLANK" }, {"TDMINn", "DATAMIN" }, {"TDMAXn", "DATAMAX" }, {"iCTYPn", "CTYPEi" }, /* Coordinate labels */ {"iCTYna", "CTYPEia" }, {"iCUNIn", "CUNITi" }, /* Coordinate units */ {"iCUNna", "CUNITia" }, {"iCRVLn", "CRVALi" }, /* WCS keywords */ {"iCRVna", "CRVALia" }, {"iCDLTn", "CDELTi" }, {"iCDEna", "CDELTia" }, {"iCRPXn", "CRPIXi" }, {"iCRPna", "CRPIXia" }, {"ijPCna", "PCi_ja" }, {"ijCDna", "CDi_ja" }, {"iVn_ma", "PVi_ma" }, {"iSn_ma", "PSi_ma" }, {"iCRDna", "CRDERia" }, {"iCSYna", "CSYERia" }, {"iCROTn", "CROTAi" }, {"WCAXna", "WCSAXESa"}, {"WCSNna", "WCSNAMEa"}};
int fits_translate_keywords( fitsfile *infptr, /* I - pointer to input HDU */ fitsfile *outfptr, /* I - pointer to output HDU */ int firstkey, /* I - first HDU record number to start with */ char *patterns[][2],/* I - pointer to input / output keyword templates */ int npat, /* I - number of templates passed */ int n_value, /* I - base 'n' template value of interest */ int n_offset, /* I - offset to be applied to the 'n' */ /* value in the output string */ int n_range, /* I - controls range of 'n' template */ /* values of interest (-1,0, or +1) */ int *status) /* IO - error status */
int fits_parse_range / ffrwrg(char *rowlist, LONGLONG maxrows, int maxranges, > int *numranges, long *rangemin, long *rangemax, int *status) int fits_parse_rangell / ffrwrgll(char *rowlist, LONGLONG maxrows, int maxranges, > int *numranges, LONGLONG *rangemin, LONGLONG *rangemax, int *status)
int ffchfl(fitsfile *fptr, > int *status)
int ffcdfl(fitsfile *fptr, > int *status)