G FITS-WCS Coverage

 G.1 Paper I - General Linear Coordinates
 G.2 Paper II - Celestial Coordinates

This appendix gives details of the FitsChan class implementation of the conventions described in the FITS-WCS papers available at http://fits.gsfc.nasa.gov/fits_wcs.html. These conventions are used only if the Encoding attribute of the FitsChan has the value “FITS-WCS” (whether set explicitly or defaulted). It should always be possible for a FrameSet to be read (using the astRead function) from a FitsChan containing a header which conforms to these conventions. However, only those FrameSets which are compatible with the FITS-WCS model can be written to a FitsChan using the astWrite function. For instance, if the current Frame of a FrameSet is re-mapped using, say, an arbitrary MathMap then the FrameSet will no longer be compatible with the FITS-WCS model, and so will not be written out successfully to a FitsChan.

The following sub-sections describe the details of the implementation of each of the first four FITS-WCS papers. Here, the term “pixel axes” is used to refer to the FITS pixel coordinates (i.e. the centre of the first image pixel has a value 1.0 on each pixel axis); the term “IWC axes” is used to refer to the axes of the Intermediate World Coordinate system; and the term “WCS axes” is used to refer to the axes of the final physical coordinate system described by the CTYPEi keywords.

G.1 Paper I - General Linear Coordinates

When reading a FrameSet from a FitsChan, these conventions are used if the CTYPEi keyword values within the FitsChan do not conform to the conventions described in later papers, in which case the axes are assumed to be linear. When writing a FrameSet to a FitsChan, these conventions are used for axes which are described by a simple Frame (i.e. not a SkyFrame, SpecFrame, etc.).

Table 1 describes the use made by AST of each keyword defined by FITS-WCS paper I.





Keyword
Read
Write



WCSAXESa

Ignored.

Set to the number of axes in the WCS Frame - only written if different to NAXIS.

CRVALia

Used to create the pixel to WCS Mapping.

Always written (see “Choice of Reference Point” below).

CRPIXja

Used to create the pixel to WCS Mapping.

Always written (see “Choice of Reference Point” below).

CDELTia

Used to create the pixel to WCS Mapping.

Only written if the CDMatrix attribute of the FitsChan is set to zero.

CROTAi

Used to create the pixel to WCS Mapping.

Only written in FITS-AIPS and FITS-AIPS++ encodings.

CTYPEia

Used to choose the class and attributes of the WCS Frame, and to create the pixel to WCS Mapping (note, “STOKES” and “COMPLEX” axes are treated as unknown linear axes).

Always written (see “Use and Choice of CTYPE keywords” below).

CUNITia

Used to set the Units attributes of the WCS Frame.

Only written if the Units attribute of the WCS Frame has been set explicitly. If so, the Units value for each axis is used as the CUNIT value.

PCi_ja

Used to create the pixel to WCS Mapping.

Only written if the CDMatrix attribute of the FitsChan is set to zero.

CDi_ja

Used to create the pixel to WCS Mapping.

Only written if the CDMatrix attribute of the FitsChan is set to a non-zero value.

PVi_ma

Ignored for linear axes.

Not written if the axes are linear.

PSi_ma

Ignored.

Not used.

WCSNAMEa

Used to set the Domain attribute of the WCS Frame.

Only written if the Domain attribute of the WCS Frame has been set explicitly. If so, the Domain value is used as the WCSNAME value.

CRDERia

Ignored.

Not used.

CSYERia

Ignored.

Not used.





Table 1: Use of FITS-WCS Paper I keywords

G.1.1 Requirements for a Successful Write Operation

When writing a FrameSet in which the WCS Frame is a simple Frame to a FitsChan, success depends on the Mapping from pixel coordinates (the base Frame in the FrameSet) to the WCS Frame being linear. The write operation will fail if this is not the case.

G.1.2 Use and Choice of CTYPEi keywords

When reading a FrameSet from a FitsChan the CTYPEi values in the FitsChan are used to set the Symbol attributes of the corresponding WCS Frame. The Label attributes of the WCS Frame are set from the CNAMEi keywords, if present in the header. Otherwise they are set from the CTYPEi comments strings in the header, so long as each axis has a unique non-blank comment. Otherwise, the Label attributes are set to the CTYPEi values. The above procedure is over-ridden if the axis types conform to the conventions described in paper II or III, as described below.

When writing a FrameSet to a FitsChan, each CTYPEi value is set to the value of the Symbol attribute of the corresponding axis in the Frame being written. If a value has been set explicitly for the axis Label attribute, it is used as the axis comment (except that any existing comments in the FitsChan take precedence if the keyword value has not changed). The above procedure is over-ridden if the Frame is a SkyFrame or a SpecFrame, in which case the CTYPEi value is derived from the System attribute of the Frame and the nature of the pixel to WCS Mapping according to the conventions of papers II and III, as described below.

G.1.3 Choice of Reference Point

When writing a FrameSet to a FitsChan, the pixel coordinates of the reference point for linear axes (i.e. the CRPIXj values) are chosen as follows:

The pixel to WCS Mapping is then used to find the corresponding CRVALjvalues.

Again, the above procedure is over-ridden if the Frame is a SkyFrame or a SpecFrame, in which case the conventions of papers II and III are used as described below.

G.1.4 Choice of Axis Ordering

When reading a FrameSet from a FitsChan, WCS axis i in the current Frame of the resulting FrameSet corresponds to axis i in the FITS header.

When writing a FrameSet to a FitsChan, the axis ordering for the FITS header is chosen to make the CDi_j or PCi_j matrix predominately diagonal. This means that the axis numbering in the FITS header will not necessarily be the same as that in the AST Frame.

G.1.5 Alternate Axis Descriptions

When reading a FrameSet from a FitsChan which contains alternate axis descriptions, each complete set of axis descriptions results in a single Frame being added to the final FrameSet, connected via an appropriate Mapping to the base pixel Frame. The Ident attribute of the Frame is set to hold the single alphabetical character which is used to identify the set of axis descriptions within the FITS header (a single space is used for the primary axis descriptions).

When writing a FrameSet to a FitsChan, it is assumed that the base Frame represents pixel coordinates, and the current Frame represents the primary axis descriptions. If there are any other Frames present in the FrameSet, an attempt is made to create a complete set of “alternate” set of keywords describing each additional Frame. The first character in the Ident attribute of the Frame is used as the single character descriptor to be appended to the keyword, with the proviso that a given character can only be used once. If a second Frame is found with an Ident attribute which has already been used, its Ident attribute is ignored and the next free character is used instead. Note, failure to write a set of alternate axis descriptions does not result in failure of the entire write operation: the primary axis descriptions are still written, together with any other alternate axis descriptions which can be produced successfully.

G.2 Paper II - Celestial Coordinates

These conventions are used when reading a FrameSet from a FitsChan containing appropriate CTYPEi values, and when writing a FrameSet in which the WCS Frame is a SkyFrame.

Table ?? describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper II.