next up previous
Next: Epoch - Epoch of observation
Up: AST Attribute Descriptions
Previous: Edge(axis) - Which edges to label in a Plot

   
Encoding - System for encoding Objects as FITS headers

Description:
This attribute specifies the encoding system to use when AST Objects are stored as FITS header cards in a FitsChan. It affects the behaviour of the AST_WRITE and AST_READ routines when they are used to transfer any AST Object to or from an external representation consisting of FITS header cards (i.e. whenever a write or read operation is performed using a FitsChan as the I/O Channel).

There are several ways (conventions) by which coordinate system information may be represented in the form of FITS headers and the Encoding attribute is used to specify which of these should be used. The encoding options available are outlined in the "Encodings Available" section below, and in more detail in the sections which follow.

Encoding systems differ in the range of possible Objects (e.g. classes) they can represent, in the restrictions they place on these Objects (e.g. compatibility with some externally-defined coordinate system model) and in the number of Objects that can be stored together in any particular set of FITS header cards (e.g. multiple Objects, or only a single Object). The choice of encoding also affects the range of external applications which can potentially read and interpret the FITS header cards produced.

The encoding options available are not necessarily mutually exclusive, and it may sometimes be possible to store multiple Objects (or the same Object several times) using different encodings within the same set of FITS header cards. This possibility increases the likelihood of other applications being able to read and interpret the information.

By default, a FitsChan will attempt to determine which encoding system is already in use, and will set the default Encoding value accordingly (so that subsequent I/O operations adopt the same conventions). It does this by looking for certain critical FITS keywords which only occur in particular encodings. For details of how this works, see the "Choice of Default Encoding" section below. If you wish to ensure that a particular encoding system is used, independently of any FITS cards already present, you should set an explicit Encoding value yourself.

Type:
String.

Class Applicability:
FitsChan
All FitsChans have this attribute.

Encodings Available
The Encoding attribute can take any of the following (case insensitive) string values to select the corresponding encoding system:

  • "DSS": Encodes coordinate system information in FITS header cards using the convention developed at the Space Telescope Science Institute (STScI) for the Digitised Sky Survey (DSS) astrometric plate calibrations. The main advantages of this encoding are that FITS images which use it are widely available and it is understood by a number of important and well-established astronomy applications. For further details, see the section "The DSS Encoding" below.
  • "FITS-WCS": Encodes coordinate system information in FITS header cards using the conventions described in the (draft) FITS world coordinate system (FITS-WCS) paper by E.W. Greisen and M. Calabretta (A & A, in preparation). The main advantages of this encoding are that it should be understood by any FITS-WCS compliant application and is likely to be adopted widely for FITS data in future. At present, however, it suffers from the disadvantage that the FITS-WCS standard is only a draft (and is not stable), so it cannot yet be recommended for regular use. For further details, see the section "The FITS-WCS Encoding" below.
  • "FITS-PC": Encodes coordinate system information in FITS header cards using the conventions described in an earlier draft of the FITS world coordinate system paper by E.W. Greisen and M. Calabretta. This encoding uses a combination of CDELTi and PCiiijjj keywords to describe the scale and rotation of the pixel axes. This encoding is included to support existing data and software which uses these now superceded conventions. In general, the "FITS-WCS" encoding (which uses CDi_j keywords to describe the scale and rotation) should be used in preference to "FITS-PC".
  • "FITS-IRAF": Encodes coordinate system information in FITS header cards using the conventions described in the document "World Coordinate Systems Representations Within the FITS Format" by R.J. Hanisch and D.G. Wells, 1988. This encoding is currently employed by the IRAF data analysis facility, so its use will facilitate data exchange with IRAF. Its main advantages are that it is a stable convention which approximates to a subset of the propsed FITS-WCS encoding (above). This makes it suitable as an interim method for storing coordinate system information in FITS headers until the FITS-WCS encoding becomes stable. Since many datasets currently use the FITS-IRAF encoding, conversion of data from FITS-IRAF to the final form of FITS-WCS is likely to be well supported.
  • "FITS-AIPS": Encodes coordinate system information in FITS header cards using the conventions originally introduced by the AIPS data analysis facility. This is base on the use of CDELTi and CROTAi keuwords to desribe the scale and rotation of each axis. These conventions have been superceded but are still widely used.
  • "NATIVE": Encodes AST Objects in FITS header cards using a convention which is private to the AST library (but adheres to the general FITS standard) and which uses FITS keywords that will not clash with other encoding systems. The main advantages of this are that any class of AST Object may be encoded, and any (reasonable) number of Objects may be stored sequentially in the same FITS header. This makes FITS headers an almost loss-less communication path for passing AST Objects between applications (although all such applications must, of course, make use of the AST library to interpret the information). For further details, see the section "The NATIVE Encoding" below.

Choice of Default Encoding
If the Encoding attribute of a FitsChan is not set, the default value it takes is determined by the presence of certain critical FITS keywords within the FitsChan. The sequence of decisions used to arrive at the default value is as follows:

  • If the FitsChan contains any keywords beginning with the string "BEGAST", then NATIVE encoding is used,
  • Otherwise, if the FitsChan contains a keyword of the form "PCiiijjj", where "i" and "j" are single digits, then FITS-PC encoding is used,
  • Otherwise, if the FitsChan contains a keyword of the form "CDiiijjj", where "i" and "j" are single digits, then FITS-IRAF encoding is used,
  • Otherwise, if the FitsChan contains a keyword of the form "CDi_j", and at least one of RADECSYS, PROJPi, or CjVALi where "i" and "j" are single digits, then FITS-IRAF encoding is used.
  • Otherwise, if the FitsChan contains any keywords of the form PROJPi, CjVALi or RADECSYS, where "i" and "j" are single digits, then FITS-PC encoding is used.
  • Otherwise, if the FitsChan contains a keyword of the form CROTAi, where "i" is a single digit, then FITS-AIPS encoding is used.
  • Otherwise, if the FitsChan contains a keyword of the form CDELTi, where "i" is a single digit, then FITS-PC encoding is used.
  • Otherwise, if the FitsChan contains a keyword of the form CRVALi, where "i" is a single digit, then FITS-WCS encoding is used.
  • Otherwise, if the FitsChan contains the "PLTRAH" keyword, then DSS encoding is used,
  • Otherwise, if none of these conditions is met (as would be the case when using an empty FitsChan), then NATIVE encoding is used.

Setting an explicit value for the Encoding attribute always over-rides this default behaviour.

Note that when writing information to a FitsChan, the choice of encoding will depend greatly on the type of application you expect to be reading the information in future. If you do not know this, there may sometimes be an advantage in writing the information several times, using a different encoding on each occasion.

The DSS Encoding
The DSS encoding uses FITS header cards to store a multi-term polynomial which relates pixel positions on a digitised photographic plate to celestial coordinates (right ascension and declination). This encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSet which conforms to the STScI/DSS coordinate system model (this means the Mapping which relates its base and current Frames must include either a DssMap or a WcsMap with type AST__TAN or AST__TPN).

When reading a DSS encoded Object (using AST_READ), the FitsChan concerned must initially be positioned at the first card (its Card attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base Frame of this FrameSet represents DSS pixel coordinates, and the current Frame represents DSS celestial coordinates. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the "end-of-file". A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound.

When AST_WRITE is used to store a FrameSet using DSS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the DSS model. Specifically, the current Frame must be a default FK5 SkyFrame; the projection must be a tangent plane (gnomonic) projection with polynomial corrections conforming to DSS requirements, and north must be parallel to the second base Frame axis.

If the simplification process succeeds, a description of the FrameSet is written to the FitsChan using appropriate DSS FITS header cards. The base Frame of the FrameSet is used to form the DSS pixel coordinate system and the current Frame gives the DSS celestial coordinate system. A successful write operation will over-write any existing DSS encoded data in the FitsChan, but will not affect other (non-DSS) header cards. If a destructive read of a DSS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations.

If an attempt to simplify a FrameSet to conform to the DSS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and AST_WRITE will return zero. No error will result.

The FITS-WCS Encoding
The FITS-WCS convention uses FITS header cards to describe the relationship between pixels in an image (not necessarily 2-dimensional) and one or more related "world coordinate systems". Often, although not necessarily, one of these systems will be a celestial coordinate system, in which case the sequence of transformations which convert between the various intermediate coordinate systems will include a "sky projection" (e.g. as implemented by a WcsMap). The FITS-WCS encoding may only be used to store a single AST Object in any set of FITS header cards, and that Object must be a FrameSet which conforms to the FITS-WCS model (the FrameSet may, however, contain multiple Frames). The projections supported include all those in the fits-wcs standard. In addition, it supports the "TAN with polynomial correction terms" projection which was included in a draft of the FITS-WCS paper, but was not present in the final version.

When reading a FITS-WCS encoded Object (using AST_READ), the FitsChan concerned must initially be positioned at the first card (its Card attribute must equal 1) and the result of the read, if successful, will always be a pointer to a FrameSet. The base Frame of this FrameSet represents FITS-WCS pixel coordinates, and the current Frame represents the physical coordinate system described by the FITS-WCS primary axis descriptions. If secondary axis descriptions are also present, then the FrameSet may contain additional (non-current) Frames which represent these. Such a read is always destructive and causes the FITS header cards required for the construction of the FrameSet to be removed from the FitsChan, which is then left positioned at the "end-of-file". A subsequent read using the same encoding will therefore not return another FrameSet, even if the FitsChan is rewound.

When AST_WRITE is used to store a FrameSet using FITS-WCS encoding, an attempt is first made to simplify the FrameSet to see if it conforms to the FITS-WCS model. If this simplification process succeeds (as it often should, as the model is reasonably flexible), a description of the FrameSet is written to the FitsChan using appropriate FITS header cards. The base Frame of the FrameSet is used to form the FITS-WCS pixel coordinate system and the current Frame gives the physical coordinate system to be described by the FITS-WCS primary axis descriptions. Any additional Frames in the FrameSet may be used to construct secondary axis descriptions, where appropriate.

A successful write operation will over-write any existing FITS-WCS encoded data in the FitsChan, but will not affect other (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS encoded Object has previously occurred, then an attempt will be made to store the FITS header cards back in their original locations. Otherwise, the new cards will be inserted following any other FITS-WCS related header cards present or, failing that, in front of the current card (as given by the Card attribute).

If an attempt to simplify a FrameSet to conform to the FITS-WCS model fails (or if the Object supplied is not a FrameSet), then no data will be written to the FitsChan and AST_WRITE will return zero. No error will result.

The FITS-IRAF Encoding
The FITS-IRAF encoding can, for most purposes, be considered as a subset of the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following:

  • The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic,
  • Sky projections can be represented only if any associated projection parameters are set to their default values.
  • Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored.

Note that this encoding is provided mainly as an interim measure to provide a more stable alternative to the FITS-WCS encoding until the FITS standard for encoding WCS information is finalised. The name "FITS-IRAF" indicates the general keyword conventions used and does not imply that this encoding will necessarily support all features of the WCS scheme used by IRAF software. Nevertheless, an attempt has been made to support a few such features where they are known to be used by important sources of data.

When writing a FrameSet using the FITS-IRAF encoding, axis rotations are specified by a matrix of FITS keywords of the form "CDi_j", where "i" and "j" are single digits. The alternative form "CDiiijjj", which is also in use, is recognised when reading an Object, but is never written.

In addition, the experimental IRAF "ZPX" and "TNX" sky projections will be accepted when reading, but will never be written (the corresponding FITS "ZPN" or "distorted TAN" projection being used instead). However, there are restrictions on the use of these experimental projections. For "ZPX", longitude and latitude correction surfaces (appearing as "lngcor" or "latcor" terms in the IRAF-specific "WAT" keywords) are not supported. For "TNX" projections, only cubic surfaces encoded as simple polynomials with "half cross-terms" are supported. If an un-usable "TNX" or "ZPX" projection is encountered while reading from a FitsChan, a simpler form of TAN or ZPN projection is used which ignores the unsupported features and may therefore be inaccurate. If this happens, a warning message is added to the contents of the FitsChan as a set of cards using the keyword "ASTWARN".

You should not normally attempt to mix the FITS-IRAF, FITS-WCS, FITS-AIPS or FITS-PC encodings within the same FitsChan, since there is a risk that keyword clashes may occur.

The FITS-PC Encoding
The FITS-PC encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions.

The FITS-AIPS Encoding
The FITS-AIPS encoding can, for most purposes, be considered as equivalent to the FITS-WCS encoding (above), although it differs in the details of the FITS keywords used. It is used in exactly the same way and has the same restrictions, but with the addition of the following:

  • The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic,
  • Sky projections can be represented only if any associated projection parameters are set to their default values.
  • The AIT, SFL and MER projections can only be written if the CRVAL keywords are zero for both longitude and latitude axes.
  • Secondary axis descriptions are not supported, so when writing a FrameSet to a FitsChan, only information from the base and current Frames will be stored.
  • If there are more than 2 axes in the base and current Frames, any rotation must be restricted to the celestial plane, and must involve no shear.

The NATIVE Encoding
The NATIVE encoding may be used to store a description of any class of AST Object in the form of FITS header cards, and (for most practical purposes) any number of these Object descriptions may be stored within a single set of FITS cards. If multiple Object descriptions are stored, they are written and read sequentially. The NATIVE encoding makes use of unique FITS keywords which are designed not to clash with keywords that have already been used for other purposes (if a potential clash is detected, an alternative keyword is constructed to avoid the clash).

When reading a NATIVE encoded object from a FitsChan (using AST_READ), FITS header cards are read, starting at the current card (as determined by the Card attribute), until the start of the next Object description is found. This description is then read and converted into an AST Object, for which a pointer is returned. Such a read is always destructive and causes all the FITS header cards involved in the Object description to be removed from the FitsChan, which is left positioned at the following card.

The Object returned may be of any class, depending on the description that was read, and other AST routines may be used to validate it (for example, by examining its Class or ID attribute using AST_GETC). If further NATIVE encoded Object descriptions exist in the FitsChan, subsequent calls to AST_READ will return the Objects they describe in sequence (and destroy their descriptions) until no more remain between the current card and the "end-of-file".

When AST_WRITE is used to write an Object using NATIVE encoding, a description of the Object is inserted immediately before the current card (as determined by the Card attribute). Multiple Object descriptions may be written in this way and are stored separately (and sequentially if the Card attribute is not modified between the writes). A write operation using the NATIVE encoding does not over-write previously written Object descriptions. Note, however, that subsequent behaviour is undefined if an Object description is written inside a previously-written description, so this should be avoided.

When an Object is written to a FitsChan using NATIVE encoding, AST_WRITE should (barring errors) always transfer data and return a value of 1.



next up previous
Next: Epoch - Epoch of observation
Up: AST Attribute Descriptions
Previous: Edge(axis) - Which edges to label in a Plot

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils