While a FitsChan is active, it represents a buffer which may contain zero or more
" header cards
" conforming to FITS conventions. Any sequence of
FITS-conforming header cards may be stored, apart from the
" card whose
existence is merely implied. The cards may be accessed in any order by using the
’ s integer Card attribute, which identifies a
" card, to
which subsequent operations apply. Searches based on keyword may be performed
(using astFindFits), new cards may be inserted (astPutFits, astPutCards,
and existing ones may be deleted (astDelFits), extracted
or changed (astSetFitsX).
When you create a FitsChan, you have the option of specifying
" functions which connect it to external data stores by reading and writing
FITS header cards. If you provide a source function, it is used to fill the
FitsChan with header cards when it is accessed for the first time. If you do not
provide a source function, the FitsChan remains empty until you explicitly enter
data into it (e.g. using astPutFits, astPutCards, astWrite or by using the
SourceFile attribute to specifying a text file from which headers should be
read). When the FitsChan is deleted, any remaining header cards in the FitsChan
can be saved in either of two ways: 1) by specifying a value for the SinkFile
attribute (the name of a text file to which header cards should be written), or 2)
by providing a sink function (used to to deliver header cards to an external
data store). If you do not provide a sink function or a value for SinkFile,
any header cards remaining when the FitsChan is deleted will be lost, so you
should arrange to extract them first if necessary (e.g. using astFindFits or
Coordinate system information may be described using FITS header cards using
several different conventions, termed
" . When an AST Object is
written to (or read from) a FitsChan, the value of the FitsChan
’ s Encoding
attribute determines how the Object is converted to (or from) a description
involving FITS header cards. In general, different encodings will result in
different sets of header cards to describe the same Object. Examples of encodings
include the DSS encoding (based on conventions used by the STScI Digitised
Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard)
and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS
The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings.
The detailed behaviour of astRead and astWrite, when used with a FitsChan, depends on the encoding in use. In general, however, all successful use of astRead is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the astRetainFits function). An unsuccessful call of astRead (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged.
If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using astWrite will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence.
FitsChan also has the following attributes:
AllWarnings: A list of the available conditions
AltAxes: Controls generation of FITS-WCS alternate axis descriptions
Card: Index of current FITS card in a FitsChan
CardComm: The comment of the current FITS card in a FitsChan
CardName: The keyword name of the current FITS card in a FitsChan
CardType: The data type of the current FITS card in a FitsChan
CarLin: Ignore spherical rotations on CAR projections?
CDMatrix: Use a CD matrix instead of a PC matrix?
Clean: Remove cards used whilst reading even if an error occurs?
DefB1950: Use FK4 B1950 as default equatorial coordinates?
Encoding: System for encoding Objects as FITS headers
FitsAxisOrder: Sets the order of WCS axes within new FITS-WCS headers
FitsDigits: Digits of precision for floating-point FITS values
ForceTab: Force use of the FITS
Ncard: Number of FITS header cards in a FitsChan
Nkey: Number of unique keywords in a FitsChan
PolyTan: Use ??m
keywords to define distorted TAN projection?
SipReplace: Replace SIP inverse transformation?
SipOK: Use Spitzer Space Telescope keywords to define distortion?
SipReplace: Replace SIP inverse transformation?
TabOK: Should the FITS
" algorithm be recognised?
Warnings: Produces warnings about selected conditions
astDelFits: Delete the current FITS card in a FitsChan
astEmptyFits: Delete all cards in a FitsChan
astFindFits: Find a FITS card in a FitsChan by keyword
astGetFitsX: Get a keyword value from a FitsChan
astGetTables: Retrieve any FitsTables from a FitsChan
astPurgeWCS: Delete all WCS-related cards in a FitsChan
astPutCards: Stores a set of FITS header card in a FitsChan
astPutFits: Store a FITS header card in a FitsChan
astPutTables: Store multiple FitsTables in a FitsChan
astReadFits: Read cards in through the source function
astRemoveTables: Remove one or more FitsTables from a FitsChan
astRetainFits: Ensure current card is retained in a FitsChan
astSetFitsX: Store a new keyword value in a FitsChan
astShowFits: Display the contents of a FitsChan on standard output
astTableSource: Register a source function for FITS table access
astTestFits: Test if a keyword has a defined value in a FitsChan
astWriteFits: Write all cards out to the sink function
AST_SHOWFITS: Display the contents of a FitsChan on standard output