Naming Conventions for FITS Coordinate System Keywords

W. Pence, A. Rots, L. Angelini,

NASA Goddard Space Flight Center

Greenbelt, MD 20771

and J. McDowell

Center for Astrophysics

Cambridge, MA 02138

DRAFT: 3 Feb 1994

Introduction

This document is intended to be used in conjunction with the paper entitled ``Representations of Celestial Coordinates in FITS'' (here after referred to as RCCF) by E. W. Greisen and M. Calabretta, dated August 24, 1993, which defines the FITS keywords for describing the celestial coordinates associated with pixels in a FITS image. This document extends their paper by defining analogous sets of coordinate system keywords to be used for other types of image representations in a FITS file.

Types of Image Representations

There are several commonly used methods of representing an image in a FITS file. The RCCF paper describes the coordinate keywords to be used with an n-dimensional array of pixels in the FITS primary array or IMAGE extension, which is the most common image representation, but there are other image representations that are also used for astronomical data:

• an n-dimensional vector within a single element of a FITS binary table
• a tabulated list of pixel coordinates (and other optional parameters) in a FITS ASCII or binary table.

In addition, we consider a fourth case which simply tabulates a set of coordinate keyword values which refer to other images. Each of these types of images is described in more detail in the following sections, and this is followed by a table of the recommended keywords to be used in each case.

Primary array image

The most familiar type of FITS image representation is as an n-dimensional array of pixels stored either in the primary array or in an IMAGE extension. The RCCF paper deals with this case.

N-Dimensional Vector in a Binary Table

One feature of the FITS Binary Table (BINTABLE) format is that each element of the table (i.e., the intersection of a row and a column in the table) may be a vector of data values, and the TDIMn keyword (where n is an integer column number) may be used to specify the number and size of the dimensions within the vector. This feature allows each row of a binary table to contain one or more images.

Tabulated List of Pixels

An image may be represented by a list of pixel coordinates and other optional associated parameters. This representation is often used in high-energy astrophysics as a way of tagging the position and other properties of individual detected photons. This is also a compact way of representing very sparse images since only the non-zero pixels need to be given in the list.

Note that this image representation is qualitatively different from the others in that the pixel coordinates are explicitly given in the table whereas 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 difference in the way the coordinate keywords are interpreted.

Referred Coordinate System

It is sometimes convenient to make a table of the values of the coordinate transformation keywords that apply to a set of images. This is not a different type of image representation per se, but a new family of keyword (or column) names is required because one cannot simply reuse the same keyword names as in a primary array image. (For example it would be confusing to have an NAXIS keyword for the table itself as well as an NAXIS column in the table). The naming convention proposed here is to prefix the referred keyword or column names with the letter `R'. This system might be used, for example, to make a table of the coordinate keyword values that define how the celestial pointing of an imaging instrument changed with time.

Keyword Naming Conventions

A standard set of coordinate keywords is needed for use with each of the 4 FITS image representations discussed above. The RCCF paper has already defined the keywords to be used with images stored in a FITS primary array or image extension, which we adopt here without any modification. In the following table we propose sets of keywords to be used for the other 3 types of image representations. These new keywords are analogous to, and have exactly the same meaning and usage as the RCCF keywords.

Keyword	Primary	BINTABLE	Table	Referred
Description	Array	Vector	Pixel List	Table
Axis Type	CTYPEi	iCTYPn	TCTYPn	RCTYPi
Reference Pixel	CRPIXi	iCRPXn	TCRPXn	RCRPXi
Reference Value	CRVALi	iCRVLn	TCRVLn	RCRVLi
Pixel Increment	CDELTi	iCDLTn	TCDLTn	RCDLTi
Axis Rotation	CROTAi	iCROTn	TROTAn	RROTAi
Rotation Matrix	CDiiijjj	ijCDn	TCDnnmm	RCDiijj
Transform Matrix$^1$	CDi_j	N/A	N/A	N/A
Axis Units	CUNITi	iCUNIn	TCUNIn	RCUNIi
Coord. Epoch	EQUINOX	EQUINOX or	EQUINOX or	EQUINOX
		EQUINn	EQUINn
Date of Obs.	DATE-OBS	DATE-OBS or	DATE-OBS or	DATE-OBS
		DATOBn	DATOBn
MJD of Obs.	MJD-OBS	MJD-OBS or	MJD-OBS or	MJD-OBS
		MJDOBn	MJDOBn
Reference Frame	RADECSYS	RADECSYS or	RADECSYS or	RADECSYS
		RADECn	RADECn
Coord. Rotation	LONGPOLE	LONGPOLE or	LONGPOLE or	LONGPOLE
		LONGPn	LONGPn
Proj. Param. 1	PROJP1	PROJP1 or	PROJP1 or	PROJP1
		P1PARn	P1PARn
Proj. Param. 2	PROJP2	PROJP2 or	PROJP2 or	PROJP2
		P2PARn	P2PARn

Notes:
$^1$This keyword has been superseded.
i, j are integer axis numbers referring to an axis of the n-dimensional array. When used as a keyword prefix (e.g. iCTYPn these are limited to 1 digit (1-9). When used as a keyword suffix they may be up to 3 digits long (1-999).
ii, jj are 2-digit integer axis numbers, including leading zeros if necessary (01-99).
iii, jjj are 3-digit integer axis numbers, including leading zeros if necessary (001-999).
n is an integer table column number (1-999) without any leading zeros.
mm, nn are 2-digit integer table column numbers (01-99).

The following paragraphs describe each type of keyword in more detail.

1. Axis Type: a character string label which defines the type of axis. In the case of the celestial coordinate system projections discussed in RCCF this keyword also specifies the type of map projection and implicitly defines the units of the physical coordinates (see also the Axis Units keyword below).

2. Reference Pixel: the pixel coordinate of the reference point. When dealing with arrays, the first pixel runs from pixel number 0.5 to 1.5 on each axis and (1.0, 1.0) refers to the center of the lower left pixel in a 2-D image.

3. Reference Value: the physical coordinate value at the position of the reference pixel.

4. Pixel Increment: the increment per pixel of the physical coordinate value at the position of the reference pixel.

5. Axis Rotation: the rotation angle between the pixel axis and the physical coordinate axis. This keyword is superseded by the Rotation Matrix keywords which should be written in new FITS files, but the CROTAi keyword should still be given to assist older FITS-reading programs. This keyword is only appropriate for 2-dimensional arrays and should only be given for the 2nd axis (i.e., CROTA2).

6. Rotation Matrix: the rotation (and skew) terms needed to convert from the pixel coordinate system to the physical coordinate system. After this transformation has been applied the coordinates are aligned with the physical axes but are still in pixel units. The Pixel Increment value is then used to scale the pixel values to the physical values. Note that in the BINTABLE Vector format, the coordinate matrix keyword name can only support up to a 9-dimensional array because of the 8-character limitation on keyword names. Similarly, in the table pixel list image format the TCDnnmm keyword is limited to 2-digit column numbers, thus one is restricted to using columns 1 - 99 for storing the pixel coordinates.

7. Transformation Matrix: the product of the Rotation matrix and the `Pixel Increment' diagonal matrix. These keywords are no longer recommended and should not be written in any new FITS files. Instead, the Rotation Matrix and Pixel Increment keywords should be given separately.

8. Axis Units: specifies the physical units of each axis. This keyword was not defined in RCCF because the units are implied by the Axis Type keyword. It has been included here for added generality when dealing with other types of coordinate systems besides those discussed in RCCF. (e.g., 'deg').

9. Coordinate Epoch: epoch of the mean equator and equinox in years. It is recommended that the value of this keyword be either 1950.0 or 2000.0. If different columns of the table contain images with different epochs, then the EQUINn form of the keyword must be used to give the epoch value for each column individually.

10. Date of Observation: the date of the observation in 'dd/mm/yy' format. If different columns of the table contain images with different dates, then the DATOBn form of the keyword must be used to give the date for each column individually.

11. MJD of Observation: the modified Julian date of the observation in decimal days. If different columns of the table contain images with different dates, then the MJDOBn form of the keyword must be used to give the date for each column individually.

12. Reference Frame: the frame of reference of the equatorial coordinates (e.g., `FK4' for EQUINOX 1950.0 and `FK5' for EQUINOX 2000.0) If different columns of the table contain images with different reference frames, then the RADECn form of the keyword must be used to give the frame for each column individually.

13. Coordinate Rotation: the longitude in the native coordinate system of the standard system's north pole; default value = 180 degrees. This keyword is only applicable to certain celestial coordinate system projections. If different columns of the table contain images with different rotations, then the LONGPn form of the keyword must be used to give the rotation for each column individually.

14. Projection Parameters: some projections require additional parameters. The interpretation of these keywords depends on the value of the Axis Type keyword. If different columns of the table contain images with different projection parameters, then the P1PARn and P2PARn form of the keywords must be used to give the parameter for each column individually.

Multiple images and the `Greenbank' Convention

In the binary table vector representation of images, each row of the table contains a separate image and in general all the images do not necessarily have the same coordinate transformation keywords values. If, for example, the value of the reference pixel was different for each image (row) then a single 1CRVLn keyword would not be sufficient. Instead, this single keyword would need to be expanded into a whole column of values in the table, where the column has the same name as the previous keyword (e.g., TTYPEn = 1CRVL3 for the reference value of the first axis of the image contained in column 3 of a table). Then the appropriate reference value can be supplied in each row of the table. This convention for expanding a keyword into a table column (or conversely, collapsing a column of identical values into a single header keyword with the same name as the column) was originally developed and promoted at the Greenbank Radio Observatory, and hence this is commonly referred to as part of the `Greenbank Convention' for keywords.

Example FITS Headers

The following examples show how the same image may be represented using different FITS formats. In each case the images are 300 x 200 pixels in size and are rotated 30 degrees with respect to the RA and DEC celestial coordinate system.

Primary Array

This is a sample FITS header for a FITS primary array image.

SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   32 / number of bits per data pixel
NAXIS   =                    2 / number of data axes
NAXIS1  =                  300 / length of data axis   1
NAXIS2  =                  200 / length of data axis   2

CTYPE1  = 'RA---TAN'           / TAN projection used
CRPIX1  =                  150 / reference pixel
CRVAL1  =                45.83 / RA at the reference pixel
CDELT1  =           -.00277777 / increment per pixel (degrees)
CUNIT1  = 'deg     '           / physical units of axis 1

CTYPE2  = 'DEC--TAN'           / TAN projection used
CRPIX2  =                  100 / reference pixel
CRVAL2  =                63.57 / DEC at the reference pixel
CDELT2  =            .00277777 / increment per pixel (degrees)
CUNIT2  = 'deg     '           / physical units of axis 2
CROTA2  =                 30.0 / image rotation (degrees)

CD001001=           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)
CD002002=                  -.5 / Coord. Descrp. Matrix: -sin(CROTA2)
CD001002=                   .5 / Coord. Descrp. Matrix:  sin(CROTA2)
CD002001=           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)

EQUINOX =               1950.0 / coordinate epoch
DATE-OBS= '04/03/51'           / date of observation
END

BINTABLE Vector with Fixed Transformation Parameters

In this example the image is stored as a vector in column 3 of the table where each row of the table contains a different 300 x 200 pixel image. All the coordinate system parameters except for the date of observation are the same for each image and are given as header keywords. The DATE-OBS column gives the date corresponding to the image in that row.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =               240024 / width of table in bytes
NAXIS2  =                    4 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)

TFIELDS =                    3 / number of fields in each row
TTYPE1  = 'Name    '           / name of observed object
TFORM1  = '16A     '           / data format of the field: ASCII Character
TTYPE2  = 'DATE-OBS'           / date of observation
TFORM2  = '8A      '           / data format of the field: ASCII Character
TTYPE3  = 'Image   '           / 2-D image vector
TFORM3  = '60000J  '           / data format of the field: I*4 vector
TDIM3   = '(300,200)'          / dimension sizes of the vector

COMMENT  The following keywords define the coordinate system of the image
COMMENT  contained in Column 3 of the table

1CTYP3  = 'RA---TAN'           / TAN projection used in axis 1 
1CRPX3  =                  150 / reference pixel in axis 1 
1CRVL3  =                45.83 / RA at the reference pixel
1CDLT3  =           -.00277777 / increment per pixel
1CUNI3  = 'deg     '           / physical units of axis 1

2CTYP3  = 'DEC--TAN'           / TAN projection used
2CRPX3  =                  100 / reference pixel
2CRVL3  =                63.57 / DEC at the reference pixel
2CDLT3  =            .00277777 / increment per pixel
2CUNI3  = 'deg     '           / physical units of axis 2
2CROT3  =                 30.0 / image rotation (degrees)

11CD3   =           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)
22CD3   =                  -.5 / Coord. Descrp. Matrix: -sin(CROTA2)
12CD3   =                   .5 / Coord. Descrp. Matrix:  sin(CROTA2)
21CD3   =           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)

EQUINOX =               1950.0 / coordinate epoch
END

BINTABLE Vector with Variable Transformation Parameters

This table, like the previous example, has 4 rows, each of which contains a 300 x 200 pixel image. In this case, however, the position of the image on the sky varies from image to image, and so the Reference Values must be supplied in columns in the table rather than as header keywords. The pixel size and image rotation are still assumed to be the same for each image.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =               240032 / width of table in bytes
NAXIS2  =                    4 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)

TFIELDS =                    5 / number of fields in each row
TTYPE1  = 'Name    '           / name of observed object
TFORM1  = '16A     '           / data format of the field: ASCII Character
TTYPE2  = 'DATE-OBS'           / date of observation
TFORM2  = '8A      '           / data format of the field: ASCII Character
TTYPE3  = '1CRVL5  '           / reference pixel of axis 1 in column 5
TFORM3  = '1E      '           / data format of the field: R*4
TTYPE4  = '2CRVL5  '           / reference pixel of axis 2 in column 5
TFORM4  = '1E      '           / data format of the field: R*4
TTYPE5  = 'Image   '           / 2-D image vector
TFORM5  = '60000J  '           / data format of the field: I*4 vector
TDIM5   = '(300,200)'          / dimension sizes of the vector

COMMENT  The following keywords define the coordinate system of the image
COMMENT  contained in Column 5 of the table

1CTYP5  = 'RA---TAN'           / TAN projection used
1CRPX5  =                  150 / reference pixel
1CDLT5  =           -.00277777 / increment per pixel
1CUNI5  = 'deg     '           / physical units of axis 1

2CTYP5  = 'DEC--TAN'           / TAN projection used
2CRPX5  =                  100 / reference pixel
2CDLT5  =            .00277777 / increment per pixel
2CUNI5  = 'deg     '           / physical units of axis 2
2CROT5  =                 30.0 / image rotation (degrees)

11CD5   =           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)
22CD5   =                  -.5 / Coord. Descrp. Matrix: -sin(CROTA2)
12CD5   =                   .5 / Coord. Descrp. Matrix:  sin(CROTA2)
21CD5   =           .866025403 / Coord. Descrp. Matrix:  cos(CROTA2)

EQUINOX =               1950.0 / coordinate epoch
END

Pixel list

In this example the image is given as a list of arrival times and pixel coordinates of a set of detected photons. A 2-D array image (like the first example of a primary array image) could be generated from this list by making a 2-D histogram of the number of photons that were recorded in each pixel. The TLMINn and TLMAXn keywords are used to record the legal range of the values along each axis.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                   12 / width of table in bytes
NAXIS2  =                10000 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)

TFIELDS =                    3 / number of fields in each row
TTYPE1  = 'TIME    '           / time of photon detection
TFORM1  = '1D      '           / data format of the field: R*8
TTYPE2  = 'X       '           / X pixel coordinate of the photon
TFORM2  = '1I      '           / data format of the field: ASCII Character
TTYPE3  = 'Y       '           / Y pixel coordinate of the photon
TFORM3  = '1I      '           / data format of the field: ASCII Character

TCTYP2  = 'RA---TAN'           / TAN projection used
TCRPX2  =                  150 / reference pixel
TCRVL2  =                45.83 / reference pixel
TCDLT2  =           -.00277777 / increment per pixel
TCUNI2  = 'deg     '           / physical units of axis 1
TLMIN2  =                    1 / lower limit of axis 1
TLMAX2  =                  300 / upper limit of axis 1

TCTYP3  = 'DEC--TAN'           / TAN projection used
TCRPX3  =                  100 / reference pixel
TCRVL3  =                63.57 / reference pixel
TCDLT3  =            .00277777 / increment per pixel
TCUNI3  = 'deg     '           / physical units of axis 2
TCROT3  =                 30.0 / image rotation (degrees)
TLMIN3  =                    1 / lower limit of axis 2
TLMAX3  =                  200 / upper limit of axis 2

TCD0202 =           .866025403 / Coord. Descrp. Matrix:  cos(TCROT2)
TCD0303 =                  -.5 / Coord. Descrp. Matrix: -sin(TCROT2)
TCD0203 =                   .5 / Coord. Descrp. Matrix:  sin(TCROT2)
TCD0302 =           .866025403 / Coord. Descrp. Matrix:  cos(TCROT2)

EQUINOX =               1950.0 / coordinate epoch
DATE-OBS= '03/04/51'           / date of observation
END

Referred Coordinates

In this example the binary table is used to store values of the celestial coordinate system transformation parameters for a particular imaging instrument as a function of time (TIME being the first column of the table). In effect, this records exactly where the instrument was pointed on the sky as a function of time. Since the axis type (RCTYPi), reference pixel (RCRPXi), and pixel increment (RCDLTi) values are fixed and are the same for every image, these are give as a keywords instead of as table columns to conserve space.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                   36 / width of table in bytes
NAXIS2  =                  100 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)

TFIELDS =                    8 / number of fields in each row
TTYPE1  = 'TIME    '           / time of photon detection
TFORM1  = '1D      '           / data format of the field: R*8
TUNIT1  = 's       '           / time in units of seconds
TTYPE2  = 'RCRVL1  '           / reference value on axis 1
TFORM2  = '1E      '           / data format of the field: R*4
TTYPE3  = 'RCRVL2  '           / reference value on axis 2
TFORM3  = '1E      '           / data format of the field: R*4
TTYPE4  = 'RROTA2  '           / rotation of axis 2
TFORM4  = '1E      '           / data format of the field: R*4
TTYPE5  = 'RCD0101 '           / rotation matrix element 1,1
TFORM5  = '1E      '           / data format of the field: R*4
TTYPE6  = 'RCD0102 '           / rotation matrix element 1,2
TFORM6  = '1E      '           / data format of the field: R*4
TTYPE7  = 'RCD0201 '           / rotation matrix element 2,1
TFORM7  = '1E      '           / data format of the field: R*4
TTYPE8  = 'RCD0202 '           / rotation matrix element 2,2
TFORM8  = '1E      '           / data format of the field: R*4

COMMENT  The following fixed values apply to all rows of the table

RCTYP1  = 'RA---TAN'           / TAN projection used
RCTYP2  = 'DEC--TAN'           / TAN projection used
RCRPX1  =                  150 / reference pixel on axis 1
RCRPX2  =                  100 / reference pixel on axis 2
RCDLT1  =           -.00277777 / increment per pixel on axis 1
RCDLT2  =            .00277777 / increment per pixel on axis 2
RCUNI1  = 'deg     '           / units of axis 1
RCUNI2  = 'deg     '           / units of axis 2

EQUINOX =               1950.0 / coordinate epoch
DATE-OBS= '03/04/51'           / date of observation
END

About this document ...

This document was generated using the LaTeX2HTML translator Version 99.2beta8 (1.46)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -t OGIP/94-006 -split 3 -image_type gif ogip_94_006.tex

The translation was initiated by Michael Arida on 2001-06-28

HEASARC home page

This file was last modified on Friday, 18-May-2007 10:27:11 EDT

This page maintained by: Michael Arida (SP Sys); arida@milkyway.gsfc.nasa.gov
HEASARC Guest Observer Facility