Chapter 12 Local FITS Conventions
CFITSIO supports several local FITS conventions which are not
defined in the official NOST 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.
12.1 64-Bit Long Integers
CFITSIO can read and write FITS images or table columns containing
64-bit integer data values. This data type is not recognized in the
official FITS Standard definition document, but it is likely that FITS
will eventually support this data type, especially as computers that
run 64-bit operating systems become more common. Support for reading
and writing 64-bit integers in CFITSIO can be controlled with the
#define statement at the beginning of the fitsio2.h file by setting
SUPPORT_64BIT_INTEGERS to 1 (enable) or 0 (disable).
Under the convention used by CFITSIO, FITS 64-bit images have BITPIX =
64, and the 64-bit binary table columns have TFORMn = 'K'. The use of
these data types on platforms where the size of a 'long' (or 'longlong')
integer = 8 bytes is rather intuitive. CFITSIO will write 64-bit
'long' variable values to the FITS file and read them back into 'long'
variables just as one would expect. CFITSIO also supports implicit
data type conversion between 64-bit integer images and columns and any
other supported data type, although some loss of numerical precision or
numerical overflow is likely in this case.
The situation is more difficult on 32-bit computing platforms that do
not support an intrinsic 64-bit integer data type. In this case it is
not possible to return the full 64 precision of the FITS data values when
reading the values into a program variable. CFITSIO will still
convert the 64-bit integer values into any other supported data type;
the 64-bit double data type is probably the most useful in this case.
It only provides about 52-bits of precision in the mantissa, however,
so some lose of precision is possible.
12.2 Long String Keyword Values.
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.
12.3 Arrays of Fixed-Length Strings in Binary Tables
The definition of the FITS binary table extension format does not
provide a simple way to specify that a character column contains an
array of fixed-length strings. To support this feature, CFITSIO uses 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.
The Binary Table definition document that was approved by the IAU in
1994 contains an appendix describing an alternate convention for
specifying arrays of fixed or variable length strings in a binary table
character column (with the form 'rA:SSTRw/nnn)'. This appendix was not
officially voted on by the IAU and hence is still provisional. CFITSIO
does not currently support this proposal.
12.4 Keyword Units Strings
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.
12.5 HIERARCH Convention for Extended Keyword Names
CFITSIO supports the HIERARCH keyword convention which allows keyword
names that are longer then 8 characters and may contain the full range
of printable ASCII text characters. This convention
was developed at the European Southern Observatory (ESO) to support
hierarchical FITS keyword such as:
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 and can
contain any printable ASCII text characters, including spaces. 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://arcdev.hq.eso.org/dicb/dicd/dic-1-1.4.html (search for
HIERARCH).
This convention allows a much 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, and mixed case
HIERARCH XTE$TEMP = 98.6 / Keyword contains the '$' character
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. In the current implementation,
CFITSIO preserves the case of the letters when writing the keyword
name, but it is case-insensitive when reading or searching for a
keyword. The current implementation allows any ASCII text character
(ASCII 32 to ASCII 126) in the keyword name except for the '='
character. A space is also required on either side of the equal sign.
12.6 Tile-Compressed Image Format
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. 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.