next up previous contents
Next: Required Keywords Up: Basic FITS Previous: Basic FITS

3.1.1 Primary Header

  Each ``card image'' in the header is in the following form:

keyword = value  /comment

Keywords can be no more than eight characters long. The only characters permitted for keywords are upper case (capital) Latin alphabetic, numbers, hyphen, and underscore, with underscore preferred over hyphen. Leading and embedded blanks are forbidden. There are two special classes of keywords:  required keywords and reserved keywords. If a keyword is required, then a card image with that keyword must appear in the header. Some keywords are required in all FITS headers; others are required only in conjunction with certain FITS structures. Some structures may require certain keywords to appear in a specific order. Reserved keywords do not have to appear in any header, but they may be used only with the reserved meaning if they do. Users may define their own additional keywords for any FITS file.

The contents of the keyword field determine the structure of the value field. Keywords that have values associated must contain ``= '' in columns 9 and 10; otherwise, columns 9-80 are regarded as comment. Except for the special cases of the HISTORY and COMMENT keywords and a blank keyword field (section, if a keyword does not have a value, column 9 must not contain ``=''. The name of the keyword governs whether a value is present. Keyword values have one of four types: logical, character string, integer, or floating point. The following notation will be used to show what type of value must be associated with each keyword:

KEYWORD (value type)

The discussion that follows the keyword name will describe the meaning of the value.

The following content is required for the first ten columns of a header card image:

To simplify the process of writing software to read FITS files, the following fixed format is mandatory for values of the required keywords. For the same reason, its use is strongly recommended for other keywords. Departures should be restricted to cases where use of fixed format is impossible for some reason. Use of the fixed format simplifies the task of the software in determining the type of the value. The structure of a fixed format value field depends upon its type:

The 20 columns specified in the fixed format may not always be sufficient to hold the full precision of a real floating point number or either the real or imaginary part of a complex floating point number. None of the required keywords used for the primary header, random groups or the ASCII table, binary table or image extensions requires a floating point value, and developers of new extensions might be well advised to avoid required keywords with floating point values. Many reserved keywords have floating point values, but there is no standard practice or recommended procedure for handling floating point values with too many digits to fit in 20 columns.

When the fixed format is not used, the value field must be written in a notation consistent with the list-directed read operations in FORTRAN-77. (With the exception of complex numbers, all the fixed formats follow the rules for FORTRAN-77 list-directed read.) Such a notation has the following requirements for the different formats:

Any information in a character string value that the reading software needs to retrieve the data from the FITS file should be in the first eight characters, for the benefit of primitive systems. Users should name their strings accordingly. If the string is used only to provide descriptive information or in the scientific interpretation of the file, it is not critical to have the meaning clear from the first eight characters, but it is still a good idea.

Comments may be incorporated in a header card image whether or not a value is present. If a value is present, place a slash (hexadecimal 2F) between the value and comment field, with at least one blank between the end of the value and the slash. For the fixed format, the slash and space are not required, but using them when writing a FITS file will simplify the task of the reader. If the fixed format is not used, a slash serving as a delimiter, a requirement derived from FORTRAN list-directed read, is required before the comment. If the keyword has no associated value (which is immediately apparent when column 9 does not contain ``=''), then the entire content of columns 9-80 is a comment. In such a case, it is best to leave column 9 blank.

The first keyword in a header must be SIMPLE and have a value of T (true) if the file conforms to FITS standards. Subsequent keywords convey the form in which array values are stored, the number of dimensions in the array, and the length of each axis. The coordinate system, scaling, and other information may be given at user option.

Note that while the FITS required keywords will always be the same, the interpretation of the associated values may be expanded. For example, negative values of the keyword BITPIX are now used to indicate IEEE floating point data, and the PCOUNT keyword, which originated in connection with random groups, was then used in the generalized extensions definition and has now been adopted to describe the heap of variable length arrays logically included in a binary table. Neither later usage was part of the original definition.

Many keywords, called indexed keywords, consist of an alphabetic root and a number. If there is only one index, the number does not have leading zeroes: NAXIS1, not NAXIS001; TTYPE11, not TTYPE011. Such keywords are represented in this Guide by an upper case root followed by a lower case n, for example NAXISn, TTYPEn. If there is more than one index, as in the PC matrix discussed in section, leading zeroes may be needed to delimit the indexes, for example PC012001, as PC121 does not distinguish between P12,1 and P1,21.

next up previous contents
Next: Required Keywords Up: Basic FITS Previous: Basic FITS