Naming Conventions for FITS Coordinate System KeywordsW. Pence, A. Rots, L. Angelini,
and J. McDowell
DRAFT: 3 Feb 1994
IntroductionThis 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 RepresentationsThere 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 ndimensional 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:
Primary array imageThe most familiar type of FITS image representation is as an ndimensional array of pixels stored either in the primary array or in an IMAGE extension. The RCCF paper deals with this case.
NDimensional Vector in a Binary TableOne 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 PixelsAn image may be represented by a list of pixel coordinates and other optional associated parameters. This representation is often used in highenergy 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 nonzero 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 SystemIt 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 ConventionsA 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.
This keyword has been superseded. i, j are integer axis numbers referring to an axis of the ndimensional array. When used as a keyword prefix (e.g. iCTYPn these are limited to 1 digit (19). When used as a keyword suffix they may be up to 3 digits long (1999). ii, jj are 2digit integer axis numbers, including leading zeros if necessary (0199). iii, jjj are 3digit integer axis numbers, including leading zeros if necessary (001999). n is an integer table column number (1999) without any leading zeros. mm, nn are 2digit integer table column numbers (0199). The following paragraphs describe each type of keyword in more detail.
Multiple images and the `Greenbank' ConventionIn 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 HeadersThe 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 ArrayThis 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 = 'RATAN' / 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 = 'DECTAN' / 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 DATEOBS= '04/03/51' / date of observation END
BINTABLE Vector with Fixed Transformation ParametersIn 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 DATEOBS column gives the date corresponding to the image in that row.
XTENSION= 'BINTABLE' / binary table extension BITPIX = 8 / 8bit bytes NAXIS = 2 / 2dimensional 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 = 'DATEOBS' / date of observation TFORM2 = '8A ' / data format of the field: ASCII Character TTYPE3 = 'Image ' / 2D 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 = 'RATAN' / 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 = 'DECTAN' / 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 ParametersThis 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 / 8bit bytes NAXIS = 2 / 2dimensional 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 = 'DATEOBS' / 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 ' / 2D 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 = 'RATAN' / TAN projection used 1CRPX5 = 150 / reference pixel 1CDLT5 = .00277777 / increment per pixel 1CUNI5 = 'deg ' / physical units of axis 1 2CTYP5 = 'DECTAN' / 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 listIn this example the image is given as a list of arrival times and pixel coordinates of a set of detected photons. A 2D array image (like the first example of a primary array image) could be generated from this list by making a 2D 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 / 8bit bytes NAXIS = 2 / 2dimensional 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 = 'RATAN' / 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 = 'DECTAN' / 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 DATEOBS= '03/04/51' / date of observation END
Referred CoordinatesIn 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 / 8bit bytes NAXIS = 2 / 2dimensional 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 = 'RATAN' / TAN projection used RCTYP2 = 'DECTAN' / 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 DATEOBS= '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.
The command line arguments were:
The translation was initiated by Michael Arida on 20010628
This file was last modified on Friday, 18May2007 10:27:11 EDT
This page maintained by:
Michael Arida (SP Sys); arida@milkyway.gsfc.nasa.gov
