CFITSIO supports several local FITS conventions which are not defined in the official FITS standard and which are not necessarily recognized or supported by other FITS software packages. Programmers should be cautious about using these features, especially if the FITS files that are produced are expected to be processed by other software systems which do not use the CFITSIO interface.
CFITSIO supports reading and writing FITS images or table columns containing 64-bit integer data values. Support for 64-bit integers was added to the official FITS Standard in December 2005. FITS 64-bit images have BITPIX = 64, and the 64-bit binary table columns have TFORMn = ’K’. CFITSIO also supports the ’Q’ variable-length array table column format which is analogous to the ’P’ column format except that the array descriptor is stored as a pair of 64-bit integers.
For the convenience of C programmers, the fitsio.h include file defines (with a typedef statement) the ’LONGLONG’ datatype to be equivalent to an appropriate 64-bit integer datatype on each platform. Since there is currently no universal standard for the name of the 64-bit integer datatype (it might be defined as ’long long’, ’long’, or ’__int64’ depending on the platform) C programmers may prefer to use the ’LONGLONG’ datatype when declaring or allocating 64-bit integer quantities when writing code which needs to run on multiple platforms. Note that CFITSIO will implicitly convert the datatype when reading or writing FITS 64-bit integer images and columns with data arrays of a different integer or floating point datatype, but there is an increased risk of loss of numerical precision or numerical overflow in this case.
The length of a standard FITS string keyword is limited to 68 characters because it must fit entirely within a single FITS header keyword record. In some instances it is necessary to encode strings longer than this limit, so CFITSIO supports a local convention in which the string value is continued over multiple keywords. This continuation convention uses an ampersand character at the end of each substring to indicate that it is continued on the next keyword, and the continuation keywords all have the name CONTINUE without an equal sign in column 9. The string value may be continued in this way over as many additional CONTINUE keywords as is required. The following lines illustrate this continuation convention which is used in the value of the STRKEY keyword:
LONGSTRN= 'OGIP 1.0' / The OGIP Long String Convention may be used. STRKEY = 'This is a very long string keyword&' / Optional Comment CONTINUE ' value that is continued over 3 keywords in the & ' CONTINUE 'FITS header.' / This is another optional comment.
It is recommended that the LONGSTRN keyword, as shown here, always be included in any HDU that uses this longstring convention as a warning to any software that must read the keywords. A routine called fits_write_key_longwarn has been provided in CFITSIO to write this keyword if it does not already exist.
This long string convention is supported by the following CFITSIO routines:
fits_write_key_longstr - write a long string keyword value
fits_insert_key_longstr - insert a long string keyword value
fits_modify_key_longstr - modify a long string keyword value
fits_update_key_longstr - modify a long string keyword value
fits_read_key_longstr - read a long string keyword value
fits_delete_key - delete a keyword
The fits_read_key_longstr routine is unique among all the CFITSIO routines in that it internally allocates memory for the long string value; all the other CFITSIO routines that deal with arrays require that the calling program pre-allocate adequate space to hold the array of data. Consequently, programs which use the fits_read_key_longstr routine must be careful to free the allocated memory for the string when it is no longer needed.
The following 2 routines also have limited support for this long string convention,
fits_modify_key_str - modify an existing string keyword value
fits_update_key_str - update a string keyword value
in that they will correctly overwrite an existing long string value, but the new string value is limited to a maximum of 68 characters in length.
The more commonly used CFITSIO routines to write string valued keywords (fits_update_key and fits_write_key) do not support this long string convention and only support strings up to 68 characters in length. This has been done deliberately to prevent programs from inadvertently writing keywords using this non-standard convention without the explicit intent of the programmer or user. The fits_write_key_longstr routine must be called instead to write long strings. This routine can also be used to write ordinary string values less than 68 characters in length.
CFITSIO supports 2 ways to specify that a character column in a binary table contains an array of fixed-length strings. The first way, which is officially supported by the FITS Standard document, uses the TDIMn keyword. For example, if TFORMn = ’60A’ and TDIMn = ’(12,5)’ then that column will be interpreted as containing an array of 5 strings, each 12 characters long.
CFITSIO also supports a local convention for the format of the TFORMn keyword value of the form ’rAw’ where ’r’ is an integer specifying the total width in characters of the column, and ’w’ is an integer specifying the (fixed) length of an individual unit string within the vector. For example, TFORM1 = ’120A10’ would indicate that the binary table column is 120 characters wide and consists of 12 10-character length strings. This convention is recognized by the CFITSIO routines that read or write strings in binary tables. The Binary Table definition document specifies that other optional characters may follow the data type code in the TFORM keyword, so this local convention is in compliance with the FITS standard although other FITS readers may not recognize this convention.
One limitation of the current FITS Standard is that it does not define a specific convention for recording the physical units of a keyword value. The TUNITn keyword can be used to specify the physical units of the values in a table column, but there is no analogous convention for keyword values. The comment field of the keyword is often used for this purpose, but the units are usually not specified in a well defined format that FITS readers can easily recognize and extract.
To solve this problem, CFITSIO uses a local convention in which the keyword units are enclosed in square brackets as the first token in the keyword comment field; more specifically, the opening square bracket immediately follows the slash ’/’ comment field delimiter and a single space character. The following examples illustrate keywords that use this convention:
EXPOSURE= 1800.0 / [s] elapsed exposure time V_HELIO = 16.23 / [km s**(-1)] heliocentric velocity LAMBDA = 5400. / [angstrom] central wavelength FLUX = 4.9033487787637465E-30 / [J/cm**2/s] average flux
In general, the units named in the IAU(1988) Style Guide are recommended, with the main exception that the preferred unit for angle is ’deg’ for degrees.
The fits_read_key_unit and fits_write_key_unit routines in CFITSIO read and write, respectively, the keyword unit strings in an existing keyword.
CFITSIO supports the HIERARCH keyword convention which allows keyword names that are longer than 8 characters. This convention was developed at the European Southern Observatory (ESO) and allows characters consisting of digits 0-9, upper case letters A-Z, the dash ’-’ and the underscore ’_’. The components of hierarchical keywords are separated by a single ASCII space charater. For instance:
HIERARCH ESO INS FOCU POS = -0.00002500 / Focus position
Basically, this convention uses the FITS keyword ’HIERARCH’ to indicate that this convention is being used, then the actual keyword name (’ESO INS FOCU POS’ in this example) begins in column 10. The equals sign marks the end of the keyword name and is followed by the usual value and comment fields just as in standard FITS keywords. Further details of this convention are described at http://fits.gsfc.nasa.gov/registry/hierarch_keyword.html and in Section 4.4 of the ESO Data Interface Control Document that is linked to from http://archive.eso.org/cms/tools-documentation/eso-data-interface-control.html.
This convention allows a broader range of keyword names than is allowed by the FITS Standard. Here are more examples of such keywords:
HIERARCH LONGKEYWORD = 47.5 / Keyword has > 8 characters HIERARCH LONG-KEY_WORD2 = 52.3 / Long keyword with hyphen, underscore and digit HIERARCH EARTH IS A STAR = F / Keyword contains embedded spaces
CFITSIO will transparently read and write these keywords, so application programs do not in general need to know anything about the specific implementation details of the HIERARCH convention. In particular, application programs do not need to specify the ‘HIERARCH’ part of the keyword name when reading or writing keywords (although it may be included if desired). When writing a keyword, CFITSIO first checks to see if the keyword name is legal as a standard FITS keyword (no more than 8 characters long and containing only letters, digits, or a minus sign or underscore). If so it writes it as a standard FITS keyword, otherwise it uses the hierarch convention to write the keyword. The maximum keyword name length is 67 characters, which leaves only 1 space for the value field. A more practical limit is about 40 characters, which leaves enough room for most keyword values. CFITSIO returns an error if there is not enough room for both the keyword name and the keyword value on the 80-character card, except for string-valued keywords which are simply truncated so that the closing quote character falls in column 80. A space is also required on either side of the equal sign.
CFITSIO supports a convention for compressing n-dimensional images and storing the resulting byte stream in a variable-length column in a FITS binary table. The general principle used in this convention is to first divide the n-dimensional image into a rectangular grid of subimages or ‘tiles’. Each tile is then compressed as a continuous block of data, and the resulting compressed byte stream is stored in a row of a variable length column in a FITS binary table. By dividing the image into tiles it is generally possible to extract and uncompress subsections of the image without having to uncompress the whole image. The default tiling pattern treats each row of a 2-dimensional image (or higher dimensional cube) as a tile, such that each tile contains NAXIS1 pixels (except the default with the HCOMPRESS algorithm is to compress the whole 2D image as a single tile). Any other rectangular tiling pattern may also be defined. In the case of relatively small images it may be sufficient to compress the entire image as a single tile, resulting in an output binary table with 1 row. In the case of 3-dimensional data cubes, it may be advantageous to treat each plane of the cube as a separate tile if application software typically needs to access the cube on a plane by plane basis.
See section 5.6 “Image Compression” for more information on using this tile-compressed image format.