System for encoding Objects as FITS headers Encoding
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.
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 FITS world coordinate system (FITS-WCS) papers by E.W.
Greisen, M. Calabretta, et al. 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. 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 papers 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 or PCi_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.
"
FITS-AIPS"
: Encodes coordinate system information in FITS header cards using the conventions used by the
AIPS
project. This is an extension of FITS-AIPS which includes some of the features of
FITS-IRAF and FITS-PC.
"
FITS-CLASS"
: Encodes coordinate system information in FITS header cards using the
conventions used by the CLASS project. CLASS is a software package for reducing
single-dish radio and sub-mm spectroscopic data. See the section "
CLASS FITS format"
at http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.
"
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.
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, FITS-CLASS is used if the FitsChan contains a DELTAV keyword and a keyword
of the form VELO-xxx, where xxx indicates one of the rest frames used by class (e.g. "
VELO-LSR"
), or "
VLSR"
.
Otherwise, if the FitsChan contains a CTYPE keyword which
represents a spectral axis using the conventions of the AIPS and
AIPS
projects (e.g. "
FELO-LSR"
, etc), then one of FITS-AIPS or
FITS-AIPS
encoding is used. FITS-AIPS
is used if any of the keywords CDi_j, PROJP, LONPOLE or LATPOLE are found in the
FitsChan. Otherwise FITS-AIPS 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 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.
Except for the NATIVE and DSS encodings, all the above checks also require that the header contains at least one CTYPE, CRPIX and CRVAL keyword (otherwise the checking process continues to the next case).
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.
When reading a DSS encoded Object (using astRead), 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 astWrite 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 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 astWrite will return zero. No error will result.
"
world coordinate
systems"
. 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 which will be result
in multiple FITS "
alternate axis descriptions"
). Details of the use made by this
Encoding of the conventions described in the FITS-WCS papers are given in the
appendix "
FITS-WCS Coverage"
of this document. A few main points are described
below.
The rotation and scaling of the intermediate world coordinate system can be specified
using either "
CDi_j"
keywords, or "
PCi_j"
together with "
CDELTi"
keywords. When
writing a FrameSet to a FitsChan, the the value of the CDMatrix attribute of the
FitsChan determines which system is used.
In addition, this encoding 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. A "
TAN with polynomial correction terms"
projection is
represented using a WcsMap with type AST__TPN (rather than AST__TAN which is
used to represent simple TAN projections). When reading a FITS header, a CTYPE
keyword value including a "
-TAN"
code results in an AST__TPN projection if
there are any projection parameters (given by the PVi_m keywords) associated
with the latitude axis, or if there are projection parameters associated with
the longitude axis for m greater than 4. When writing a FrameSet to a FITS
header, an AST__TPN projection gives rise to a CTYPE value including the normal "
-TAN"
code, but the projection parameters are stored in keywords with names "
QVi_m"
, instead of the usual "
PVi_m"
. Since these QV parameters are not
part of the FITS-WCS standard they will be ignored by other non-AST software,
resulting in the WCS being interpreted as a simple TAN projection without any
corrections. This should be seen as an interim solution until such time as an
agreed method for describing projection distortions within FITS-WCS has been
published.
AST extends the range of celestial coordinate systems which may be described using
this encoding by allowing the inclusion of "
AZ–"
and "
EL–"
as the coordinate
specification within CTYPE values. These form a longitude/latitude pair of axes
which describe azimuth and elevation. The geographic position of the observer
should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS paper
III. Currently, a simple model is used which includes diurnal aberration, but
ignores atmospheric refraction, polar motion, etc. These may be added in a later
release.
If an AST SkyFrame that represents offset rather than absolute coordinates (see
attribute SkyRefIs) is written to a FitsChan using FITS-WCS encoding, two alternate
axis descriptions will be created. One will describe the offset coordinates, and will
use "
OFLN"
and "
OFLT"
as the axis codes in the CTYPE keywords. The other will
describe absolute coordinates as specified by the System attribute of the SkyFrame,
using the usual CTYPE codes ("
RA–"
/"
DEC-"
, etc). In addition, the absolute
coordinates description will contain AST-specific keywords (SREF1/2, SREFP1/2 and
SREFIS) that allow the header to be read back into AST in order to reconstruct the
original SkyFrame.
When reading a FITS-WCS encoded Object (using astRead), 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 astWrite 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 astWrite will return zero. No error will result.
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 foreign FITS encodings within the same FitsChan, since there is a risk that keyword clashes may occur.
addition of the following:
The only celestial coordinate systems that may be represented are equatorial, galactic and ecliptic,
Spectral axes can only be represented if they represent frequency, radio velocity or optical velocity, and are linearly sampled in frequency. In addition, the standard of rest must be LSRK, LSRD, barycentric or geocentric.
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.
"
Developer Manual"
/"
CLASS FITS
Format"
contained in the CLASS documentation at:
http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html.
This encoding is similar to FITS-AIPS with the following restrictions:
When a SpecFrame is created by reading a FITS-CLASS header, the attributes describing
the observer’
s position (ObsLat, ObsLon and ObsAlt) are left unset because the CLASS
encoding does not specify these values. Conversions to or from the topocentric standard
of rest will therefore be inaccurate (typically by up to about 0.5 km/s) unless
suitable values are assigned to these attributes after the FrameSet has been
created.
When writing a FrameSet to a FITS-CLASS header, the current Frame in the FrameSet must have at least 3 WCS axes, of which one must be a linear spectral axis. The spectral axis in the created header will always describe frequency. If the spectral axis in the supplied FrameSet refers to some other system (e.g. radio velocity, etc), then it will be converted to frequency.
There must be a pair of celestial axes - either (RA,Dec) or (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000.
A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) can be used. For AIT and SFL, the reference point must be at the origin of longitude and latitude. For SIN, the associated projection parameters must both be zero.
No rotation of the celestial axes is allowed, unless the spatial axes are degenerate (i.e. cover only a single pixel).
The frequency axis in the created header will always describe frequency in the source rest frame. If the supplied FrameSet uses some other standard of rest then suitable conversion will be applied.
The source velocity must be defined. In other words, the SpecFrame attributes SourceVel and SourceVRF must have been assigned values.
The frequency axis in a FITS-CLASS header does not represent absolute frequency, but instead represents offsets from the rest frequency in the standard of rest of the source.
When writing a FrameSet out using FITS-CLASS encoding, the current Frame may be temporarily modified if this will allow the header to be produced. If this is done, the associated pixel-WCS Mapping will also be modified to take account of the changes to the Frame. The modifications performed include re-ordering axes (WCS axes, not pixel axes), changing spectral coordinate system and standard of rest, changing the celestial coordinate system and reference equinox, and changing axis units.
When reading a NATIVE encoded object from a FitsChan (using astRead), 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 astGetC). If further NATIVE encoded Object descriptions exist in
the FitsChan, subsequent calls to astRead 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 astWrite 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, astWrite should (barring errors) always transfer data and return a value of 1.