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 AST_READ 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 AST_WRITE 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.
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. |
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.
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.
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.
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.
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.
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 2 describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper II.
Keyword | Read | Write
|
CTYPEia | All coordinate systems and projection types listed in paper II are supported (note, “CUBEFACE” axes are treated as unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar HEALPix) are supported. | Determined by the System attribute of the SkyFrame and the WcsType attribute of the WcsMap within the FrameSet. |
CUNITia | Ignored (assumed to be ’degrees’). | Not written. |
PVi_ma | Used to create the pixel to WCS Mapping (values are stored as attributes of a WcsMap within this Mapping). | Values are obtained from the WcsMap in the pixel to WCS Mapping. |
LONPOLEa | Used to create the pixel to WCS Mapping. Also stored as a PVi_m attribute for the longitude axis of the WcsMap. | Only written if not equal to the default value defined in paper II (see “Choice of LONPOLE/LATPOLE” below). |
LATPOLEa | Used to create the pixel to WCS Mapping. Also stored as a PV attribute for the longitude axis of the WcsMap. | Only written if not equal to the default value defined in paper II (see “Choice of LONPOLE/LATPOLE” below). |
RADESYSa | Used to set the attributes of the SkyFrame. All values supported except that ecliptic coordinates are currently always assumed to be FK5. | Always written. Determined by the System attribute of the SkyFrame. |
EQUINOXa | Used to set the Equinox attribute of the SkyFrame. | Written if relevant. Determined by the Equinox attribute of the SkyFrame. |
EPOCH | Used to set the Equinox attribute of the SkyFrame. | Only written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute of the SkyFrame. |
MJD-OBS | Used to set the Epoch attribute of the SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on RADESYS and EQUINOX is used if used if DATE-OBS is not present either. | Determined by the Epoch attribute of the SkyFrame. Only written if this attribute has been set to an explicit value (in which case DATE-OBS is also written). |
When writing a FrameSet in which the WCS Frame is a SkyFrame to a FitsChan, success depends on the following conditions being met:
If none of the above conditions hold, the write operation will be unsuccessful.
When writing a FrameSet to a FitsChan, the choice of LONPOLE and LATPOLE values is determined as follows:
When reading a FrameSet from a FitsChan, projection parameters PVi_0, PVi_1 and PVi_2 (for longitude axis “i”) are used to indicate a user-defined fiducial point as described in section 2.5 of paper II. This results in a shift of IWC origin being applied before the WcsMap which converts IWC into native spherical coordinates. The values of these projection parameters, if supplied, are stored as the corresponding PVi_m attributes of the WcsMap.
When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap determine the native coordinates of the fiducial point (the fixed defaults for each projection described in paper II are used if the PV attributes of the WcsMap have not been assigned a value). The corresponding celestial coordinates are used as the CRVALi keywords and the corresponding pixel coordinates as the CRPIXj keywords.
A collection of common non-standard features are supported when reading a FrameSet from a FitsChan, in addition to those embodied within the available encodings of the FitsChan class. These are translated into the equivalent standard features before being used to create a FrameSet. Note, the reverse operation is never performed: it is not possible to produce non-standard features when writing a FrameSet to a FitsChan (other than those embodied in the available encodings of the FitsChan class). The supported non-standard features include:
These conventions are used when reading a FrameSet from a FitsChan which includes appropriate CTYPEi values, and when writing a FrameSet in which the WCS Frame is a SpecFrame.
Table 3 describes the use made by AST of each keyword whose meaning is defined or extended by FITS-WCS paper III.
Keyword | Read | Write
|
CTYPEia | All coordinate systems and projection types listed in paper III are supported algorithm (the “-LOG” algorithm may also be applied to non-spectral linear axes; the “-TAB” algorithm requires the TabOK attribute to be set in the FitsChan). | Determined by the System attribute of the SpecFrame and the nature of the pixel to SpecFrame Mapping. |
CUNITia | Used to set the Units attribute of the SpecFrame (note, SpecFrames always have an “active” Units attribute (see astSetActiveUnit). | Always written. |
PVi_ma | Used to create the pixel to WCS Mapping (values are stored as attributes of a GrismMap). | Set from the attributes of the GrismMap, if present, and if set explicitly. |
SPECSYSa | Used to set the StdOfRest attribute of the SpecFrame (all systems are supported except CMBDIPOL). | Set from the StdOfRest attribute of the SpecFrame, but only if it has been set explicitly. |
SSYSOBSa | Ignored. | Never written. |
OBSGEO-X/Y/Z | Used to set the ObsLon and ObsLat attributes of the Frame (the observers height above sea level is ignored). | Set from the ObsLon and ObsLat attributes of the Frame, if they have been set explicitly (it is assumed that the observer is at sea level). |
MJD-AVG | Used to set the Epoch attributes of the SpecFrame. | Set from the Epoch attribute of the SpecFrame, if it has been set explicitly. |
SSYSSRCa | Used to set the SourceVRF attribute of the SpecFrame (all systems are supported except CMBDIPOL). | Set from the SourceVRF attribute of the SpecFrame. |
ZSOURCEa | Used to set the SourceVel attribute of the SpecFrame (the SourceVRF attribute is first set to the system indicated by the SSYSSRC keyword, and the ZSOURCE value is then converted to an apparent radial velocity and stored as the SourceVel attribute). | Set from the SourceVel attribute of the SpecFrame, if it has been set explicitly (the SourceVel value is first converted from apparent radial velocity to redshift). |
VELOSYSa | Ignored. | Set from the attributes of the SpecFrame that define the standard of rest and the observers position. |
RESTFRQa | Used to set the RestFreq attribute of the SpecFrame. | Set from the RestFreq attribute of the SpecFrame, but only if the System attribute is not set to “WAVE”, “VOPT”, “ZOPT” or “AWAV”, and only if RestFreq has been set explicitly. |
RESTWAVa | Used to set the RestFreq attribute of the SpecFrame (after conversion from wavelength to frequency). | Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the System attribute is set to “WAVE”, “VOPT”, “ZOPT” or “AWAV”, and only if RestFreq has been set explicitly. |
CNAMEia | Used to set the Label attributes of the WCS Frame keywords. | Set from the Label attributes of the WCS Frame, if they have been set explicitly. |
When writing a FrameSet in which the WCS Frame is a SpecFrame to a FitsChan, the write operation is successful only if the Mapping from pixel coordinates (the base Frame in the FrameSet) to the SpecFrame satisfies one of the following conditions:
If none of the above conditions hold, the write operation will be unsuccessful. Note, if the FitsChan’s TabOK attribute is set to a positive non-zero value then any Mapping that does not meet any of the earlier conditions will be written out as a look-up table, using the “-TAB” algorithm described in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or negative in the FitsChan, then the write operation will be unsuccessful unless one of the eaerlier conditions is met.44
The following non-standard features are supported when reading spectral axes from a FitsChan:
This paper proposes that an additional 4 character code be appended to the end of the CTYPEi keyword to specify the nature of any distortion away from the basic algorithm described by the first 8 characters of the CTYPEi value. Currently AST ignores all such codes when reading a FrameSet from a FitsChan (except for the “-SIP” code defined by the Spitzer Space Telescope project - see below). This means that a FrameSet can still be read from such headers, but the Mapping which gives the WCS position associated with a given pixel position will reflect only the basic algorithm and will not include the effects of the distortion.
If such a FrameSet is then written out to a FitsChan, the resulting CTYPEi keywords will include no distortion code.
The Spitzer Space Telescope project (http://www.spitzer.caltech.edu/) has developed its own system for encoding 2-dimensional image distortion within a FITS header, based on the proposals of paper IV. A description of this system is available in http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf. In this system, the presence of distortion is indicated by appending the distortion code “-SIP” to the CTYPEi keyword values for the celestial axes. The distortion takes the form of a polynomial function which is applied to the pixel coordinates, after subtraction of the CRPIXj values.
This system is a strictly 2 dimensional system. When reading a FrameSet from a FitsChan which includes the “-SIP” distortion code, AST assumes that it is only applied to the first 2 WCS axes in a FITS header (i.e. CTYPE1 and CTYPE2). If the “-SIP” distortion code is attached to other axes, it will be ignored. The distortion itself is represented by a PolyMap within the resulting FrameSet.
If a FrameSet is read from a FitsChan which includes “-SIP” distortion, and an attempt is then made to write this FrameSet out to a FitsChan, the write operation will fail unless the distortion is insignificant (i.e. is so small that the tests for linearity built into AST are passed). In this case, no distortion code will be appended to the resulting CTYPEi keyword values.
43http://www.astro.gla.ac.uk/users/norman/star/autoastrom/
44If the -TAB algorithm is used, the positive value of the TabOK attribute is used as the table version number (the EXTVER header) in the associated FITS binary table.