[fitsbits] coordinates by table lookup

[Arnold Rots]

About two years ago, we established a convention for enumerated
coordinate axes in Chandra FITS files.

Attached is the section on coordinates in our FITS conventions
document.

  - Arnold

--------------------------------------------------------------------------
Arnold H. Rots                                Chandra X-ray Science Center
Smithsonian Astrophysical Observatory                tel:  +1 617 496 7701
60 Garden Street, MS 81                              fax:  +1 617 495 7356
Cambridge, MA 02138                             arots at head-cfa.harvard.edu
USA                                     http://hea-www.harvard.edu/~arots/
--------------------------------------------------------------------------


\subsection{Coordinate information}

As a rule, coordinates are to be specified using the corrdinate
systems given in the documents SDS-2.0, {\em Coordinate Systems},
SDS-9.0 {\em FITS names for ASC Coordinates}, and SDS-12.0 {\em
Coordinate system design for data model}, all by Jonathan McDowell.
For calibration-related coordinate issues, see also the applicable
HEASARC documents.

For regularly spaced coordinates, it appears that consensus is
building in the FITS community to have the pixel grid defined by an
$NAXIS \times NAXIS$ matrix stored in the keywords ``CD{\em i}\_{\em j}''.
However, since the formal acceptance of the current WCS proposal is
still some way off and since it is not clear what the status of the
CDELT{\em i} and CROTA{\em i} keywords is going to be, we shall allow
both forms to be used in the ASC: either CD{\em i}\_{\em j} or
CDELT{\em i} and CROTA{\em i}.  In addition, alternate coordinate axis
may be indicated by adding WCS keywords that have a letter appended,
such as CTYPE1A, CDELT1A, CUNIT1A, \etc

We have adopted one additional convention for specifying enumerated
coordinates (irregularly spaced bins or pixels.  If, for instance, the
third coordinate of a multi-dimensional image in the primary array is
energy ('ENERG'), sampled irregularly, the actual energy values of the pixels
may be listed in a subsequent extension in the same file, with the
referencing done as follows.

\begin{verbatim}
HDU0:
...
NAXIS3  =          10   / Number of pixels along 3rd axis
CTYPE3  = 'ENERG_BIN'   / Name of this pseudo coordinate
CD3_3   =           1   / Pixel increment (or CDELT3)
CRPIX3  =           1   / Better make this 1
CRVAL3  =           1   / ... And this one, too, or confusion will reign
CEXTN3  = 'ENERGY_BINS' / It will be enumerated in an HDU with EXTNAME='ENERGY_BINS'
CEXTV3  =           1   / ... and EXTVER=1 (first HDU of that name if CEXTV omitted)
...

HDU1:
...
TFIELDS =           2   / Needs to be at least 2
NAXIS2  =          10   / There are 10 rows (at least NAXIS3 above)
...
EXTNAME = 'ENERGY_BINS' / EXTNAME
EXTVER  =           1
TTYPE1  = 'ENERG_BIN'   / First column: the bin numbers
TFORM1  = '1I'
TTYPE2  = 'ENERG'       / Second column: the real energy values
TFORM2  = '1D'
TUNIT2  = 'keV'
...
\end{verbatim}

This introduces the new keywords CEXTN{\em i} and CEXTV{\em i}, which link a table
in the same FITS file to a particular coordinate axis.  CEXTV{\em i} is
optional.

The HDU with the enumerated coordinate pixels needs to:
\begin{itemize}
\item ... have the same EXTNAME as CEXTN{\em i}.
\item ... have a column with TTYPE identical to the value of CTYPEi.
\item ... have a column with TTYPE the name of the ``real'' coordinate axis.
\end{itemize}

If the table provides pixel (bin) bounds, rather tha pixel coordinate
values, the example above would look like this (HDU1 only):

\begin{verbatim}
...
TFIELDS =           3   / Needs to be at least 2
NAXIS2  =          10   / There are 10 rows (at least NAXIS3 above)
...
EXTNAME = 'ENERGY_BINS' / EXTNAME
EXTVER  =           1
TTYPE1  = 'ENERG_BIN'   / First column: the bin numbers
TFORM1  = '1I'
TTYPE2  = 'ENERG_LO'     / Second column: the lower energy bin bounds
TFORM2  = '1D'
TUNIT2  = 'keV'
TTYPE3  = 'ENERG_HI'     / Third column: the upper energy bin bounds
TFORM3  = '1D'
TUNIT3  = 'keV'
...
\end{verbatim}

Of course, that table may have more rows than NAXIS{\em i}; and
CRPIX{\em i}, CDELT{\em i}, and CRVAL{\em i} need not be 1; but one
should not complicate matters when it's not necessary.