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
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.
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 |
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 |
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.
- 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).
- 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.
- Reference Value: the physical coordinate value at the
position of the reference pixel.
- Pixel Increment: the increment per pixel of the
physical coordinate value at the position of the reference pixel.
- 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).
- 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.
- 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.
- 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').
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- Introduction
- Types of Image Representations
- Keyword Naming Conventions
- Multiple images and the `Greenbank' Convention
- Example FITS Headers
- About this document ...
| 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