.FITS File Format – Extensions

Extension header

The data holds |BITPIX| × GCOUNT × (PCOUNT + NAXIS1 × … × NAXISm) bits, padded to a whole block. A reader can skip an extension it does not know with this formula alone.

Extension types

New types must not reuse these names. After the last HDU a file may have special records, whose first 8 bytes are never XTENSION; their use needs the approval of the IAU FITS Working Group.

IMAGE

XTENSION = 'IMAGE ', then BITPIX, NAXIS (0 to 999), NAXISn, PCOUNT = 0 and GCOUNT = 1. The data is stored exactly like the primary array, with the same scaling keywords; see data.

ASCII TABLE

Each field n then has these keywords:

On reading, F, E and D are the same: the text decides the value. A blank numeric field is zero. The physical value is TZEROn + TSCALn × field value. The last block is padded with spaces.

BINTABLE

Field keywords are those of the ASCII table except TBCOLn, plus TDIMn and THEAP. Fields follow each other in the row with no gaps and no alignment; rows follow each other with no gaps. TFORMn is rT: a repeat count r (default 1, and 0 for an empty field) and a type code T:

• All numbers are big-endian; integers of 2, 4 and 8 bytes are two’s complement.
• A string of r characters may end early with a 00 byte; what follows it is undefined. A full-length string has no terminator.
• The physical value of a number is TZEROn + TSCALn × stored value.
• Unused bytes at the end of the last block are zero.

For these columns TSCALn must be 1.

Multi-dimensional fields

TDIMn = '(l,m,n…)' shapes the r elements of a field as an array, first dimension fastest. The product must not exceed r. For example TFORM1 = '60A' with TDIM1 = '(5,4,3)' is a 4 × 3 array of five-character strings. Unused trailing elements are undefined fill.

The heap and variable-length arrays

A field of type rPt(emax) or rQt(emax) holds a variable-length array of type t (any code above except P and Q), at most emax elements long; r is 0, 1 or absent. For example TFORM8 = 'PB(1800)' is a byte array of up to 1800 elements.

• The heap starts THEAP bytes after the start of the main table. The default, which is also the minimum, is NAXIS1 × NAXIS2; a larger value leaves a gap. THEAP is not used when PCOUNT is 0.
• Arrays may be in any order, with gaps, and two descriptors may point at the same bytes. No alignment is needed. Offsets are never negative, and an array must lie wholly inside the heap.
• An empty array has count 0, and its offset should be 0.
• TSCALn and TZEROn apply to the values in the heap, not to the descriptor.

Display formats

TDISPn suggests how to show a field as text. It is advice for software and does not change the data.

Tiled image compression

A compressed image is stored as a BINTABLE with ZIMAGE = T. The image is cut into tiles (by default one row each), and each table row holds one compressed tile, the first tile in the first row.

The bit-level layout of Rice, PLIO and H-compress blocks is defined by the tiled image compression convention and its reference code, not by the standard itself, and is not described here.

Tiled table compression

A compressed binary table is itself a BINTABLE with ZTABLE = T. The rows are cut into tiles of ZTILELEN rows; each column of a tile is compressed on its own and stored as a 1QB variable-length byte array, one tile per row.

Byte shuffling with GZIP_2 applies only to integer and float columns. Variable-length arrays in the original table are compressed one by one, and their descriptors are stored as 64-bit Q descriptors compressed with GZIP_1.