Subject: FITS Coordinate Keywords

From: pence at tetra.gsfc.nasa.gov (William Pence)
Date: Tue, 31 Aug 93 17:54:26 EDT

This note describes the 3 different sets of coordinate system keywords
that the HEASARC proposes to use within it's FITS files.  One of these
is the standard set of celestial coordinate system keywords that has
already been widely used for FITS images in the primary array, or in
IMAGE extensions.  The other 2 sets of coord. system keywords are used
when the image information is expressed in a FITS binary table.  Two
different sets of keywords are needed because sometimes the array
coordinate values are explicitly given in the table, but in other cases
the array coordinate is only implicitly given by the position of the
pixel within the multidimensional array (as is the case in a FITS
primary array).  Any comments, criticisms, or suggestions about these
proposed sets of keywords are welcome.

---------------------------------------------------------------------------
A.  Possible FITS Image Representations

There are three different ways (at least) of representing an image
in a FITS file, and each way requires a slightly different set
of keywords to define the coordinate system in the image.  The
three ways of representing an image are  (for simplicity, the
image is assumed to be a 2-D array. but this discussion can
be applied to an array with any number of dimensions):

     1)  as a 2-D array in the FITS primary array (or
         in an IMAGE extension).

     2)  as a 2-D array in a single element of BINTABLE
         extension

     3)  as a list of pixels in a BINTABLE extension, where the X and Y
         coordinates and the pixel intensity are given in 3 separate
         columns of the table.

Note that the 3rd method is qualitively different from the first 2 in
that the pixel coordinates are explicitly given in the table.  In the
first 2 cases the pixel coordinates are only implied by the location of
the pixel within the array.  This difference results in a significant
difference in the way the coordinate keywords are to be interpreted.

B.  Coordinate System Keywords.

The three different sets of coordinate system keywords are summarized
in the following table and are described in more detail in the
following sections:

               PRIMARY ARRAY    BINTABLE ARRAY    TABLE LIST
               --------------   --------------    ----------
Axis Type        CTYPEm            mCTYPnnn        TCTYPnnn
Ref. Pixel       CRPIXm            mCRPXnnn        TCRPXnnn
Ref. Value       CRVALm            mCRVLnnn        TCRVLnnn
Pixel Increment  CDELTm             -----          TCDLTnnn
Coord Matrix     CDi_j             i_jCDnnn         -----
Axis Units       CUNITm            mCUNInnn        TCUNInnn

    Notes:   nnn = integer table column number
             m   = integer array axis number
             i_j = pair of integer array axis numbers

1.  Primary Array Coordinate Keywords

All the keywords listed here, except for the last CUNIT keyword,
have been widely used in the FITS world and form the basis for
the 2 other sets of derived keywords.  The CUNIT keyword has been
added for generality in cases where the axis units are not already
implied by the CTYPE value.

2.  BINTABLE Array Coordinate Keywords

In this case the image is represent by a vector column in a Binary Table.
The TDIMnnn keyword gives the number and size of the array axes.  The keyword
usage is best explained by example where a 10 x 20 image is in
column 2 of the binary table:

TFORM2  = '200J'         / this is a 200 element vector of I*4 values
TDIM2   = '(10,20)'      / a 2-D array  10 x 20
1CTYP2  = 'RA---TAN'
2CTYP2  = 'DEC--TAN'
1CRPX2  =             5.0
2CRPX2  =            10.0
1CRVL2  =           45.83
2CRVL2  =           63.57
1_1CD2  =    -0.002777777
2_2CD2  =     0.002777777
1CUNI2  = 'deg     '
2CUNI2  = 'deg     '

Note that only the 2 diagonal terms of the full CD matrix are given since
the other terms are zero.  Hopefully the meaning of these keywords
is obvious by analogy with the primary array coordinate keywords.

(Note:  William Thompson has proposed a different set of keywords,
TDESCnnn, TRPIXnnn, TRVALnnn, TDELTnnn, which give values for
all the axes in single string, e.g.,

TRPIX2   = '(5.0,10.0)'

We decided not to use this convention because the string values can
in principle become very long, exceeding the maximum length of 
as single keyword, and because it is more complicated having to deal
with a whole array of values rather than just reading or writing
a single value per keyword).

3.  Table List Coordinate Keywords.

In this case the image is not represented as an array, but instead each
pixel (or perhaps only each non-zero pixel) is listed separately on
multiple rows of a FITS table.  Each row has a column for the X
coordinate of the pixel, the Y coordinate, and a column for the
intensity of the pixel value. (If the table just represents a list of
recorded events, such as photon detections, then the intensity column
may be absent).  The coordinate keywords in this case are understood to
be applied to the _value_ in the column, and not to the _position_ of
the value in an array as is the case in the other 2 types of FITS image
representation.  To give a concrete example, the 10 x 20 array in the
previous example could be represented as 200 rows in a table with 3
columns 'X', 'Y', and 'Value'.  The relevant coordinate keywords would
then be:

TCTYP1  = 'RA---TAN'
TCTYP2  = 'DEC--TAN'
TCRPX1  =           5.0
TCRPX2  =          10.0
TCRVL1  =         45.83
TCRVL2  =         63.57
TCDLT1  =  -0.002777777
TCDLT2  =   0.002777777
TCUNI1  = 'deg     '
TCUNI2  = 'deg     '

C.  Summary

These 3 sets of keywords will probably be widely used within the FITS 
files generated by the HEASARC.  We would appreciate any comments
on this usage from the rest of the FITS community.