path: root/ast/sun211.tex

\documentclass[twoside,11pt]{starlink}

% ? Specify used packages
% ? End of specify used packages

% -----------------------------------------------------------------------------
% ? Document identification
% Fixed part
\stardoccategory    {Starlink User Note}
\stardocinitials    {SUN}
\stardocsource      {sun\stardocnumber}

% Variable part - replace [xxx] as appropriate.
\stardocnumber      {211.27}
\stardocauthors     {R.F. Warren-Smith \& D.S. Berry}
\stardocdate        {26th October 2016}
\stardoctitle     {AST\linebreak%
                                A Library for Handling\linebreak%
                                World Coordinate Systems\linebreak%
                                in Astronomy}
\stardoccopyright   {Copyright (C) 2014 Science \& Technology Facilities Council}
\stardocversion     {V8.3}
\stardocmanual      {Programmer's Guide\\(C Version)}
\startitlepic{
   \includegraphics[width=0.25\textwidth]{sun211_figures/fronta}~~~~~\hfill
   \includegraphics[width=0.25\textwidth]{sun211_figures/frontb}~~~~~\hfill
   \includegraphics[width=0.25\textwidth]{sun211_figures/frontc}
}
\stardocabstract  {
The AST library provides a comprehensive range of facilities for
attaching world coordinate systems to astronomical data, for
retrieving and interpreting that information in a variety of formats,
including FITS-WCS, and for generating graphical output based on it.

This programmer's manual should be of interest to anyone writing
astronomical applications which need to manipulate coordinate system
data, especially celestial or spectral coordinate systems. AST is portable and
environment-independent.
}
% ? End of document identification
% -----------------------------------------------------------------------------
% ? Document specific \providecommand or \newenvironment commands.

\providecommand{\appref}[1]{Appendix~\ref{#1}}
\providecommand{\secref}[1]{\S\ref{#1}}

\providecommand{\fitskey}[3]{{#1}&{#2}&{#3}\\}

% Use {\tt ... } as \texttt{...} does not work if there are new lines in #1
\providecommand{\sstsynopsis}[1]{\sstdiytopic{Synopsis}{\tt #1}}

%  Format the constructor section.
\providecommand{\sstconstructor}[1]{\sstdiytopic{Constructor Function}{#1}}

% ? End of document specific commands
% -----------------------------------------------------------------------------
%  \htmlref{Title}{Title} Page.
%  ===========
\begin{document}
\scfrontmatter

\begin{center}
\emph{This is the C version of this document.\\
  For the Fortran version, please see \xref{SUN/210}{sun210}{}.}
\end{center}

% Main text of document.
\vspace{7mm}
\section{Introduction}

Welcome to the AST library. If you are writing software for astronomy
and need to use celestial coordinates (\emph{e.g.}\ RA and Dec), spectral
coordinates (\emph{e.g.}\ wavelength, frequency, \emph{etc.}), or
other coordinate system information, then this library should be of
interest. It provides solutions for most of the problems you will meet
and allows you to write robust and flexible software. It is able to read
and write WCS information in a variety of formats, including
\htmladdnormallink{FITS-WCS}{http://fits.gsfc.nasa.gov/fits_wcs.html}.

%\subsection{TBW---What is a World Coordinate \htmlref{System}{System}?}

\subsection{What Problems Does AST Tackle?}

Here are some of the main problems you may face when handling world
coordinate system (WCS) information and the solutions that AST
provides:

\begin{description}
\item[1. The Variety of Coordinate Systems]\mbox{}\\
Astronomers use a wide range of differing coordinate systems to describe
positions within a variety of physical domains. For instance, there are a
large number of celestial coordinate systems in use within astronomy to
describe positions on the sky. Understanding these, and knowing how to
convert coordinates between them, can require considerable expertise. It
can also be difficult to decide which of them your software should support.
The same applies to coordinate systems describing other domains, such as
position within an electro-magnetic spectrum.

\textbf{Solution.} AST has built-in knowledge of many coordinate systems
and allows you to convert freely between them without specialist
knowledge. This avoids the need to embed details of specific
coordinate systems in your software. You also benefit automatically
when new coordinate systems are added to AST.

\item[2. Storing and Retrieving WCS Information]\mbox{}\\
Storing coordinate system information in astronomical datasets and
retrieving it later can present a considerable challenge. Typically,
it requires knowledge of rather complex conventions
(\emph{e.g.}\ FITS) which are low-level, often mis-interpreted and may
be subject to change. Exchanging information with other software
systems is further complicated by the number of different conventions
in use.

\textbf{Solution.} AST combines a unifying high-level description of WCS
information with the ability to save and restore this using a variety
of formats. Details of the formats, which include FITS, are handled
internally by AST. This frees you from the need to understand them or
embed the details in your software. Again, you benefit automatically
when new formats are added to AST.

\item[3. Generating Graphical Output]\mbox{}\\
Producing graphical displays involving curvilinear coordinate systems,
such as celestial coordinate grids, can be complicated. Particular
difficulties arise when handling large areas of sky, the polar regions
and discontinuous (\emph{e.g.}\ segmented) sky projections.  Even just
numbering and labelling curvilinear axes is rarely straightforward.

\textbf{Solution.} AST provides plotting facilities especially designed
for use with curvilinear coordinate systems. These include the
plotting of axes and complete labelled coordinate grids.  A large
number of options are provided for tailoring the output to your
specific needs. Three dimensional coordinate grids can also be produced.

\item[4. Aligning Data from Different Sources]\mbox{}\\
One of the main uses of coordinate systems is to facilitate the
inter-comparison of data from different sources. A typical use might
be to plot (say) radio contours over an optical image.  In practice,
however, different celestial coordinate systems may have been used,
making accurate alignment far from simple.

\textbf{Solution} AST provides a one-step method of aligning datasets,
searching for all possible intermediate coordinate systems.  This
makes it simple to directly inter-relate the pixel coordinates of
different datasets.

\item[5. Handling Different Types of Coordinate \htmlref{System}{System}]\mbox{}\\
Not all coordinate systems used in astronomy are celestial ones, so if
you are writing general-purpose software such as (say) a display tool,
you may also need to handle axes representing wavelength, distance,
time or whatever else comes along. Obviously, you would prefer not to
handle each one as a special case.

\textbf{Solution} AST uses the same flexible high-level model to
describe all types of coordinate system. This allows you to write
software that handles different kinds of coordinate axis without
introducing special cases.
\end{description}

\subsection{Other Design Objectives}

As well as its scientific objectives, the AST library's design
includes a number of technical criteria intended to make it applicable
to as wide a range of projects as possible. The main considerations
are described here:

\begin{enumerate}
\item {\bf{Minimum Software Dependencies.}}
The AST library depends on no other other software\footnote{It comes with
bundled copies of the ERFA and
\xref{Starlink PAL libraries}{sun268}{} which are built
at the same time as the other AST internal libraries. Alternatively, external
PAL and ERFA libraries may be used by specifying the ``\texttt{--with-external\_pal}'' option when configuring AST}.

\item {\bf{Environment Independence.}}
AST is designed so that it can operate in a variety of ``programming
environments'' and is not tied to any particular one. To allow this,
it uses simple, flexible interfaces to obtain the following services:

\begin{itemize}
\item {\bf{Data Storage.}} Data I/O operations are based on text
and/or FITS headers. This makes it easy to interface to a wide variety
of astronomical data formats in a machine-independent way.

\item {\bf{Graphics.}} Graphical output is produced \emph{via} a
simple generic graphics interface, which may easily be re-implemented
over different graphics systems. AST provides a default implementation
based on the widely-used PGPLOT graphics system
(\xref{SUN/15}{sun15}{}).

\item {\bf{Error Handling.}} Error messages are written to standard
error by default, but go through a simple generic interface similar to
that used for graphics (above). This permits error message delivery
\emph{via} other routes when necessary (\emph{e.g.} in a graphical
interface).
\end{itemize}

\item {\bf{Multiple Language Support.}}
AST has been designed to be called from more than one language.
Both C and Fortran interfaces are available (see
\xref{SUN/210}{sun210}{} for the Fortran version)
and use from C$++$ is also straightforward if the C interface is
included using:

\begin{small}
\begin{terminalv}
extern "C" {
#include "ast.h"
}
\end{terminalv}
\end{small}

A JNI interface (known as ``JNIAST'' - see
\url{http://www.starlink.ac.uk/jniast/}) has also been developed by Starlink
which allows AST to be used from Java.

\item {\bf{\htmlref{Object}{Object} Oriented Design.}}
AST uses ``object oriented'' techniques internally in order to provide
a flexible and easily-extended programming model.  A fairly
traditional calling interface is provided, however, so that the
library's facilities are easily accessible to programmers using
C and Fortran.

\item {\bf{Portability.}}
AST is implemented entirely in ANSI standard C and, when called
\emph{via} its C interface, makes no explicit use of any
machine-dependent facilities.

The Fortran interface is, unavoidably, machine dependent. However, the
potential for problems has been minimised by encapsulating the
interface layer in a compact set of C macros which facilitate its
transfer to other platforms. No Fortran compiler is needed to build
the library.

Currently, AST is supported by Starlink on PC~Linux, Sun~Solaris and
Tru64~Unix (formerly DEC~UNIX) platforms.
\end{enumerate}

\subsection{What Does ``AST'' Stand For?}

The library name ``AST'' stands for ``ASTrometry Library''. The name
arose when it was thought that knowledge of ``astrometry''
(\emph{i.e.}\ celestial coordinate systems) would form the bulk of the
library.  In fact, it turns out that astrometry forms only a minor
component, but the name AST has stuck.

\cleardoublepage
\section{Overview of AST Concepts}

This section presents a brief overview of AST concepts. It is intended
as a basic orientation course before you move on to the more technical
considerations in subsequent sections.

\subsection{\label{ss:mappingoverview}Relationships Between Coordinate Systems}

The relationships between coordinate systems are represented in AST by
Objects called Mappings. A \htmlref{Mapping}{Mapping} does not represent a coordinate
system itself, but merely the process by which you move from one
coordinate system to another related one.

   A convenient picture of a Mapping is as a ``black box''
   (Figure~\ref{fig:mapping}) into which you can feed sets of
   coordinates.
   \begin{figure}[bhtp]
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/mapping}
   \caption{A Mapping viewed as a ``black box'' for transforming coordinates.}
   \label{fig:mapping}
   \end{center}
   \end{figure}

For each set you feed in, the Mapping returns a corresponding set of
transformed coordinates. Since each set of coordinates represents a
point in a coordinate space, the Mapping acts to inter-relate
corresponding positions in the two spaces, although what these spaces
represent is unspecified.  Notice that a Mapping need not have the
same number of input and output coordinates. That is, the two
coordinate spaces which it inter-relates need not have the same number
of dimensions.

In many cases, the transformation can, in principle, be performed in
either direction: either from the \emph{input} coordinate space to the
\emph{output}, or \emph{vice versa}. The first of these is termed the
\emph{forward} transformation and the other the \emph{inverse}
transformation.


\textbf{Further reading:} For a more complete discussion of Mappings,
see~\secref{ss:mappings}.

\subsection{\label{ss:mappingselection}Mappings Available}

The basic concept of a \htmlref{Mapping}{Mapping} (\secref{ss:mappingoverview}) is rather
generic and obviously it is necessary to have specific Mappings that
implement specific relationships between coordinate systems. AST
provides a range of these, to perform transformations such as the
following and, where appropriate, their inverses:

\begin{itemize}
\item Conversions between various celestial coordinate systems (the
\htmlref{SlaMap}{SlaMap}).

\item Conversions between various spectral coordinate systems (the
\htmlref{SpecMap}{SpecMap} and \htmlref{GrismMap}{GrismMap}).

\item Conversions between various time systems (the \htmlref{TimeMap}{TimeMap}).

\item Conversion between 2-dimensional spherical celestial coordinates
(longitude and latitude) and a 3-dimensional vectorial positions (the \htmlref{SphMap}{SphMap}).

\item Various projections of the celestial sphere on to 2-dimensional
coordinate spaces---\emph{i.e.}\ map projections (the \htmlref{DssMap}{DssMap} and \htmlref{WcsMap}{WcsMap}).

\item Permutation, introduction and elimination of coordinates (the
\htmlref{PermMap}{PermMap}).

\item Various linear coordinate transformations (the \htmlref{MatrixMap}{MatrixMap}, \htmlref{WinMap}{WinMap},
\htmlref{ShiftMap}{ShiftMap} and \htmlref{ZoomMap}{ZoomMap}).

\item General N-dimensional polynomial transformations (the \htmlref{PolyMap}{PolyMap}).

\item Lookup tables (the \htmlref{LutMap}{LutMap}).

\item General-purpose transformations expressed using arithmetic
operations and functions similar to those available in C (the
\htmlref{MathMap}{MathMap}).

\item Transformations for internal use within a program, based on
private transformation functions which you write yourself in C (the
\htmlref{IntraMap}{IntraMap}).
\end{itemize}

\textbf{Further reading:} For a more complete description of each of the
Mappings mentioned above, see its entry in
\appref{ss:classdescriptions}. In addition, see the discussion of the
PermMap in \secref{ss:permmapexample}, the \htmlref{UnitMap}{UnitMap} in
\secref{ss:unitmapexample} and the IntraMap in
\secref{ss:intramaps}. The ZoomMap is used as an example throughout
\secref{ss:primer}.

\subsection{\label{ss:cmpmapoverview}Compound Mappings}

The Mappings described in \secref{ss:mappingselection} provide a set
of basic building blocks from which more complex Mappings may be
constructed. The key to doing this is a type of \htmlref{Mapping}{Mapping} called a
\htmlref{CmpMap}{CmpMap}, or compound Mapping.  A CmpMap's role is, in principle, very
simple: it allows any other pair of Mappings to be joined together
into a single entity which behaves as if it were a single Mapping. A
CmpMap is therefore a container for another pair of Mappings.

   A pair of Mappings may be combined using a CmpMap in either of two
   ways. The first of these, \emph{in series}, is illustrated in
   Figure~\ref{fig:seriescmpmap}.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/series}
   \caption[A CmpMap composed of two component Mappings joined in series]{A CmpMap (compound Mapping) composed of two component
   Mappings joined in series. The output coordinates of the first Mapping
   feed into the input coordinates of the second one, so that the whole
   entity behaves like a single Mapping.}
   \label{fig:seriescmpmap}
   \end{center}
   \end{figure}


   Here, the transformations implemented by each component Mapping are
   performed one after the other, with the output from the first Mapping
   feeding into the second.  The second way, \emph{in parallel}, is shown in
   Figure~\ref{fig:parallelcmpmap}.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.5\textwidth]{sun211_figures/parallel}
   \caption[A CmpMap composed of two Mappings joined in parallel.]{A CmpMap composed of two Mappings joined in parallel. Each
   component Mapping acts on a complementary subset of the input and
   output coordinates.}
   \label{fig:parallelcmpmap}
   \end{center}
   \end{figure}

In this case, each Mapping acts on a complementary subset of the
input and output coordinates.\footnote{A pair of Mappings can be combined
in a third way using a \htmlref{TranMap}{TranMap}. A TranMap allows the forward
transformation of one Mapping to be combined with the inverse
transformation of another to produce a single Mapping.}

   The CmpMap forms the key to building arbitrarily complex Mappings
   because it is itself a form of Mapping. This means that a CmpMap may
   contain other CmpMaps as components
   (\emph{e.g.}\ Figure~\ref{fig:complexcmpmap}). This nesting of CmpMaps
   can be repeated indefinitely, so that complex Mappings may be built in
   a hierarchical manner out of simper ones.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.65\textwidth]{sun211_figures/complex}
   \caption[CmpMaps may be nested in order to
   construct complex Mappings out of simpler building blocks.]{CmpMaps
   (compound Mappings) may be nested in order to
   construct complex Mappings out of simpler building blocks.}
   \label{fig:complexcmpmap}
   \end{center}
   \end{figure}
   This gives AST great flexibility in the coordinate transformations it
   can describe.

\textbf{Further reading:} For a more complete description of CmpMaps,
see \secref{ss:cmpmaps}. Also see the CmpMap entry in
\appref{ss:classdescriptions}.

\subsection{Representing Coordinate Systems}

   While Mappings (\secref{ss:mappingoverview}) represent the
   relationships between coordinate systems in AST, the coordinate
   systems themselves are represented by Objects called Frames
   (Figure~\ref{fig:frames}).
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.55\textwidth]{sun211_figures/frames}
   \caption[Representing coordinate systems as Frames.]{(a) A basic Frame is used to represent a Cartesian coordinate
   system, here 2-dimensional. (b) A \htmlref{SkyFrame}{SkyFrame} represents a (spherical)
   celestial coordinate system. (c) The axis order of any \htmlref{Frame}{Frame} may be
   permuted to match the coordinate space it describes.}
   \label{fig:frames}
   \end{center}
   \end{figure}

A Frame is similar in concept to the frame you might draw around a
graph.  It contains information about the labels which appear on the
axes, the axis units, a title, knowledge of how to format the
coordinate values on each axis, \emph{etc.}  An AST Frame is not,
however, restricted to two dimensions and may have any number of axes.

A basic Frame may be used to represent a Cartesian coordinate system
by setting values for its \emph{attributes} (all AST Objects have
values associated with them called attributes, which may be set and
enquired).  Usually, this would involve setting appropriate axis
labels and units, for example.  Functions are provided for use with
Frames to perform operations such as formatting coordinate values as
text, calculating distances between points, interchanging axes,
\emph{etc.}

There are several more specialised forms of Frame, which provide the
additional functionality required when handling coordinates within some
specific physical domain. This ranges from tasks such as formatting axis
values, to complex tasks such as determining the transformation between
any pair of related coordinate systems. For instance, the SkyFrame
(Figure~\ref{fig:frames}b,c), represents celestial coordinate systems,
the \htmlref{SpecFrame}{SpecFrame} represents spectral coordinate systems, and the \htmlref{TimeFrame}{TimeFrame}
represents time coordinate systems. All these provide a wide range of
different systems for describing positions within their associated physical
domain, and these may be selected by setting appropriate attributes.

   As with compound Mappings (\secref{ss:cmpmapoverview}), it is possible
   to merge two Frames together to form a compound Frame, or \htmlref{CmpFrame}{CmpFrame}, in
   which both sets of axes are combined.  One could, for example, have
   celestial coordinates on two axes and an unrelated coordinate
   (wavelength, perhaps) on a third (Figure~\ref{fig:cmpframe}).
   Knowledge of the relationships between the axes is preserved
   internally by the process of constructing the CmpFrame which
   represents them.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.4\textwidth]{sun211_figures/cmpframe}
   \caption[A CmpFrame (compound Frame) formed by combining two simpler
   Frames.]{A CmpFrame (compound Frame) formed by combining two simpler
   Frames. Note how the special relationship which exists between the RA
   and Dec axes is preserved within this data structure. As with compound
   Mappings (Figure~\ref{fig:complexcmpmap}), CmpFrames may be nested in
   order to build more complex Frames.}
   \label{fig:cmpframe}
   \end{center}
   \end{figure}

\textbf{Further reading:} For a more complete description of Frames see
\secref{ss:frames}, for SkyFrames see \secref{ss:skyframes} and for
SpecFrames see \secref{ss:specframes}.  Also see the Frame, SkyFrame,
SpecFrame, TimeFrame and CmpFrame entries in \appref{ss:classdescriptions}.

\subsection{Networks of Coordinate Systems}

   Mappings and Frames may be connected together to form networks called
   FrameSets, which are used to represent sets of inter-related
   coordinate systems (Figure~\ref{fig:frameset}).
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.65\textwidth]{sun211_figures/frameset}
   \caption[A FrameSet is a network of Frames.]{A FrameSet is a network of Frames inter-connected by Mappings
   such that there is exactly one conversion path, \emph{via} Mappings,
   between any pair of Frames.}
   \label{fig:frameset}
   \end{center}
   \end{figure}


A \htmlref{FrameSet}{FrameSet} may be extended by adding a new \htmlref{Frame}{Frame} to it, together with
an associated \htmlref{Mapping}{Mapping} which relates the new coordinate system to one
which is already present.  This process ensures that there is always
exactly one path, \emph{via} Mappings, between any pair of Frames.  A
function is provided for identifying this path and returning the
complete Mapping.

One of the Frames in a FrameSet is termed its \emph{base} Frame.  This
underlies the FrameSet's purpose, which is to calibrate datasets and
other entities by attaching coordinate systems to them.  In this
context, the base Frame represents the ``native'' coordinate system
(for example, the pixel coordinates of an image).  Similarly, one
Frame is termed the \emph{current} Frame and represents the
``currently-selected'' coordinates.  It might, typically, be a
celestial or spectral coordinate system and would be used during
interactions with
a user, as when plotting axes on a graph or producing a table of
results.  Other Frames within the FrameSet represent a library of
alternative coordinate systems which a software user can select by
making them current.

\textbf{Further reading:} For a more complete description of
FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. Also
see the FrameSet entry in \appref{ss:classdescriptions}.

\subsection{Input/Output Facilities}

AST allows you to convert any kind of \htmlref{Object}{Object} into a stream of text
which contains a full description of that Object. This text may be
written out by one program and read back in by another, thus allowing
the original Object to be reconstructed.

The filter which converts Objects into text and back again is itself a
kind of Object, called a \htmlref{Channel}{Channel}. A Channel provides a number of
options for controlling the information content of the text, such as
the addition of comments for human interpretation.  It is also
possible to intercept the text being processed by a Channel so that it
may be redirected to/from any chosen external data store, such as a
text file, an astronomical dataset, or a network connection.

The text format used by the basic Channel class is peculiar to the AST
library - no other software will understand it. However, more specialised
forms of Channel are provided which use text formats more widely
understood.

To further facilitate the storage of coordinate system information in
astronomical datasets, a more specialised form of Channel called a
\htmlref{FitsChan}{FitsChan} is provided. Instead of using free-format text, a FitsChan
converts AST Objects to and from FITS header cards. It also allows the
information to be encoded in the FITS cards in a number of ways
(called \emph{encodings}), so that WCS information from a variety of
sources can be handled.

Another sub-class of Channel, called \htmlref{XmlChan}{XmlChan}, is a specialised form of
Channel that stores the text in the form of XML markup. Currently, two
markup formats are provided by the XmlChan class, one is closely related
to the text format produced by the basic Channel class (currently, no
schema or DTD is available describing this format). The other is a subset
of an early draft of the IVOA Space-Time-Coordinates XML (STC-X) schema
(V1.20) described at
\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html
}\footnote{XML documents which use only the subset of the STC schema
supported by AST can be read by the XmlChan class to produce
corresponding AST objects (subclasses of the \htmlref{Stc}{Stc} class). However, the
reverse is not possible. That is, AST objects can not currently be
written out in the form of STC documents.}. The version of STC-X that has
been adopted by the IVOA differs in several significant respects from
V1.20, and therefore this XmlChan format is of historical interest only.

Finally, the \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing
IVOA STC-S region descriptions. STC-S (see
\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string
syntax that allows simple specification of STC metadata. AST supports a
subset of the STC-S specification, allowing an STC-S description of a
region within an AST-supported astronomical coordinate system to be converted
into an equivalent AST \htmlref{Region}{Region} object, and vice-versa.

\textbf{Further reading:} For a more complete description of Channels
see \secref{ss:channels} and for FitsChans see \secref{ss:nativefits}
and \secref{ss:foreignfits}. Also see the Channel and FitsChan entries
in \appref{ss:classdescriptions} and the \htmlref{Encoding}{Encoding} entry in
\appref{ss:attributedescriptions}.

\subsection{Producing Graphical Output}

Two dimensional graphical output is supported by a specialised form of
\htmlref{FrameSet}{FrameSet} called
a \htmlref{Plot}{Plot}, whose base \htmlref{Frame}{Frame} corresponds with the native coordinates of
the underlying graphics system.  Plotting operations are specified in
\emph{physical coordinates} which correspond with the Plot's current
Frame. Typically, this might be a celestial coordinate system.

Three dimensional plotting is also supported, via the \htmlref{Plot3D}{Plot3D} class -
sub-class of Plot.

Operations, such as drawing lines, are automatically transformed from
physical to graphical coordinates before plotting, using an adaptive
algorithm which ensures smooth curves (because the transformation is
usually non-linear).  ``Missing'' coordinates (\emph{e.g.}\ graphical
coordinates which do not project on to the celestial sphere),
discontinuities and generalised clipping are all consistently handled.
It is possible, for example, to plot in equatorial coordinates and
clip in galactic coordinates.  The usual plotting operations are
provided (text, markers), but a geodesic curve replaces the primitive
straight line element.  There is also a separate function for drawing
axis lines, since these are normally not geodesics.

In addition to drawing coordinate grids over an area of the sky, another
common use of the Plot class is to produce line plots such as flux
against wavelength, displacement again time, \emph{etc}. For these
situations the current Frame of the Plot would be a compound Frame
(\htmlref{CmpFrame}{CmpFrame}) containing a pair of 1-dimensional Frames - the first
representing the X axis quantity (wavelength, time, etc), and the second
representing the Y axis quantity (flux, displacement, etc). The Plot
class includes an option for axes to be plotted logarithmically.

   Perhaps the most useful graphics function available is for drawing
   fully annotated coordinate grids (\emph{e.g.}\ Figure~\ref{fig:gridplot}).
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.6\textwidth]{sun211_figures/gridplot_bw}
   \caption[A labelled coordinate grid for an all-sky zenithal equal area
   projection in ecliptic coordinates.]{A labelled coordinate grid for an all-sky zenithal equal area
   projection in ecliptic coordinates. This was composed and drawn
   \emph{via} a Plot using a
   single function call.}
   \label{fig:gridplot}
   \end{center}
   \end{figure}

This uses a general algorithm which does not depend on knowledge of
the coordinates being represented, so can also handle
programmer-defined coordinate systems.  Grids for all-sky projections,
including polar regions, can be drawn and most aspects of the output
(colour, line style, \emph{etc.}) can be adjusted by setting
appropriate Plot attributes.

\textbf{Further reading:} For a more complete description of
Plots and how to produce graphical output, see \secref{ss:plots}. Also
see the Plot entry in \appref{ss:classdescriptions}.

\cleardoublepage
\section{\label{ss:howto}How To\ldots}

For those of you with a plane to catch, this section provides some
instant templates and recipes for performing the most
commonly-required operations using AST, but without going into
detail. The examples given (sort of) follow on from each other, so you
should be able to construct a variety of programs by piecing them
together.  Note that some of them appear longer than they actually
are, because we have included plenty of comments and a few options
that you probably won't need.

If any of this material has you completely baffled, then you may want
to read the introduction to AST programming concepts in
\secref{ss:primer} first. Otherwise, references to more detailed
reading are given after each example, just in case they don't quite do
what you want.

\subsection{\ldots Obtain and Install AST}
The AST library is available both as a stand-alone package and also as
part of the Starlink Software Collection\footnote{The Starlink Software
Collection can be downloaded from
\url{http://www.starlink.ac.uk/Download/}.}. If your site has the Starlink
Software Collection installed then AST should already be available.

If not, you can download the AST library by itself from
\url{http://www.starlink.ac.uk/ast/}.

\subsection{\ldots Structure an AST Program}

An AST program normally has the following structure:

\begin{small}
\begin{terminalv}
/* Include the interface to the AST library. */
#include "ast.h"

/* Main program (or could be any function). */
main () {
   <normal C declarations and statements>

/* Enclose the parts which use AST between the astBegin and astEnd macros. */
   astBegin;
   <C statements which use AST>
   astEnd;

   <maybe more C statements>
}
\end{terminalv}
\end{small}

The use of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} is optional, but has the effect of
tidying up after you have finished using AST, so is normally
recommended. For more details of this, see \secref{ss:contexts}. For
details of how to access the ``ast.h'' header file, see
\secref{ss:accessingheaderfile}.

\subsection{\label{ss:howtobuild}\ldots Build an AST Program}

To build a simple AST program that doesn't use graphics, use:

\begin{small}
\begin{terminalv}
cc program.c -L/star/lib -I/star/include `ast_link` -o program
\end{terminalv}
\end{small}

To build a program which uses PGPLOT for graphics, use:

\begin{small}
\begin{terminalv}
cc program.c -L/star/lib `ast_link -pgplot` -o program
\end{terminalv}
\end{small}

For more details about accessing the ``ast.h'' header file, see
\secref{ss:accessingheaderfile}. For more
details about linking programs, see \secref{ss:linking} and the
description of the ``\htmlref{ast\_link}{ast\_link}'' command in
\appref{ss:commanddescriptions}.

\subsection{\label{ss:howtoreadwcs}\ldots Read a WCS Calibration from a Dataset}

Precisely how you extract world coordinate system (WCS) information
from a dataset obviously depends on what type of dataset it
is. Usually, however, you should be able to obtain a set of FITS
header cards which contain the WCS information (and probably much more
besides). Suppose that ``cards'' is a pointer to a string
containing a complete set of concatenated FITS header cards (such as
produced by the CFITSIO function fits\_hdr2str). Then proceed as follows:

\begin{small}
\begin{terminalv}
fitsfile *fptr;
AstFitsChan *fitschan;
AstFrameSet *wcsinfo;
char *header;
int nkeys, status;

...

/* Obtain all the cards in the header concatenated into a single dynamically
   allocated null-terminated character string. Note, we do not exclude
   any cards since we may later modify the WCS information within the
   header and consequently want to write the entire header out again. */
   if( fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) )
          printf(" Error getting header\n");
   ...

/* Header obtained succesfully... */
   } else {

/* Create a FitsChan and fill it with FITS header cards. */
      fitschan = astFitsChan( NULL, NULL, "" );
      astPutCards( fitschan, header );

/* Free the memory holding the concatenated header cards. */
      header = free( header );

/* Read WCS information from the FitsChan. */
      wcsinfo = astRead( fitschan );

      ...

\end{terminalv}
\end{small}


The result should be a pointer, ``wcsinfo'', to a \htmlref{FrameSet}{FrameSet} which
contains the WCS information. This pointer can now be used to perform
many useful tasks, some of which are illustrated in the following
recipes.

Some datasets which do not easily yield FITS header cards may require
a different approach, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan}
(\secref{ss:channels}) rather than a \htmlref{FitsChan}{FitsChan}. In the case of the
Starlink NDF data format, for example, all the above may be replaced
by a single call to the function
\xref{ndfGtwcs}{sun33}{ndfGtwcs}---see \xref{SUN/33}{sun33}{}.  The
whole process can probably be encapsulated in a similar way for
most data systems, whether they use FITS header cards or not.

For more details about reading WCS information from datasets, see
\secref{ss:identifyingfitsencoding} and
\secref{ss:readingforeignfits}. For a more general description of
FitsChans and their use with FITS header cards, see
\secref{ss:nativefits} and \secref{ss:foreignfits}. For more details
about FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}.

\subsection{\ldots Validate WCS Information}

Once you have read WCS information from a dataset, as in
\secref{ss:howtoreadwcs}, you may wish to check that you have been
successful. The following will detect and classify the things that
might possibly go wrong:

\begin{small}
\begin{terminalv}
#include <string.h>

...

if ( !astOK ) {
   <an error occurred (a message will have been issued)>
} else if ( wcsinfo == AST__NULL ) {
   <there was no WCS information present>
} else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) {
   <something unexpected was read (i.e. not a FrameSet)>
} else {
   <WCS information was read OK>
}
\end{terminalv}
\end{small}

For more information about detecting errors in AST functions, see
\secref{ss:errordetection}. For details of how to validate input data
read by AST, see \secref{ss:validatinginput} and
\secref{ss:readingforeignfits}.

\subsection{\ldots Display AST Data}

If you have a pointer to any AST \htmlref{Object}{Object}, you can display the data
stored in that Object in textual form as follows:

\begin{small}
\begin{terminalv}
astShow( wcsinfo );
\end{terminalv}
\end{small}

Here, we have used a pointer to the \htmlref{FrameSet}{FrameSet} which we read earlier
(\secref{ss:howtoreadwcs}).  The result is written to the program's
standard output stream. This can be very useful during debugging.

For more details about using \htmlref{astShow}{astShow}, see
\secref{ss:displayingobjects}. For information about interpreting the
output, also see \secref{ss:textualoutputformat}.

\subsection{\label{ss:howtotransform}\ldots Convert Between Pixel and World Coordinates}

You may use a pointer to a \htmlref{FrameSet}{FrameSet}, such as we read in
\secref{ss:howtoreadwcs}, to transform a set of points between the
pixel coordinates of an image and the associated world coordinates. If
you are working in two dimensions, proceed as follows:

\begin{small}
\begin{terminalv}
double xpixel[ N ], ypixel[ N ];
double xworld[ N ], yworld[ N ];

...

astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld );
\end{terminalv}
\end{small}

Here, N is the number of points to be transformed, ``xpixel'' and
``ypixel'' hold the pixel coordinates, and ``xworld'' and ``yworld''
receive the returned world coordinates.\footnote{By pixel coordinates,
we mean a coordinate system in which the first pixel in the image is
centred on (1,1) and each pixel is a unit square.  Note that the world
coordinates will not necessarily be celestial coordinates, but if they
are, then they will be in radians.}  To transform in the opposite
direction, interchange the two pairs of arrays (so that the world
coordinates are given as input) and change the fifth argument of
\htmlref{astTran2}{astTran2} to zero.

To transform points in one dimension, use \htmlref{astTran1}{astTran1}. In any other
number of dimensions (or if the number of dimensions is initially
unknown), use \htmlref{astTranN}{astTranN} or \htmlref{astTranP}{astTranP}. These functions are described in
\appref{ss:functiondescriptions}.

For more information about transforming coordinates, see
\secref{ss:transforming} and \secref{ss:framesetasmapping}. For
details of how to handle missing coordinates, see
\secref{ss:badcoordinates}.

\subsection{\label{ss:howtotestforcelestial}\ldots Test if a WCS is a Celestial Coordinate System}

The world coordinate system (WCS) currently associated with an image
may often be a celestial coordinate system, but this need not
necessarily be the case. For instance, instead of right ascension and
declination, an image might have a WCS with axes representing
wavelength and slit position, or maybe just plain old pixels.

If you have obtained a WCS calibration for an image, as in
\secref{ss:howtoreadwcs}, in the form of a pointer ``wcsinfo'' to a
\htmlref{FrameSet}{FrameSet}, then you may determine if the current coordinate system is a
celestial one or not, as follows:

\begin{small}
\begin{terminalv}
AstFrame *frame;
int issky;

...

/* Obtain a pointer to the current Frame and determine if it is a
   SkyFrame. */
frame = astGetFrame( wcsinfo, AST__CURRENT );
issky = astIsASkyFrame( frame );
frame = astAnnul( frame );
\end{terminalv}
\end{small}

This will set ``issky'' to 1 if the WCS is a celestial coordinate
system, and to zero otherwise.

\subsection{\label{ss:howtotestforspectral}\ldots Test if a WCS is a Spectral Coordinate System}
Testing for a spectral coordinate system is basically the same as testing
for a celestial coordinate system (see the previous section). The one
difference is that you use the
astIsASpecFrame function
in place of the
astIsASkyFrame function.

\subsection{\label{ss:howtoformatcoordinates}\ldots Format Coordinates for Display}

Once you have converted pixel coordinates into world coordinates
(\secref{ss:howtotransform}), you may want to format them as text
before displaying them. Typically, this would convert from (say)
radians into something more comprehensible. Using the \htmlref{FrameSet}{FrameSet} pointer
``wcsinfo'' obtained in \secref{ss:howtoreadwcs} and a pair of world
coordinates ``xw'' and ``yw'' (\emph{e.g.}\ see
\secref{ss:howtotransform}), you could proceed as follows:

\begin{small}
\begin{terminalv}
#include <stdio.h>
const char *xtext, *ytext;
double xw, yw;

...

xtext = astFormat( wcsinfo, 1, xw );
ytext = astFormat( wcsinfo, 2, yw );

(void) printf( "Position = %s, %s\n", xtext, ytext );
\end{terminalv}
\end{small}

Here, the second argument to \htmlref{astFormat}{astFormat} is the axis number.

With celestial coordinates, this will usually result in sexagesimal
notation, such as ``12:34:56.7''. However, the same method may be
applied to any type of coordinates and appropriate formatting will be
employed.

For more information about formatting coordinate values and how to
control the style of formatting used, see
\secref{ss:formattingaxisvalues} and
\secref{ss:formattingskyaxisvalues}. If necessary, also see
\secref{ss:normalising} for details of how to ``normalise'' a set of
coordinates so that they lie within the standard range (\emph{e.g.}\ 0
to 24 hours for right ascension and $\pm 90^\circ$ for
declination).

\subsection{\ldots Display Coordinates as they are Transformed}

In addition to formatting coordinates as part of a program's output,
you may also want to examine coordinate values while debugging your
program. To save time, you can ``eavesdrop'' on the coordinate values
being processed every time they are transformed. For example, when
using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in
\secref{ss:howtoreadwcs} to transform coordinates
(\secref{ss:howtotransform}), you could inspect the coordinate values
as follows:

\begin{small}
\begin{terminalv}
astSet( wcsinfo, "Report=1" );
astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld );
\end{terminalv}
\end{small}

By setting the FrameSet's \htmlref{Report}{Report} attribute to 1, coordinate
transformations are automatically displayed on the program's standard
output stream, appropriately formatted, for example:

\begin{terminalv}
(42.1087, 20.2717) --> (2:06:03.0, 34:22:39)
(43.0197, 21.1705) --> (2:08:20.6, 35:31:24)
(43.9295, 22.0716) --> (2:10:38.1, 36:40:09)
(44.8382, 22.9753) --> (2:12:55.6, 37:48:55)
(45.7459, 23.8814) --> (2:15:13.1, 38:57:40)
(46.6528, 24.7901) --> (2:17:30.6, 40:06:25)
(47.5589, 25.7013) --> (2:19:48.1, 41:15:11)
(48.4644, 26.6149) --> (2:22:05.6, 42:23:56)
(49.3695, 27.5311) --> (2:24:23.1, 43:32:41)
(50.2742, 28.4499) --> (2:26:40.6, 44:41:27)
\end{terminalv}

For a complete description of the Report attribute, see its entry in
\appref{ss:attributedescriptions}.  For further details of how to set
and enquire attribute values, see \secref{ss:settingattributes} and
\secref{ss:gettingattributes}.

\subsection{\ldots Read Coordinates Entered by a User}

In addition to writing out coordinate values generated by your program
(\secref{ss:howtoformatcoordinates}), you may also need to accept
coordinates entered by a user, or perhaps read from a file. In this
case, you will probably want to allow ``free-format'' input, so that
the user has some flexibility in the format that can be used. You will
probably also want to detect any typing errors.

Let's assume that you want to read a number of lines of text, each
containing the world coordinates of a single point, and to split each
line into individual numerical coordinate values. Using the \htmlref{FrameSet}{FrameSet}
pointer ``wcsinfo'' obtained earlier (\secref{ss:howtoreadwcs}), you
could proceed as follows:

\begin{small}
\begin{terminalv}
#include <stdio.h>
char *t;
char text[ MAXCHARS + 2 ];
double coord[ 10 ];
int iaxis, n, naxes;

...

/* Obtain the number of coordinate axes (if not already known). */
naxes = astGetI( wcsinfo, "Naxes" );

/* Loop to read each line of input text, in this case from the
   standard input stream (your programming environment will probably
   provide a better way of reading text than this). Set the pointer
   "t" to the start of each line read. */
while ( t = fgets( text, MAXCHARS + 2, stdin ) ) {

/* Attempt to read a coordinate for each axis. */
   for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {
      n = astUnformat( wcsinfo, iaxis, t, &coord[ iaxis - 1 ] );

/* If nothing was read and this is not the first axis or the
   end-of-string, try stepping over a separator and reading again. */
   if ( !n && ( iaxis > 1 ) && *t )
      n = astUnformat( wcsinfo, iaxis, ++t, &coord[ iaxis - 1 ] );

/* Quit if nothing was read, otherwise move on to the next coordinate. */
      if ( !n ) break;
      t += n;
   }

/* Test for the possible errors that may occur... */

/* Error detected by AST (a message will have been issued). */
   if ( !astOK ) {
      break;

/* Error in input data at character t[n]. */
   } else if ( *t || !n ) {
      <handle the error, or report your own message here>
      break;

   } else {
      <coordinates were read OK>
   }
}
\end{terminalv}
\end{small}

This algorithm has the advantage of accepting free-format input in
whatever style is appropriate for the world coordinates in use (under
the control of the FrameSet whose pointer you provide). For example,
wavelength values might be read as floating point numbers
(\emph{e.g.}\ ``1.047'' or ``4787''), whereas celestial positions
could be given in sexagesimal format (\emph{e.g.}\ ``12:34:56'' or
``12~34.5'') and would be converted into radians. Individual
coordinate values may be separated by white space and/or any
non-ambiguous separator character, such as a comma.

For more information on reading coordinate values using the
\htmlref{astUnformat}{astUnformat} function, see \secref{ss:unformattingaxisvalues}. For
details of how sexagesimal formats are handled, and the forms of input
that may be used for celestial coordinates, see
\secref{ss:unformattingskyaxisvalues}.

\subsection{\label{ss:howtocreatenewwcs}\ldots Create a New WCS Calibration}

This section describes how to add a WCS calibration to a data set which you
are creating from scratch, rather than modifying an existing data set.

In most common cases, the simplest way to create a new WCS calibration
from scratch is probably to create a set of strings describing the
required calibration in terms of the keywords used by the FITS WCS
standard, and then convert these strings into an AST \htmlref{FrameSet}{FrameSet} describing
the calibration. This FrameSet can then be used for many other purposes, or
simply stored in the data set.

The full FITS-WCS standard is quite involved, currently running to four
separate papers, but the basic kernel is quite simple, involving the
following keywords (all of which end with an integer axis index,
indicated below by $<i>$):

\begin{description}
\item[CRPIX<i>]\mbox{}\\
hold the pixel coordinates at a reference point
\item[CRVAL<i>]\mbox{}\\
hold the corresponding WCS coordinates at the reference point
\item[CTYPE<i>]\mbox{}\\
name the quantity represented by the WCS axes, together with the
projection algorithm used to convert the scaled and rotated pixel coordinates
to WCS coordinates.
\item[CD<i>\_<j>]\mbox{}\\
a set of keywords which specify the elements of a matrix. This matrix scales
pixel offsets from the reference point into the offsets required as input
by the projection algorithm specified by the CTYPE keywords. This matrix
specifies the scale and rotation of the image. If there is no rotation
the off-diagonal elements of the matrix (\emph{e.g.} CD1\_2 and
CD2\_1) can be omitted.
\end{description}

As an example consider the common case of a simple 2D image of the sky in
which north is parallel to the second pixel axis and east parallel to the
(negative) first pixel axis. The image scale is 1.2 arc-seconds per pixel
on both axes, and the image is presumed to have been obtained with a
tangent plane projection. Furthermore, it is known that pixel coordinates
(100.5,98.4) correspond to an RA of 11:00:10 and a Dec. of  -23:26:02.
A suitable set of FITS-WCS header cards could be:

\begin{small}
\begin{terminalv}
CTYPE1  = 'RA---TAN'       / Axis 1 represents RA with a tan projection
CTYPE2  = 'DEC--TAN'       / Axis 2 represents Dec with a tan projection
CRPIX1  = 100.5            / Pixel coordinates of reference point
CRPIX2  = 98.4             / Pixel coordinates of reference point
CRVAL1  = 165.04167        / Degrees equivalent of "11:00:10" hours
CRVAL2  = -23.433889       / Decimal equivalent of "-23:26:02" degrees
CD1_1   = -0.0003333333    / Decimal degrees equivalent of -1.2 arc-seconds
CD2_2   = 0.0003333333     / Decimal degrees equivalent of 1.2 arc-seconds
\end{terminalv}
\end{small}

Notes:
\begin{itemize}
\item a FITS header card begins with the keyword name starting at column 1,
has an equals sign in column 9, and the keyword value in columns 11 to 80.
\item string values must be enclosed in single quotes.
\item celestial longitude and latitude must both be specified in decimal degrees.
\item the CD1\_1 value is negative to indicate that RA increases as the
first pixel axis decreases.
\item the (RA,Dec) coordinates will be taken as ICRS coordinates. For FK5
you should add:

\begin{small}
\begin{terminalv}
RADESYS = 'FK5'
EQUINOX = 2005.6
\end{terminalv}
\end{small}

The EQUINOX value defaults to J2000.0 if omitted. FK4 can also be used in
place of FK5, in which case EQUINOX defaults to B1950.0.

\end{itemize}

Once you have created these FITS-WCS header card strings, you should
store them in a \htmlref{FitsChan}{FitsChan} and then read the corresponding FrameSet from the
FitsChan. How to do this is described in \secref{ss:howtoreadwcs}.

Having created the WCS calibration, you may want to store it in a data
file. How to do this is described in \secref{ss:howtowritewcs}).\footnote{If
you are writing the WCS calibration to a FITS file you obviously
have the choice of storing the FITS-WCS cards directly.}

If the required WCS calibration cannot be described as a set of FITS-WCS
headers, then a different approach is necessary. In this case, you should
first create a \htmlref{Frame}{Frame} describing pixel coordinates, and store this Frame
in a new FrameSet. You should then create a new Frame describing the
world coordinate system. This Frame may be a specific subclass of Frame such
as a \htmlref{SkyFrame}{SkyFrame} for celestial coordinates, a \htmlref{SpecFrame}{SpecFrame} for spectral
coordinates, a Timeframe for time coordinates, or a \htmlref{CmpFrame}{CmpFrame} for a combination
of different coordinates.
You also need to create a suitable \htmlref{Mapping}{Mapping} which transforms pixel
coordinates into world coordinates. AST provides many different types of
Mappings, all of which can be combined together in arbitrary fashions to
create more complicated Mappings. The WCS Frame should then be added into
the FrameSet, using the Mapping to connect the WCS Frame with the pixel
Frame.

\subsection{\label{ss:howtomodifywcs}\ldots Modify a WCS Calibration}

The usual reason for wishing to modify the WCS calibration associated
with a dataset is that the data have been geometrically transformed in
some way (here, we will assume a 2-dimensional image dataset). This
causes the image features (stars, galaxies, \emph{etc.}) to move with
respect to the grid of pixels which they occupy, so that any
coordinate systems previously associated with the image become
invalid.

To correct for this, it is necessary to set up a \htmlref{Mapping}{Mapping} which
expresses the positions of image features in the new data grid in
terms of their positions in the old grid. In both cases, the grid
coordinates we use will have the first pixel centred at (1,1) with
each pixel being a unit square.

AST allows you to correct for any type of geometrical transformation
in this way, so long as a suitable Mapping to describe it can be
constructed. For purposes of illustration, we will assume here that
the new image coordinates ``xnew'' and ``ynew'' can be expressed in
terms of the old coordinates ``xold'' and ``yold'' as follows:

\begin{small}
\begin{terminalv}
double xnew, xold, ynew, yold;
double m[ 4 ], z[ 2 ];

...

xnew = xold * m[ 0 ] + yold * m[ 1 ] + z[ 0 ];
ynew = xold * m[ 2 ] + yold * m[ 3 ] + z[ 1 ];
\end{terminalv}
\end{small}

where ``m'' is a 2$\times$2 transformation matrix and ``z'' represents
a shift of origin. This is therefore a general linear coordinate
transformation which can represent displacement, rotation,
magnification and shear.

In AST, it can be represented by concatenating two Mappings. The first
is a \htmlref{MatrixMap}{MatrixMap}, which implements the matrix multiplication. The second
is a \htmlref{WinMap}{WinMap}, which linearly transforms one coordinate window on to
another, but will be used here simply to implement the shift of
origin (alternatively, a \htmlref{ShiftMap}{ShiftMap} could have been used in place of a
WinMap). These Mappings may be constructed and concatenated as follows:

\begin{small}
\begin{terminalv}
AstCmpMap *newmap;
AstMatrixMap *matrixmap;
AstWinMap *winmap;

...

/* The MatrixMap may be constructed directly from the matrix "m". */
matrixmap = astMatrixMap( 2, 2, 0, m, "" );

/* For the WinMap, we set up the coordinates of the corners of a unit
   square (window) and then the same square shifted by the required
   amount. */
{
   double ina[] = { 0.0, 0.0 };
   double inb[] = { 1.0, 1.0 };
   double outa[] = {       z[ 0 ],       z[ 1 ] };
   double outb[] = { 1.0 + z[ 0 ], 1.0 + z[ 1 ] };

/* The WinMap will then implement this shift. */
   winmap = astWinMap( 2, ina, inb, outa, outb, "" );
}

/* Join the two Mappings together, so that they are applied one after
   the other. */
newmap = astCmpMap( matrixmap, winmap, 1, "" );
\end{terminalv}
\end{small}

You might, of course, create any other form of Mapping depending on
the type of geometrical transformation involved. For an overview of
the Mappings provided by AST, see \secref{ss:mappingselection}, and
for a description of the capabilities of each class of Mapping, see
its entry in \appref{ss:classdescriptions}. For an overview of how
individual Mappings may be combined, see \secref{ss:cmpmapoverview}
(\secref{ss:cmpmaps} gives more details).

Assuming you have obtained a WCS calibration for your original image
in the form of a pointer to a \htmlref{FrameSet}{FrameSet}, ``wcsinfo1''
(\secref{ss:howtoreadwcs}), the Mapping created above may be used to
produce a calibration for the new image as follows:

\begin{small}
\begin{terminalv}
AstFrameSet *wcsinfo1, *wcsinfo2;

...

/* If necessary, make a copy of the WCS calibration, since we are
   about to alter it. */
wcsinfo2 = astCopy( wcsinfo1 );

/* Re-map the base Frame so that it refers to the new data grid
   instead of the old one. */
astRemapFrame( wcsinfo2, AST__BASE, newmap );
\end{terminalv}
\end{small}

This will produce a pointer, ``wcsinfo2'', to a new FrameSet in which
all the coordinate systems associated with your original image are
modified so that they are correctly registered with the new image
instead.

For more information about re-mapping the Frames within a FrameSet,
see \secref{ss:remapframe}. Also see \secref{ss:wcsprocessingexample}
for a similar example to the above, applicable to the case of reducing
the size of an image by binning.

\subsection{\label{ss:howtowritewcs}\ldots Write a Modified WCS Calibration to a Dataset}

If you have modified the WCS calibration associated with a dataset,
such as in the example above (\secref{ss:howtomodifywcs}), then you
will need to write the modified version out along with any new data.

In the same way as when reading a WCS calibration
(\secref{ss:howtoreadwcs}), how you do this will depend on your data
system, but we will assume that you wish to generate a set of FITS
header cards that can be stored with the data. You should usually make
preparations for doing this when you first read the WCS calibration
from your input dataset by modifying the example given in
\secref{ss:howtoreadwcs} as follows:

\begin{small}
\begin{terminalv}
AstFitsChan *fitschan1;
AstFrameSet *wcsinfo1;
const char *encode;

...

/* Create an input FitsChan and fill it with FITS header cards. Note,
   if you have all the header cards in a single string, use astPutCards in
   place of astPutFits. */
fitschan1 = astFitsChan( NULL, NULL, "" );
for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan1, cards[ icard ], 0 );

/* Note which encoding has been used for the WCS information. */
encode = astGetC( fitschan1, "Encoding" );

/* Rewind the input FitsChan and read the WCS information from it. */
astClear( fitschan1, "Card" );
wcsinfo1 = astRead( fitschan1 );
\end{terminalv}
\end{small}

Note how we have added an enquiry to determine how the WCS information
is encoded in the input FITS cards, storing a pointer to the resulting
string in the ``encode'' variable. This must be done \textbf{before}
actually reading the WCS calibration.

\emph{(\textbf{N.B.}\ If you will be making extensive use of astGetC in
your program, then you should allocate a buffer and make a copy of
this string, because the pointer returned by astGetC will only remain
valid for 50 invocations of the function, and you will need to use the
\htmlref{Encoding}{Encoding} value again later on.)}

Once you have produced a modified WCS calibration for the output
dataset (\emph{e.g.}\ \secref{ss:howtomodifywcs}), in the form of a
\htmlref{FrameSet}{FrameSet} identified by the pointer ``wcsinfo2'', you can produce a new
\htmlref{FitsChan}{FitsChan} containing the output FITS header cards as follows:

\small
\begin{terminalv}
AstFitsChan *fitschan2;
AstFrameSet *wcsinfo2;

...

/* Make a copy of the input FitsChan, AFTER the WCS information has
   been read from it. This will propagate all the input FITS header
   cards, apart from those describing the input WCS calibration. */
fitschan2 = astCopy( fitschan1 );

/* If necessary, make modifications to the cards in "fitschan2"
   (e.g. you might need to change NAXIS1, NAXIS2, etc., to account for
   a change in image size). You probably only need to do this if your
   data system does not provide these facilities itself. */
<details not shown - see below>

/* Alternatively, if your data system handles the propagation of FITS
   header cards to the output dataset for you, then simply create an
   empty FitsChan to contain the output WCS information alone.
fitschan2 = astFitsChan( NULL, NULL, "" );
*/

/* Rewind the new FitsChan (if necessary) and attempt to write the
   output WCS information to it using the same encoding method as the
   input dataset. */
astSet( fitschan2, "Card=1, Encoding=%s", encode );
if ( !astWrite( fitschan2, wcsinfo2 ) ) {

/* If this didn't work (the WCS FrameSet has become too complex), then
   use the native AST encoding instead. */
   astSet( fitschan2, "Encoding=NATIVE" );
   (void) astWrite( fitschan2, wcsinfo2 );
}
\end{terminalv}
\normalsize

For details of how to modify the contents of the output FitsChan in
other ways, such as by adding, over-writing or deleting header cards,
see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and
\secref{ss:findingandchangingfits}.

Once you have assembled the output FITS cards, you may retrieve them
from the FitsChan that contains them as follows:

\small
\begin{terminalv}
#include <stdio.h>
char card[ 81 ];

...

astClear( fitschan2, "Card" );
while ( astFindFits( fitschan2, "%f", card, 1 ) ) (void) printf( "%s\n", card );
\end{terminalv}
\normalsize

Here, we have simply written each card to the standard output stream,
but you would obviously replace this with a function invocation to
store the cards in your output dataset.

For data systems that do not use FITS header cards, a different
approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan}
(\secref{ss:channels}) rather than a FitsChan.  In the case of the
Starlink NDF data format, for example, all of the above may be
replaced by a single call to the function
\xref{ndfPtwcs}{sun33}{ndfPtwcs}---see \xref{SUN/33}{sun33}{}. The
whole process can probably be encapsulated in a similar way for most
data systems, whether they use FITS header cards or not.

For an overview of how to propagate WCS information through data
processing steps, see \secref{ss:propagatingwcsinformation}.  For more
information about writing WCS information to FitsChans, see
\secref{ss:writingnativefits} and \secref{ss:writingforeignfits}.  For
information about the options for encoding WCS information in FITS
header cards, see \secref{ss:nativeencoding},
\secref{ss:foreignencodings}, and the description of the Encoding
attribute in \appref{ss:attributedescriptions}.  For a complete
understanding of FitsChans and their use with FITS header cards, you
should read \secref{ss:nativefits} and \secref{ss:foreignfits}.

\subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid}

   A common requirement when displaying image data is to plot an
   associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid})
   over the displayed image.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/overgrid_bw}
   \caption[An example of a displayed image with a coordinate grid
   plotted over it.]{An example of a displayed image with a coordinate grid
   plotted over it.}
   \label{fig:overgrid}
   \end{center}
   \end{figure}

The use of AST in such circumstances is independent of the underlying
graphics system, so starting up the graphics system, setting up a
coordinate system, displaying the image, and closing down afterwards
can all be done using the graphics functions you would normally use.

However, displaying an image at a precise location can be a little
fiddly with some graphics systems, and obviously the grid drawn by AST
will not be accurately registered with the image unless this is done
correctly. In the following template, we therefore illustrate both
steps, basing the image display on the C interface to the PGPLOT
graphics package.\footnote{An interface is provided with AST that
allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics,
although interfaces to other graphics systems may also be written.}
Plotting a coordinate grid with AST then becomes a relatively minor
part of what is almost a complete graphics program.

Once again, we assume that a pointer, ``wcsinfo'', to a suitable
\htmlref{FrameSet}{FrameSet} associated with the image has already been obtained
(\secref{ss:howtoreadwcs}).

\small
\begin{terminalv}
#include "cpgplot.h"
AstPlot *plot;
const float *data;
float hi, lo, scale, x1, x2, xleft, xright, xscale;
float y1, y2, ybottom, yscale, ytop;
int nx, ny;

...

/* Access the image data, which we assume has dimension sizes "nx" and
   "ny", and will be accessed via the "data" pointer.  Also derive
   limits for scaling it, which we assign to the variables "hi" and
   "lo". */
<this stage depends on your data system, so is not shown>

/* Open PGPLOT using the device given by environment variable
   PGPLOT_DEV and check for success. */
if( cpgbeg( 0, " ", 1, 1 ) == 1 ) {

/* Clear the screen and ensure equal scales on both axes. */
   cpgpage();
   cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f );

/* Obtain the extent of the plotting area (not strictly necessary for
   PGPLOT, but possibly for other graphics systems). From this, derive
   the display scale in graphics units per pixel so that the image
   will fit within the display area. */
   cpgqwin( &x1, &x2, &y1, &y2 );
   xscale = ( x2 - x1 ) / nx;
   yscale = ( y2 - y1 ) / ny;
   scale = ( xscale < yscale ) ? xscale : yscale;

/* Calculate the extent of the area in graphics units that the image
   will occupy, so as to centre it within the display area. */
   xleft   = 0.5f * ( x1 + x2 - nx * scale );
   xright  = 0.5f * ( x1 + x2 + nx * scale );
   ybottom = 0.5f * ( y1 + y2 - ny * scale );
   ytop    = 0.5f * ( y1 + y2 + ny * scale );

/* Set up a PGPLOT coordinate transformation matrix and display the
   image data as a grey scale map (these details are specific to
   PGPLOT). */
   {
      float tr[] = { xleft - 0.5f * scale, scale, 0.0f,
                     ybottom - 0.5f * scale, 0.0f, scale };
      cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr );
   }

/* BEGINNING OF AST BIT */
/* ==================== */
/* Store the locations of the bottom left and top right corners of the
   region used to display the image, in graphics coordinates. */
   {
      float gbox[] = { xleft, ybottom, xright, ytop };

/* Similarly, store the locations of the image's bottom left and top
   right corners, in pixel coordinates -- with the first pixel centred
   at (1,1). */
      double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 };

/* Create a Plot, based on the FrameSet associated with the
   image. This attaches the Plot to the graphics surface so that it
   matches the displayed image. Specify that a complete set of grid
   lines should be drawn (rather than just coordinate axes). */
      plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" );
   }

/* Optionally, we can now set other Plot attributes to control the
   appearance of the grid. The values assigned here use the
   colour/font indices defined by the underlying graphics system. */
   astSet( plot, "Colour(grid)=2, Font(textlab)=3" );

/* Use the Plot to draw the coordinate grid. */
   astGrid( plot );

   <maybe some more AST graphics here>

/* Annul the Plot when finished (or use the astBegin/astEnd technique
   shown earlier). */
   plot = astAnnul( plot );

/* END OF AST BIT */
/* ============== */

/* Close down the graphics system. */
   cpgend();
}
\end{terminalv}
\normalsize

Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a
displayed image, you may also use it to generate further graphical
output of your own, specified in the image's world coordinate system
(such as markers to represent astronomical objects, annotation,
\emph{etc.}). There is also a range of Plot attributes which gives
control over most aspects of the output's appearance.  For details of
the facilities available, see \secref{ss:plots} and the description of
the Plot class in \appref{ss:classdescriptions}.

For details of how to build a graphics program which uses PGPLOT, see
\secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in
\appref{ss:commanddescriptions}.

\subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid}

Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid
(\secref{ss:howtoplotgrid}), it is a simple matter to change things so
that the grid represents a different celestial coordinate system. For
example, after creating the Plot with \htmlref{astPlot}{astPlot}, you could use:

\small
\begin{terminalv}
astSet( plot, "System=Galactic" );
\end{terminalv}
\normalsize
or:
\small
\begin{terminalv}
astSet( plot, "System=FK5, Equinox=J2010" );
\end{terminalv}
\normalsize

and any axes and/or grid drawn subsequently would represent the new
celestial coordinate system you specified.  Note, however, that this
will only work if the original grid represented celestial coordinates
of some kind (see \secref{ss:howtotestforcelestial} for how to
determine if this is the case\footnote{Note that the methods applied
to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not,
you will get an error message.

For more information about the celestial coordinate systems available,
see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in
\appref{ss:attributedescriptions}.

\subsection{\ldots Give a User Control Over the Appearance of a Plot}

The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the
graphical output it produces (\secref{ss:howtoplotgrid} and
\secref{ss:howtoswitchgrid}) can easily be extended to allow the user
of a program complete control over such matters.

For instance, if the file ``plot.config'' contains a series of
plotting options in the form of Plot attribute assignments (see below
for an example), then we could create a Plot and implement these
assignments before producing the graphical output as follows:

\small
\begin{terminalv}
#include <stdio.h>
#define MAXCHARS 120
FILE *stream;
char line[ MAXCHARS + 2 ];
int base;

...

/* Create a Plot and define the default appearance of the graphical
   output it will produce. */
plot = astPlot( wcsinfo, gbox, pbox,
                "Grid=1, Colour(grid)=2, Font(textlab)=3" );

/* Obtain the value of any Plot attributes we want to preserve. */
base = astGetI( plot, "Base" );

/* Open the plot configuration file, if it exists. Read each line of
   text and use it to set new Plot attribute values. Close the file
   when done. */
if ( stream = fopen( "plot.config", "r" ) ) {
   while ( fgets( line, MAXCHARS + 2, stream ) ) astSet( plot, "%s", line );
   close( stream );
}

/* Restore any attribute values we are preserving. */
astSetI( plot, "Base", base );

/* Produce the graphical output (e.g.). */
astGrid( plot );
\end{terminalv}
\normalsize

Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved
so that the user cannot change it. This is because graphical output
will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe
the plotting surface to which we attached the Plot when we created it.

The arrangement shown above allows the contents of the ``plot.config''
file to control most aspects of the graphical output produced
(including the coordinate system used; the colour, line style,
thickness and font used for each component; the positioning of axes
and tick marks; the precision, format and positioning of labels;
\emph{etc.}) \emph{via} assignments of the form:

\small
\begin{terminalv}
System=Galactic, Equinox = 2001
Border = 1, Colour( border ) = 1
Colour( grid ) = 2
DrawAxes = 1
Colour( axes ) = 3
Digits = 8
Labelling = Interior
\end{terminalv}
\normalsize

For a more sophisticated interface, you could obviously perform
pre-processing on this input---for example, to translate words like
``red'', ``green'' and ``blue'' into colour indices, to permit
comments and blank lines, \emph{etc.}

For a full list of the attributes that may be used to control the
appearance of graphical output, see the description of the Plot class
in \appref{ss:classdescriptions}. For a complete description of each
individual attribute (\emph{e.g.}\ those above), see the attribute's
entry in \appref{ss:attributedescriptions}.

\cleardoublepage
\section{\label{ss:primer}An AST Object Primer}

The AST library deals throughout with entities called Objects and a
basic understanding of how to handle these is needed before you can
use the library effectively.  If you are already familiar with an
object-oriented language, such as C$++$, few of the concepts should
seem new to you.  Be aware, however, that AST is designed to be used
\emph{via} fairly conventional C and Fortran interfaces, so some
things have to be done a little differently.

If you are not already familiar with object-oriented programming, then
don't worry---we will not emphasise this aspect more than is necessary
and will not assume any background knowledge.  Instead, this section
concentrates on presenting all the fundamental information you will
need, explaining how AST Objects behave and how to manipulate them
from conventional C programs.

If you like to read documents from cover to cover, then you can
consider this section as an introduction to the programming techniques
used in the rest of the document. Otherwise, you may prefer to skim
through it on a first reading and return to it later as reference
material.

\subsection{AST Objects}

An AST \htmlref{Object}{Object} is an entity which is used to store information and
Objects come in various kinds, called \emph{classes}, according to the
sort of information they hold. Throughout this section, we will make
use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to
illustrate many of the basic concepts.

A ZoomMap is an Object that contains a recipe for converting
coordinates between two hypothetical coordinate systems.  It does this
by multiplying all the coordinate values by a constant called the
\emph{\htmlref{Zoom}{Zoom} factor}.  A ZoomMap is a very simple Object which exists
mainly for use in examples. It allows us to illustrate the ways in
which Objects are manipulated and to introduce the concept of a
\htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental
to the way the AST library works.

\subsection{\label{ss:objectcreation}Object Creation and Pointers}

Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very
simply as follows:

\small
\begin{terminalv}
#include "ast.h"
AstZoomMap *zoommap;

...

zoommap = astZoomMap( 2, 5.0, "" )
\end{terminalv}
\normalsize

The first step is to include the header file ``ast.h'' which declares
the interface to the AST library.  We then declare a pointer of type
AstZoomMap$*$ to receive the result and invoke the function \htmlref{astZoomMap}{astZoomMap}
to create the ZoomMap. The pattern is the same for all other classes
of AST \htmlref{Object}{Object}---you simply prefix ``ast'' to the class name to obtain
the function that creates the Object and prefix ``Ast'' to obtain the
type of the returned pointer.

These functions are called \emph{constructor functions}, or simply
\emph{constructors} (you can find an individual description of all AST
functions in \appref{ss:functiondescriptions}) and the arguments
passed to the constructor are used to initialise the new Object. In
this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we
are going to work in a 2-dimensional
space) and 5.0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a C
double value. We will return to the final argument, an empty string,
shortly (\secref{ss:attributeinitialisation}).

The value returned by the constructor is termed an \emph{Object pointer}
or, in this case, a \emph{ZoomMap pointer} and is used to refer to the
Object.  You perform all subsequent operations on the Object by
passing this pointer to other AST functions.

\subsection{\label{ss:objecthierarchy}The Object Hierarchy}

Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it
relates to other kinds of \htmlref{Object}{Object} before investigating what we can do
with it.

We have so far indicated that a ZoomMap is a kind of Object and have
also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements
can be represented very simply using the following hierarchy:

\small
\begin{terminalv}
Object
   Mapping
      ZoomMap
\end{terminalv}
\normalsize

which is a way of stating that a ZoomMap is a special class of
Mapping, while a Mapping, in turn, is a special class of Object.  This
is exactly like saying that an Oak is a special form of Tree, while a
Tree, in turn, is a special form of Plant. This may seem almost
trivial, but before you turn to read something less dull, be assured
that it is a very important idea to keep in mind in what follows.

If we look at some of the other Objects used by the AST library, we
can see how these are all related in a similar way (don't worry about
what they do at this stage):
\label{ss:mappinghierarchy}

\small
\begin{terminalv}
Object
   Mapping
      Frame
         FrameSet
            Plot
      UnitMap
      ZoomMap
   Channel
      FitsChan
      XmlChan
\end{terminalv}
\normalsize

Notice that there are several different types of Mapping available
(\emph{i.e.}\ there are classes of Object indented beneath the
``Mapping'' heading) and, in addition, other types of Object which are
not Mappings---Channels for instance (which are at the same
hierarchical level as Mappings).

The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we
will not discuss in detail until \secref{ss:plots}). As you can see, a
Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and,
like everything else, ultimately an Object.

What this means is that you can use a Plot not only for its own
specialised behaviour, but also whenever any of these other
less-specialised classes of Object is called for. The general rule is
that an Object of a particular class may substitute for any of the
classes appearing above it in this hierarchy. The Object is then said
to \emph{inherit} the behaviour of these higher classes. We can
therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object
is called for.

Sometimes, this can lead to some spectacular short-cuts by avoiding
the need to break large Objects down in order to access their
components. With some practice and a little lateral thinking you
should soon be able to spot opportunities for this.

You can find the full \emph{class hierarchy}, as this is called, for
the AST library in \appref{ss:classhierarchy} and you may need to
refer to it occasionally until you are familiar with the classes you
need to use.

\subsection{\label{ss:displayingobjects}Displaying Objects}

Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier
(\secref{ss:objectcreation}) and examine what it's made of.
There is a function for doing this, called \htmlref{astShow}{astShow}, which is provided
mainly for looking at Objects while you are debugging programs.

If you consult the description of astShow in
\appref{ss:functiondescriptions}, you will find that it takes a
pointer to an \htmlref{Object}{Object} (of type AstObject$*$) as its argument. Although
we have only a ZoomMap pointer available, this is not a problem. If
you refer to the brief class hierarchy described above
(\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an
Object, albeit a specialised one, so it inherits the properties of all
Objects and can be substituted wherever an Object is required.  We can
therefore pass our ZoomMap pointer directly to astShow, as follows:

\small
\begin{terminalv}
astShow( zoommap );
\end{terminalv}
\normalsize

The output from this will appear on the standard output stream and
should look like the following:

\small
\begin{terminalv}
Begin ZoomMap
   Nin = 2
IsA Mapping
   Zoom = 5
End ZoomMap
\end{terminalv}
\normalsize

Here, the ``Begin'' and ``End'' lines mark the beginning and end of
the ZoomMap, while the values 2 and 5 are simply the values we
supplied to initialise it (\secref{ss:objectcreation}). These have
been given simple names to make them easy to refer to.

The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line
between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a
property shared by all Mappings, so the ZoomMap has inherited this
from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however,
is specific to a ZoomMap and isn't shared by other kinds of Mappings.

\subsection{\label{ss:gettingattributes}Getting Attribute Values}

We saw above (\secref{ss:displayingobjects}) how to display the
internal values of an \htmlref{Object}{Object}, but what about accessing these values
from a program?  Not all internal Object values are accessible in this
way, but many are. Those that are, are called \emph{attributes}. A
description of all the attributes used by the AST library can be found
in \appref{ss:attributedescriptions}.

Attributes come in several data types (character string, integer,
boolean and floating point) and there is a standard way of obtaining
their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin}
attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as
follows:

\small
\begin{terminalv}
int nin;

...

nin = astGetI( zoommap, "Nin" );
\end{terminalv}
\normalsize

Here, the function astGetI is used to extract the attribute value by
giving it the ZoomMap pointer and the attribute name (attribute names
are not case sensitive, but we have used consistent capitalisation in
this document in order to identify them). Remember to use the
``ast.h'' header file to include the function prototype.

If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably
have used astGetD instead, this being a double version of the same
function, for example:

\small
\begin{terminalv}
double zoom;

...

zoom = astGetD( zoommap, "Zoom" );
\end{terminalv}
\normalsize

However, we could equally well have read the Nin value as double, or
the Zoom value as an integer, or whatever we wanted.

The data type you want returned is specified simply by replacing the
final character of the astGetX function name with C~(character
string), D~(double), F~(float), I~(int) or L~(long). If possible, the
value is converted to the type you want. If not, an error message will
result. Note that all floating point values are stored internally as
double, and all integer values as int. Boolean values are also stored
as integers, but only take the values 1 and 0 (for true/false).

\subsection{\label{ss:settingattributes}Setting Attribute Values}

Some attribute values are read-only and cannot be altered after an
\htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing
the number of coordinates) is like this. It is defined when the
ZoomMap is created, but cannot then be altered.

Other attributes, however, can be modified whenever you want. A
ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this
could be done simply as follows:

\small
\begin{terminalv}
astSetD( zoommap, "Zoom", 99.6 );
\end{terminalv}
\normalsize

which sets the value to 99.6. As when getting an attribute value
(\secref{ss:gettingattributes}), you have a choice of which data type
you will use to supply the new value. For instance, you could use an
integer value, as in:

\small
\begin{terminalv}
astSetI( zoommap, "Zoom", 99 );
\end{terminalv}
\normalsize

and the necessary data conversion would occur.  You specify the data
type you want to supply simply by replacing the final character of the
astSetX function name with C~(character string), D~(double),
F~(float), I~(int) or L~(long). Setting a boolean attribute to any
non-zero integer causes it to take the value 1.

An alternative way of setting attribute values for Objects is to use
the \htmlref{astSet}{astSet} function (\emph{i.e.}\ with no final character specifying a
data type). In this case, you supply the attribute values in a
character string. The big advantage of this method is that you can
assign values to several attributes at once, separating them with
commas. This also reads more naturally in programs. For example:

\small
\begin{terminalv}
astSet( zoommap, "Zoom=99.6, Report=1" );
\end{terminalv}
\normalsize

would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute
(about which more shortly---\secref{ss:transforming}). You don't really
have to worry about data types with this method, as any character
representation will do. Note, when using astSet, a
literal comma may be included in an attribute value by enclosed the value in
quotation marks:
\small
\begin{terminalv}
      astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' );
\end{terminalv}
\normalsize

Another attractive feature of astSet is that you can build the
character string which contains the attribute settings in the same way
as when using the C run time library ``printf'' function. This is most
useful when the values you want to set are held in other
variables. For example:

\small
\begin{terminalv}
double zoom = 99.6;
int report = 1;

...

astSet( zoommap, "Zoom=%g, Report=%d", zoom, report );
\end{terminalv}
\normalsize

would replace the ``\%'' conversion specifications by the values
supplied as additional arguments. Any number of additional arguments
may be supplied and the formatting rules are exactly the same as for
the C ``printf'' family of functions. This is a very flexible
technique, but does contain one pitfall:

\begin{quote}
\textbf{Pitfall.} The default precision used by ``printf'' (and astSet)
for floating point values is only 6 decimal digits, corresponding
approximately to float on most machines, whereas the AST library
stores such values internally as doubles. You should be careful to
specify a larger precision (such as DBL\_DIG, as defined in
$<$float.h$>$) when necessary. For example:

\small
\begin{terminalv}
#include <float.h>

...

astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value );
\end{terminalv}
\normalsize
\end{quote}

Substituted strings may contain commas and this is a useful way of
assigning such strings as attribute values without the comma being
interpreted as an assignment separator, for example:

\small
\begin{terminalv}
astSet( object, "Attribute=%s", "A string, containing a comma" );
\end{terminalv}
\normalsize

This is equivalent to using astSetC and one of these two methods
should always be used when assigning string attribute values which
might potentially contain a comma (\emph{e.g.}\ strings obtained from
an external source). However, you should not attempt to use astSet to
substitute strings that contain newline characters, since these are
used internally as separators between adjacent attribute assignments.
\label{ss:attributeinitialisation}

Finally, a very convenient way of setting attribute values is to do so
at the same time as you create an Object. Every Object constructor
function has a final character string argument which allows you to do
this. Although you can simply supply an empty string, it is an ideal
opportunity to initialise the Object to have just the attributes you
want. For example, we might have created our original ZoomMap with:

\small
\begin{terminalv}
zoommap = astZoomMap( 2, 5.0, "Report=1" );
\end{terminalv}
\normalsize

and it would then start life with its Report attribute set to 1.
The ``printf''-style substitution described above may also be used
here.

\subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes}

You can use the astGetX family of functions
(\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute
at any time, regardless of whether a value has previously been set for
it. If no value has been set, the AST library will generate a suitable
default value.

Often, the default value of an attribute will not simply be trivial
(zero or blank) but may involve considerable processing to
calculate. Wherever possible, defaults are designed to be real-life,
sensible values that convey information about the state of the
Object. In particular, they may often be based on the values of other
attributes, so their values may change in response to changes in these
other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a
little too simple to show this behaviour, but we will meet it later
on.

An attribute that returns a default value in this way is said to be
\emph{un-set}. Conversely, once an explicit value has been assigned to
an attribute, it becomes \emph{set} and will always return precisely
that value, never a default.

The distinction between set and un-set attributes is important and
affects the behaviour of several key routines in the AST library. You
can test if an attribute is set using the function \htmlref{astTest}{astTest}, which
returns a boolean (integer) result, as in:

\small
\begin{terminalv}
if ( astTest( zoommap, "Report" ) ) {
   <the Report attribute is set>
}
\end{terminalv}
\normalsize


Once an attribute is set, you can return it to its un-set state using
\htmlref{astClear}{astClear}. The effect is as if it had never been set in the first
place. For example:

\small
\begin{terminalv}
astClear( zoommap, "Report" );
\end{terminalv}
\normalsize

would ensure that the default value of the \htmlref{Report}{Report} attribute is used
subsequently.

%\subsection{TBW--Handling Character Attributes}

\subsection{\label{ss:transforming}Transforming Coordinates}

We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show
what it is really for. Here, we will also encounter a routine that is
a little more fussy about the type of pointer it will accept.

The purpose of a ZoomMap is to multiply coordinates by a constant zoom
factor. To witness this in action, we will first set the \htmlref{Report}{Report}
attribute for our ZoomMap to a non-zero value:

\small
\begin{terminalv}
astSet( zoommap, "Report=1" );
\end{terminalv}
\normalsize

This boolean (integer) attribute, which is present in all Mappings
(and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all
coordinate values that the Mapping converts. It is not a good idea to
leave this feature turned on in a finished program, but it can save a
lot of work during debugging.

Our next step is to set up some coordinates for the ZoomMap to work
on, using two arrays ``xin'' and ``yin'', and two arrays to receive
the transformed coordinates, ``xout'' and ``yout''.  Note that these
are arrays of double, as are all coordinate data processed by the AST
library:

\small
\begin{terminalv}
double xin[ 10 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 };
double yin[ 10 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0 };
double xout[ 10 ];
double yout[ 10 ];
\end{terminalv}
\normalsize

We will now use the function \htmlref{astTran2}{astTran2} to transform the input
coordinates. This is the most commonly-used (2-dimensional) coordinate
transformation function. If you look at its description in
\appref{ss:functiondescriptions}, you will see that it requires a
pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer,
as we could with the functions discussed previously. If we passed it a
pointer to an inappropriate Object, an error message would result.

Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we
can use it with astTran2 to transform our coordinates, as follows:

\small
\begin{terminalv}
astTran2( zoommap, 10, xin, yin, 1, xout, yout );
\end{terminalv}
\normalsize

Here, 10 is the number of points we want to transform and the fifth
argument value of 1 indicates that we want to transform in the
\emph{forward} direction (from input to output).

Because our ZoomMap's Report attribute is set to 1, this will cause
the effects of the ZoomMap on the coordinates to be displayed on the
standard output stream:

\small
\begin{terminalv}
(0, 0) --> (0, 0)
(1, 2) --> (5, 10)
(2, 4) --> (10, 20)
(3, 6) --> (15, 30)
(4, 8) --> (20, 40)
(5, 10) --> (25, 50)
(6, 12) --> (30, 60)
(7, 14) --> (35, 70)
(8, 16) --> (40, 80)
(9, 18) --> (45, 90)
\end{terminalv}
\normalsize

This shows the coordinate values of each point both before and after
the ZoomMap is applied. You can see that each coordinate value has
been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute
value. The transformed coordinates are now stored in the ``xout'' and
``yout'' arrays.

If we wanted to transform in the opposite direction, we need simply
change the fifth argument of astTran2 from 1 to 0. We can also feed
the output coordinates from the above back into the function:

\small
\begin{terminalv}
astTran2( zoommap, 10, xout, yout, 0, xin, yin );
\end{terminalv}
\normalsize

The output would then look like:

\small
\begin{terminalv}
(0, 0) --> (0, 0)
(5, 10) --> (1, 2)
(10, 20) --> (2, 4)
(15, 30) --> (3, 6)
(20, 40) --> (4, 8)
(25, 50) --> (5, 10)
(30, 60) --> (6, 12)
(35, 70) --> (7, 14)
(40, 80) --> (8, 16)
(45, 90) --> (9, 18)
\end{terminalv}
\normalsize

This is termed the \emph{inverse} transformation (we have converted
from output to input) and you can see that the original coordinates
have been recovered by dividing by the Zoom factor.

\subsection{\label{ss:annullingpointers}Managing Object Pointers}

So far, we have looked at creating Objects and using them in various
simple ways but have not yet considered how to get rid of them again.

Every \htmlref{Object}{Object} consumes various computer resources (principally memory)
and should be disposed of when it is no longer required, so as to free
up these resources. One way of doing this (not necessarily the
best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once
you have finished with it, using \htmlref{astAnnul}{astAnnul}. For example:

\small
\begin{terminalv}
zoommap = astAnnul( zoommap );
\end{terminalv}
\normalsize

This indicates that you have finished with the pointer. Since astAnnul
always returns the null value AST\_\_NULL (as defined in ``ast.h''),
the recommended way of using it, as here, is to assign the returned
value to the pointer being annulled. This ensures that any attempt to
use the pointer again will generate an error message.

In general, this process may not delete the Object, because there may
still be other pointers associated with it. However, each Object
maintains a count of the number of pointers associated with it and
will be deleted if you annul the final pointer. Using astAnnul
consistently will therefore ensure that all Objects are disposed of at
the correct time. You can determine how many pointers are associated
with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute.

\subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End}

The use of \htmlref{astAnnul}{astAnnul} (\secref{ss:annullingpointers}) is not completely
foolproof, however. Consider the following:

\small
\begin{terminalv}
astShow( astZoomMap( 2, 5.0, "" ) );
\end{terminalv}
\normalsize

This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output
(\secref{ss:displayingobjects}). Using function invocations as
arguments to other functions in this way is very convenient because it
avoids the need for intermediate pointer variables. However, the
pointer generated by \htmlref{astZoomMap}{astZoomMap} is still active, and since we have not
stored its value, we cannot use astAnnul to annul it. The ZoomMap will
therefore stay around until the end of the program.

A simple way to avoid this problem is to enclose all use of AST
functions between invocations of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}, for example:

\small
\begin{terminalv}
astBegin;
astShow( astZoomMap( 2, 5.0, "" ) );
astEnd;
\end{terminalv}
\normalsize

When the expansion of astEnd (which is a macro) executes, every \htmlref{Object}{Object}
pointer created since the previous use of astBegin (also a macro) is
automatically annulled and any Objects left without pointers are
deleted. This provides a simple solution to managing Objects and their
pointers, and allows you to create Objects very freely without needing
to keep detailed track of each one.  Because this is so convenient, we
implicitly assume that astBegin and astEnd are used in most of the
examples given in this document.  Pointer management is not generally
shown explicitly unless it is particularly relevant to the point being
illustrated.

If necessary, astBegin and astEnd may be nested, like blocks delimited
by ``\{\ldots\}'' in C, to define a series of AST pointer
contexts. Each use of astEnd will then annul only those Object
pointers created since the matching use of astBegin.

\subsection{Exporting, Importing and Exempting AST Pointers}
The \htmlref{astExport}{astExport} function allows you to export particular pointers from
one AST context (\secref{ss:contexts}) to the next outer one, as
follows:

\small
\begin{terminalv}
astExport( zoommap );
\end{terminalv}
\normalsize

This would identify the pointer stored in ``zoommap'' as being required
after the end of the current AST context. It causes any pointers
nominated in this way to survive the next use of \htmlref{astEnd}{astEnd} (but only one
such use) unscathed, so that they are available to the next outer
context.  This facility is not needed often, but is invaluable when
the purpose of your \htmlref{astBegin}{astBegin}\ldots astEnd block is basically to
generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting
that pointer out.


The \htmlref{astImport}{astImport} routine can be used in a similar manner to import a
pointer into the current context, so that it is deleted when the current
context is closed using astEnd.

Sometimes, you may also want to exempt a pointer from all the effects
of AST contexts. You should not need to do this often, but it will
prove essential if you ever need to write a library of functions that
stores AST pointers as part of its own internal data. Without some
form of exemption, the caller of your routines could cause the
pointers you have stored to be annulled---thus corrupting your
internal data---simply by using astEnd. To avoid this, you should use
\htmlref{astExempt}{astExempt} on each pointer that you store, for example:

\small
\begin{terminalv}
astExempt( zoommap );
\end{terminalv}
\normalsize

This will prevent the pointer being affected by any subsequent use of
astEnd. Of course, it then becomes your responsibility to annul this
pointer (using \htmlref{astAnnul}{astAnnul}) when it is no longer required.


\subsection{AST Objects within Multi-threaded Applications}

When the AST library is built from source, the build process checks to
see if the POSIX threads library (``\texttt{pthreads}'') is available. If so,
appropriate \texttt{pthreads} calls are inserted into the AST source code to
ensure that AST is thread-safe, and the AST\_\_THREADSAFE macro (defined
in the ``ast.h'' header file) is set to ``\texttt{1}''. If the \texttt{pthreads}
library cannot be found when AST is built, a working version of the AST
library will still be created, but it will not be thread-safe. In this
case the AST\_\_THREADSAFE macro will be set to ``\texttt{0}'' in ast.h. The
rest of this section assumes that the thread-safe version of AST is being
used.

Note, some AST functions call externally specified functions (\emph{e.g.}
the source and sink functions used by the \htmlref{Channel}{Channel} class or the graphics
primitives functions used by the \htmlref{Plot}{Plot} class). AST does not know whether
such functions are thread-safe or not. For this reason, invocations of these
functions within a multi-threaded environment are serialised using a mutex
in order to avoid two or more threads executing an external function
simultaneously.

If an application uses more than one thread, the possibility arises that
an \htmlref{Object}{Object} created by one thread may be accessed by another thread, potentially
simultaneously. If any of the threads modifies any aspect of the Object,
this could lead to serious problems within the other threads. For this
reason, some restrictions are placed on how Objects can be used in a
multi-threaded application.

\subsubsection{Locking AST Objects for Exclusive Use}
The basic restriction is that a thread can only access Objects that it
has previously locked for its own exclusive use. If a thread attempts to
access any \htmlref{Object}{Object} that it has not locked, an error is reported.

The \htmlref{astAnnul}{astAnnul} function is the one exception to this restriction. Pointers
for Objects not currently locked by the calling thread can be annulled
succesfully using astAnnul. This means that a thread that has finished
with an Object pointer can unlock the Object by passing the pointer to
\htmlref{astUnlock}{astUnlock} (so that other threads can use the Object via their own cloned
pointers), and can then annul the pointer using astAnnul. Note, however,
that an error will be reported by astAnnul if the supplied pointer has
been locked by another thread using \htmlref{astLock}{astLock}.

When an Object is created, it is initially locked by the calling thread.
Therefore a thread does not need to lock an Object explicitly if it was
created in the same thread.

If the Object pointer is then passed to another thread, the first thread
must unlock the Object using astUnlock and the second thread must then lock
it using astLock.

If a thread attempts to lock an Object that is already locked by another
thread, it can choose to report an error immediately or to wait until the
Object is available.

The \htmlref{astThread}{astThread} function can be used to determine whether an Object is
locked by the running thread, locked by another thread, or unlocked.

If two or more threads need simultaneous access to an Object, a deep copy
of the Object should be taken for each thread, using \htmlref{astCopy}{astCopy}, and then
the copies should be unlocked and passed to the othe threads, which
should then lock them. Note, if a thread modifies the Object, the
modification will have no effect on the other threads, because the Object
copies are independent of each other.

\subsubsection{AST Pointer Contexts}

Each thread maintains its own set of nested AST contexts, so when \htmlref{astEnd}{astEnd}
is called, only Objects that are locked by the current thread will
be annulled.

If an \htmlref{Object}{Object} is unlocked by a thread using \htmlref{astUnlock}{astUnlock}, it is exempted from
context handling so that subsequent invocations of astEnd will not cause it
to be annulled (this is similar to using \htmlref{astExempt}{astExempt} on the Object). When the
Object is subsequently locked by another thread using \htmlref{astLock}{astLock}, it will be
imported into the context that was active when astLock was called.



\subsection{\label{ss:copyingobjects}Copying Objects}

The AST library makes extensive use of pointers, not only for
accessing Objects directly, but also as a means of storing Objects
inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to
hold collections of other Objects). Rather than copy an Object in its
entirety, a pointer to the interior Object is simply stored in the
enclosing Object.

This means that Objects may frequently not be completely independent
of each other because, for instance, they both contain pointers to the
same sub-Object. In this situation, changing one Object (say assigning
an attribute value) may affect the other one \emph{via} the common
Object.

It is difficult to describe all cases where this may happen, so you
should always be alert to the possibility. Fortunately, there is a
simple solution. If you require two Objects to be independent, then
simply use \htmlref{astCopy}{astCopy} to make a copy of one, \emph{e.g.}:

\small
\begin{terminalv}
AstZoomMap *zoommap1, *zoommap2;

...

zoommap2 = astCopy( zoommap1 );
\end{terminalv}
\normalsize

This process will create a true copy of any Object and return a
pointer to the copy. This copy will not contain any pointers to any
component of the original Object (everything is duplicated), so you
can then modify it safely, without fear of affecting either the
original or any other Object.

%\subsection{TBW - Inheritance}

\subsection{C Pointer Types}

At this point it is necessary to confess to a small amount of
deception. So far, we have been passing \htmlref{Object}{Object} pointers to AST
functions in order to perform operations on those Objects. In fact,
however, what we were using were not true C functions at all, but
merely macros which invoke a related set of hidden functions with
essentially the same arguments. In practical terms, this makes very
little difference to how you use the functions, as we will continue to
call them.\footnote{About the only difference is that you cannot store
a pointer to an AST ``function'' in a variable and use the variable's
value to invoke that function again later.}

The reason for this deception has to do with the rules for data typing
in C. Recall that most AST functions can be used to process Objects
from a range of different classes (\secref{ss:objecthierarchy}). In C,
this means passing different pointer types to the same function and
most C compilers will not permit this (at least, not without
grumbling) because it usually indicates a programming error. In AST,
however, it is perfectly safe if done properly. Some way is therefore
needed of circumventing the normal compiler checking.

The normal way of doing this in C is with a cast. This approach
quickly becomes cumbersome, however, so we have adopted the strategy
of wrapping each function in a macro which applies the appropriate
cast for you. This means that you can pass pointers of any type to any
AST function. For example, in passing a \htmlref{ZoomMap}{ZoomMap} pointer to \htmlref{astShow}{astShow}:

\small
\begin{terminalv}
AstZoomMap *zoommap;

...

zoommap = astZoomMap( 2, 5.0, "" );
astShow( zoommap );
\end{terminalv}
\normalsize

we are exploiting this mechanism to avoid a compiler warning, because
the notional type of astShow's parameter is AstObject$*$ (not
AstZoomMap$*$).

We must still guard against programming errors, however, so every
pointer's type is checked by the enclosing macro immediately before
any AST function executes. This allows pointer mis-matches (in the
more liberal AST sense---\emph{i.e.}\ taking account of the class
hierarchy, rather than the stricter C sense) to be detected at
run-time and a suitable error message will be reported. This message
should also identify the line where the error occurs.

A similar strategy is used when pointers are returned by AST functions
(\emph{i.e.}\ as the function result). In this case the pointer is
cast to void$*$, although we retain the notional pointer type in the
function's documentation
(\emph{e.g.}\ \appref{ss:functiondescriptions}). This allows you to
assign function results to pointer variables without using an explicit
cast. For example, the \htmlref{astRead}{astRead} function returns an Object pointer, but
might be used to read (say) a ZoomMap as follows:

\small
\begin{terminalv}
AstChannel *channel;
AstZoomMap *zoommap;

...

zoommap = astRead( channel );
\end{terminalv}
\normalsize

Strictly, there is a C pointer mis-match here, but it is ignored
because the operation makes perfect sense to AST.

\textbf{There is an important exception to this, however, in that
constructor functions always return strongly-typed pointers.}  What
we mean by this is that the returned pointer is never implicitly cast
to void$*$. You must therefore match pointer types when you initially
create an Object using its constructor, such as in the following:

\small
\begin{terminalv}
AstZoomMap *zoommap;

...

zoommap = astZoomMap( 2, 5.0, "" );
\end{terminalv}
\normalsize

If the variable receiving the pointer is of a different type, an
appropriate cast should be used, as in:

\small
\begin{terminalv}
AstMapping *mapping;

...

mapping = (AstMapping *) astZoomMap( 2, 5.0, "" );
\end{terminalv}
\normalsize

This is an encouragement for you to declare your pointer types
consistently, since this is of great benefit to anyone trying to
understand your software.

Finally, we should also make one more small confession---AST pointers
are not really pointers at all.  Although they behave like pointers,
the actual ``values'' stored are not the addresses of C data
structures. This means that you cannot de-reference an AST pointer to
examine the data within (although you can use astShow
instead---\secref{ss:displayingobjects}). This is necessary so that AST
pointers can be made unique even although several of them might
reference the same Object.

\subsection{\label{ss:errordetection}Error Detection}

If an error occurs in an AST function (for example, if you supply an
invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an
error message will be written to the standard error stream and the
function will immediately return.

To indicate than an error has occurred, an AST \emph{error status}
value is used. This integer value is stored internally by AST and is
initially clear (\emph{i.e.}\ set to zero\footnote{We will assume
throughout that the ``OK'' value is zero, as it currently is. However,
a different value could, in principle, be used if the environment in
which AST is running requires it. This is why a simple interface is
provided to isolate you from the actual value of the error status.}
to indicate no error). If an error occurs, it becomes set to a
different \emph{error value}, which allows you to detect the error, as
follows:

\small
\begin{terminalv}
zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" );
if ( !astOK ) {
   <an error has occurred>
}
\end{terminalv}
\normalsize

The macro \htmlref{astOK}{astOK} is used to test whether the AST error status is still
OK. In this example it would not be, because we have attempted to set
a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not
have such an attribute.  The actual value of the AST error status can
be obtained using the \htmlref{astStatus}{astStatus} macro, as follows:

\small
\begin{terminalv}
int status;

...


status = astStatus;
\end{terminalv}
\normalsize

A consequence of the AST error status being set is that almost all AST
functions will subsequently cease to function and will instead simply
return without action.  This means that you do not need to use astOK
to check for errors very frequently. Instead, you can usually simply
invoke a succession of AST functions. If an error occurs in any of
them, the following ones will do nothing and you can check for the
error at the end, for example:

\small
\begin{terminalv}
astFunctionA( ... );
astFunctionB( ... );
astFunctionC( ... );
if ( !astOK ) {
   <an error has occurred>
}
\end{terminalv}
\normalsize

There are, however, a few functions which do not adhere to this
general rule and which will attempt to execute if the AST error status
is set. These functions, such as \htmlref{astAnnul}{astAnnul}, are concerned with cleaning
up and recovering resources. For example, in the following:

\small
\begin{terminalv}
zoommap = astZoomMap( 2, 5.0, "" );

astFunctionX( ... );
astFunctionY( ... );
astFunctionZ( ... );

zoommap = astAnnul( zoommap );
if ( !astOK ) {
   <an error has occurred>
}
\end{terminalv}
\normalsize

astAnnul will execute normally in order to recover the resources
associated with the ZoomMap that was created earlier, regardless of
whether an error has occurred in any of the intermediate functions.
Functions which behave in this way are noted in the relevant
descriptions in \appref{ss:functiondescriptions}.

If a serious error occurs, you will probably want to abort your
program, but sometimes you may want to recover and carry on. Because
very few AST functions will execute once the AST error status has been
set, you must first clear this status by using the \htmlref{astClearStatus}{astClearStatus}
macro, as follows:

\small
\begin{terminalv}
astClearStatus;
\end{terminalv}
\normalsize

This will restore the AST error status to its OK value, so that AST
functions execute normally again.

Occasionally, you may also need to set the AST error status to an
explicit error value (see \secref{ss:channelsink} for an
example). This is done using \htmlref{astSetStatus}{astSetStatus} and can be used to
communicate to AST that an error has occurred in some other item of
software, for example:

\small
\begin{terminalv}
int new_status;

...

astSetStatus( new_status );
\end{terminalv}
\normalsize

The effect is that most AST routines will subsequently return without
action, just as if an error had occurred within the AST library
itself.

\subsection{Sharing the Error Status}

In some software, it is usual to maintain a single integer error
status variable which is accessed by each function as it executes. If
an error occurs, this status variable is set and other functions can
detect this and take appropriate action.

If you use AST in such a situation, it can be awkward to have a
separate internal error status used by AST functions alone. To remedy
this, AST is capable of sharing the error status variable used by any
other software, so long as they use the same conventions
(\emph{i.e.}\ a C int with the same ``OK'' value). To enable this
facility, you should pass the address of your status variable to
\htmlref{astWatch}{astWatch}, as follows:

\small
\begin{terminalv}
int my_status;
int *old_address;

...

old_address = astWatch( &my_status );
\end{terminalv}
\normalsize

Henceforth, instead of using its own internal error status variable,
AST will use the one you supply, so that it can detect errors flagged
by other parts of your software. The address of the original error
status variable is returned by astWatch, so you can restore the
original behaviour later if necessary.

Note that this facility is not available \emph{via} the Fortran
interface to the AST library.

\cleardoublepage
\section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)}

In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a
\htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its
input to its output and back again (\secref{ss:transforming}). We also
saw how its behaviour could be controlled by setting various
attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made
it display coordinate values as it transformed them.

In this section, we will look at Mappings a bit more thoroughly and
explore the behaviour which is common to all the Mappings provided by
AST.  This is good background for what follows, because many of the
Objects we discuss later will also turn out to be Mappings in various
disguises.

\subsection{\label{ss:mappingclass}The Mapping Class}

Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class
as a whole and some of the sub-classes it contains:

\begin{terminalv}
   Mapping
      CmpMap
      DssMap
      GrismMap
      IntraMap
      LutMap
      MathMap
      MatrixMap
      PermMap
      PolyMap
      SlaMap
      SpecMap
      TimeMap
      UnitMap
      WcsMap
      ZoomMap

      Frame
         <various types of Frame>
\end{terminalv}

The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered
in detail in \secref{ss:frames}. We start by looking at the parent
class, Mapping.

AST does not provide a function to create a basic Mapping
(\emph{i.e.}\ the astMapping constructor does not exist). This is
because the Mapping class itself is ``virtual'' and basic Mappings are
of no use in themselves. The Mapping class serves simply to contain
the various specialised Mappings that exist.
However, it provides more than just a convenient heading for them
because it bestows all classes of Mapping with common properties
(\emph{e.g.}\ attributes) and behaviour.  By examining the Mapping
class, we are therefore examining the things that all other Mappings
have in common.

\subsection{The Mapping Model}

The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}.
It is a black box which you can supply with a set of coordinate values
in return for a set of transformed coordinates. The two sets are
termed \emph{input} and \emph{output} coordinates. You can also go
back the other way and transform output coordinates back into input
coordinates, as we saw in \secref{ss:transforming}.

\subsection{Changing Attributes of a Mapping}

Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter
used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an
attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each
coordinate is to be multiplied. These attribute values should be set when
the Mapping is created and should not be changed afterwards. Indeed, the
AST library will report an error if an attempt is made to change the
value of a Mapping attribute. This is because, once created, Mappings are
often later included within other objects such as FrameSets and CmpMaps.
This means that in general there could be many active references to a single
Mapping object within a program. Changing an attribute of the Mapping
via one particular reference (i.e pointer) would cause all the other
references to change too, with often undesirable or unpredictable
consequences. To avoid this, Mappings are considered \emph{immutable} in
most situations. The one exception is if the Mapping has not yet been
cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference
couint of one) - changing the attributes of such a Mapping is allowed,
and will not generate an error.

Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and
can be changed at any time.

\subsection{Input and Output Coordinate Numbers}

In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to
represent a single point need not be the same as the number that comes
out. Often these numbers will be the same, and often they will both
equal 2 (because 2-dimensional coordinate systems are common), but
this needn't necessarily be the case.

The number of coordinates required to specify an input point is
represented by the integer attribute \htmlref{Nin}{Nin} and the number required to
specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only
attributes common to all Mappings. Generally, their values are fixed
when a Mapping is created.

In \secref{ss:objectcreation}, we saw how the Nin attribute for a
\htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function
\htmlref{astZoomMap}{astZoomMap} which created it. In this case, the Nout attribute was not
needed and it implicitly took the same value as Nin, but we could
have enquired about its value had we wanted, as follows:

\small
\begin{terminalv}
#include "ast.h"
AstZoomMap *zoommap;
int nout;

...

nout = astGetI( zoommap, "Nout" );
\end{terminalv}
\normalsize

\subsection{Forward and Inverse Transformations}

We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates
either from input to output, or \emph{vice versa}. These are termed
its \emph{forward} and \emph{inverse} transformations.

This statement was not quite accurate, however, because in general
Mappings are only \textbf{potentially} capable of working in both
directions. In practice, coordinate transformation may only be
feasible in one direction or the other because some functions are not
easily inverted (they may be multi-valued, for instance). Allowance
must be made for this, so each Mapping has two read-only boolean
(integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate
whether each transformation is available.

A transformation is available if the corresponding attribute is
non-zero, otherwise it is not.\footnote{Most of the Mappings provided
by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can
behave otherwise.} If you enquire about the value of these attributes,
a value of 0 or 1 is returned.  Attempting to use a Mapping to apply a
transformation which is not available will result in an error.

\subsection{\label{ss:invertingmappings}Inverting Mappings}

An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert}
flag. This is a boolean (integer) attribute that can be assigned a new
value at any time. If it is non-zero, it has the effect of
interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the
Mapping is then said to be \emph{inverted}. By default, the Invert
attribute is zero.

There is no magic in this. There is no fancy arithmetic involved in
inverting mathematical functions, for instance. The Invert flag is
simply a switch that interchanges a Mapping's input and output
ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are
swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and
when you ask for what was once the forward transformation you get the
inverse transformation instead (and \emph{vice versa}). When you
return the Invert attribute to zero, or clear it, the Mapping returns
to its original behaviour.

Often, the actual value of the Invert attribute is unimportant and you
simply wish to invert its boolean sense, so that what was the
Mapping's input becomes its output and \emph{vice versa}. This is most
easily accomplished using \htmlref{astInvert}{astInvert}, as follows:

\small
\begin{terminalv}
AstMapping *mapping;

...

astInvert( mapping );
\end{terminalv}
\normalsize

If the Mapping you have happens to be the wrong way around, astInvert
allows you to correct the problem.

\subsection{Finding the Rate of Change of a Mapping Output}
The
\htmlref{astRate}{astRate}
function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output
with respect to any Mapping input, at a given input position. The method
used produces good accuracy (typically a relative error of 10E-10 or
less) but may require the Mapping to be evaluated 100 or more times.
An estimate of the second derivative is also produced by this function.


\subsection{Reporting Coordinate Transformations}

We have already seen (\secref{ss:transforming}) how the boolean
(integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the
operation of transforming a set of coordinates will result in a report
being written to standard output. This will display the coordinate
values before and after transformation. It can save considerable time
during program development by eliminating the need to add loops and
output statements to your program.

In a finished program, however, you should be careful that the Report
attribute is not set to a non-zero value unless you want to see the
output (there may often be rather a lot of this!). To help prevent
unwanted output being produced by accident, the Report attribute is
unusual in that its value is not preserved when a Mapping is copied
using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). Instead, it reverts to its
default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to
zero when a Mapping is written out, \emph{e.g.}\ to a file using a
\htmlref{Channel}{Channel} (\secref{ss:channels}).

%\subsection{TBW---More on Transforming Coordinates}

\subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values}

Even when coordinates can, in principle, be transformed in either
direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific
coordinate values cannot be handled. For example, the Mapping may be
mathematically intractable (\emph{e.g.}\ singular) in certain places,
or it may map a subset of one space on to another, so that some points
in one space are not represented in the other.  Sky projections often
show this behaviour, since it is quite common to project only half of
the celestial sphere on to two dimensions, omitting points on the
opposite side of the sky. There are many other examples.

To indicate when coordinates cannot be transformed, for whatever
reason, AST substitutes a special output coordinate value given by the
macro AST\_\_BAD (as defined in the ``ast.h'' header file).  Before
making use of coordinates generated by any of the AST transformation
functions, therefore, you may need to check for the presence of this
value.

Because coordinates with the value AST\_\_BAD can be generated in this
way, all other AST functions are also capable of recognising this
value and handling it appropriately. The coordinate transformation
functions do this by propagating any missing input coordinate
information through to their output.  This means that if you supply
coordinates with the value AST\_\_BAD, the returned coordinates are
also likely to contain this value. Here, for example, is what happens
if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of
coordinates:

\small
\begin{terminalv}
(0, 0) --> (0, 0)
(<bad>, 2) --> (<bad>, 10)
(2, 4) --> (10, 20)
(3, 6) --> (15, 30)
(4, <bad>) --> (20, <bad>)
(5, 10) --> (25, 50)
(<bad>, <bad>) --> (<bad>, <bad>)
(7, 14) --> (35, 70)
(8, 16) --> (40, 80)
(9, 18) --> (45, 90)
\end{terminalv}
\normalsize

The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This
is a case of ``garbage in, garbage out'' but at least it's consistent
garbage that you can recognise!

Note how the presence of the AST\_\_BAD value in one input dimension
does not necessarily result in the loss of information for all output
dimensions. Sometimes, such loss will be unavoidable, but in general
an attempt is made to preserve information as far as possible. The
exact behaviour will depend on the Mapping involved.

\subsection{\label{ss:unitmapexample}Example---the UnitMap}

The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its
purpose is simply to copy coordinate values, unaltered, from its input
to its output and \emph{vice versa}.

A UnitMap has no additional attributes beyond those of a basic
Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are
specified by the first argument supplied to its constructor. For
example:

\small
\begin{terminalv}
AstUnitMap *unitmap;

...

unitmap = astUnitMap( 2, "" );
\end{terminalv}
\normalsize

will create a UnitMap that copies 2-dimensional coordinates. Inverting
a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert}
attribute.

The main use of a UnitMap is to allow a Mapping to be supplied when one
is required (as an argument to a function, for example) but you wish
it to leave coordinate values unchanged.

\subsection{\label{ss:permmapexample}Example---the PermMap}

The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met
previously.  Its purpose is to change the order, or number, of
coordinates. It is also able to substitute fixed values for
coordinates.

To illustrate its action, suppose our input coordinates are denoted by
($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output
coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore,
should rotate the coordinate values by one position.

To create such a PermMap, we first set up two integer arrays. One of
these, ``outperm'', controls the selection of input coordinates for
use in the output and the other, ``inperm'', controls selection of
output coordinates for use in the input:

\small
\begin{terminalv}
int outperm[ 4 ] = { 4, 1, 2, 3 };
int inperm[ 4 ] = { 2, 3, 4, 1 };
\end{terminalv}
\normalsize

Note that the numbers we store in these arrays are the indices of the
coordinates that we want to select. We have chosen these so that the
forward and inverse transformations will perform complementary
permutations on the coordinates.

The PermMap is then created by passing these arrays to its
constructor, as follows:

\small
\begin{terminalv}
AstPermMap *permmap;

...

permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" );
\end{terminalv}
\normalsize

Note that we specify the number of input and output coordinates
separately, but set both to 4 in this example. The resulting PermMap
would have the following effect when used to transform coordinates:

\begin{terminalv}
Forward:
   (1, 2, 3, 4) --> (4, 1, 2, 3)
   (2, 4, 6, 8) --> (8, 2, 4, 6)
   (3, 6, 9, 12) --> (12, 3, 6, 9)
   (4, 8, 12, 16) --> (16, 4, 8, 12)
   (5, 10, 15, 20) --> (20, 5, 10, 15)

Inverse:
   (4, 1, 2, 3) --> (1, 2, 3, 4)
   (8, 2, 4, 6) --> (2, 4, 6, 8)
   (12, 3, 6, 9) --> (3, 6, 9, 12)
   (16, 4, 8, 12) --> (4, 8, 12, 16)
   (20, 5, 10, 15) --> (5, 10, 15, 20)
\end{terminalv}

If the number of input and output coordinates are unequal so, also,
will be the size of the ``outperm'' and ``inperm'' arrays. This means,
however, that we cannot fill them with coordinate indices so that they
perform complementary permutations, because one transformation will
lose information (discard a coordinate) that the other cannot recover.
To give an example, consider the following:

\small
\begin{terminalv}
int outperm[ 3 ] = { 4, 3, 2 };
int inperm[ 4 ] = { -1, 3, 2, 1 };
double con[ 1 ] = { 99.004 };
\end{terminalv}
\normalsize

In this case, the forward transformation will change
($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The
inverse transformation restores the original coordinate order, but has
no value to assign to the first coordinate. In this case, the number
entered in the ``inperm'' array is $-$1.

This negative value indicates that the coordinate value should be
obtained by addressing the first element of the ``con'' array
(\emph{i.e.}\ element zero). This array, ignored in the previous
example, may then be used to supply a value for the missing
coordinate.

The constructor function:

\small
\begin{terminalv}
permmap = astPermMap( 4, inperm, 3, outperm, con, "" );
\end{terminalv}
\normalsize

will then create a PermMap with the following effect when used to
transform coordinates:

\begin{terminalv}
Forward:
   (1, 2, 3, 4) --> (4, 3, 2)
   (2, 4, 6, 8) --> (8, 6, 4)
   (3, 6, 9, 12) --> (12, 9, 6)
   (4, 8, 12, 16) --> (16, 12, 8)
   (5, 10, 15, 20) --> (20, 15, 10)

Inverse:
   (4, 3, 2) --> (99.004, 2, 3, 4)
   (8, 6, 4) --> (99.004, 4, 6, 8)
   (12, 9, 6) --> (99.004, 6, 9, 12)
   (16, 12, 8) --> (99.004, 8, 12, 16)
   (20, 15, 10) --> (99.004, 10, 15, 20)
\end{terminalv}

The ``con'' array may contain more than one value if necessary and may
be addressed by both the ``inperm'' and ``outperm'' arrays using
coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the
first, second, third,~\emph{etc.}\ elements.

If there is no suitable replacement value that can be supplied
\emph{via} the ``con'' array, a value of zero may be entered into the
``outperm'' and/or ``inperm'' arrays. This causes the value AST\_\_BAD
to be used for the affected coordinate (as defined in the ``ast.h''
header file), thus indicating a missing coordinate value
(\secref{ss:badcoordinates}).

The principle use for a PermMap lies in matching a coordinate system
to a data array where there is a choice of storage order for the data.
PermMaps are also useful for discarding unwanted coordinates so as to
reduce the number of dimensions, such as when selecting a ``slice''
from a multi-dimensional array.

\cleardoublepage
\section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)}

We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The
Mappings we have considered so far have been atomic, in the sense that
they perform pre-defined elementary transformations. A CmpMap,
however, is a compound Mapping. In essence, it is a framework for
containing other Mappings and its purpose is to allow those Mappings
to work together in various combinations while appearing as a single
\htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is
determined by the other Mappings it contains.

\subsection{\label{ss:seriescmpmap}Combining Mappings in Series}

Consider a simple example based on two 2-dimensional coordinate
systems. Suppose that to convert from one to the other we must swap
the coordinate order and multiply both coordinates by 5, so that the
coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done
in two stages:

\begin{enumerate}
\item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the
coordinate order.

\item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both
coordinate values by the constant 5.
\end{enumerate}

The PermMap and ZoomMap are then said to operate \emph{in series},
because they are applied sequentially
(\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}).  We can create a \htmlref{CmpMap}{CmpMap}
that applies these Mappings in series as follows:

\small
\begin{terminalv}
#include "ast.h"
AstCmpMap *cmpmap;
AstPermMap *permmap;
AstZoomMap *zoommap;

...

/* Create the individual Mappings. */
{
   int inperm[ 2 ] = { 2, 1 };
   int outperm[ 2 ] = { 2, 1 };
   permmap = astPermMap( 2, inperm, 2, outperm, NULL, "" );
}
zoommap = astZoomMap( 2, 5.0, "" )

/* Combine them in series. */
cmpmap = astCmpMap( permmap, zoommap, 1, "" );

/* Annul the individual Mapping pointers. */
permmap = astAnnul( permmap );
zoommap = astAnnul( zoommap );
\end{terminalv}
\normalsize

Here, the third argument (1) of the constructor function \htmlref{astCmpMap}{astCmpMap}
indicates ``in series''.

When used to transform coordinates in the forward direction, the
resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap)
and then the second one (the ZoomMap). When transforming in the
inverse direction, it will apply the second one (in the inverse
direction) and then the first one (also in the inverse direction).  In
general, although not in this particular example, the order in which
the two component Mappings are supplied is significant. Clearly, also,
the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first
Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for
the second one.

\subsection{Combining Mappings in Parallel}

Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the
only way of combining them. The alternative, \emph{in parallel},
involves applying the two Mappings at once but on different subsets of
the coordinate values.

Consider, for example, a set of 3-dimensional coordinates and suppose
we wish to transform them by swapping the first two coordinate values
and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms
into ($x_2,x_1,5x_3$). Again, we can perform each of these steps
individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used
earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is
1-dimensional and the individual Mappings are applied in parallel
(\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}).

Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple:

\small
\begin{terminalv}
cmpmap = astCmpMap( permmap, zoommap, 0, "" );
\end{terminalv}
\normalsize

The only difference is that the third argument of \htmlref{astCmpMap}{astCmpMap} is now
zero, meaning ``in parallel''.

As before, the order in which the two component Mappings are supplied
is significant. The first one acts on the lower-numbered input
coordinate values (however many it needs) and produces the
lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on
the higher-numbered input coordinates (however many remain) and
generates the remaining higher-numbered output coordinates.  When the
CmpMap transforms coordinates in the inverse direction, both component
Mappings are applied to the same coordinates, but in the inverse
direction.

Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings
(\emph{i.e.}\ the numbers of input and output coordinates) will sum to
give the Nin and Nout attributes of the overall CmpMap.

\subsection{\label{ss:cmpmapcomponents}The Component Mappings}

A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply
holds pointers to them. In the example above
(\secref{ss:seriescmpmap}), we were free to annul the individual
\htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held
internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount}
attribute) of each component Mapping by one. The individual components
are therefore not deleted by \htmlref{astAnnul}{astAnnul}, but retained until the CmpMap
itself is deleted and annuls the pointers it holds. Consistent use of
astAnnul (\secref{ss:annullingpointers}) and/or pointer contexts
(\secref{ss:contexts}) will therefore ensure that all Objects are
deleted at the appropriate time.

Note that access to a CmpMap's component Mappings is not generally
available unless pointers to them are retained when the CmpMap is
created. If such pointers are retained, then subsequent modifications
to the individual components can be used to indirectly modify the
behaviour of the overall CmpMap.

There is an important exception to this, however, because a CmpMap
retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its
components and uses these in order to ignore any subsequent external
changes. This means that you may invert either component Mapping
before inserting it into a CmpMap and need not worry if you un-invert
it again later. The CmpMap's behaviour will not be affected by the
later action.

\subsection{\label{ss:complexcmpmap}Creating More Complex Mappings}

Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can
substitute (\secref{ss:objecthierarchy}) as a component Mapping when
constructing a new CmpMap using \htmlref{astCmpMap}{astCmpMap}. This has the effect of
nesting one CmpMap inside another and opens up many new possibilities.
For example, combining three Mappings in series can be accomplished as
follows:

\small
\begin{terminalv}
AstMapping *map1, *map2, *map3;

...

cmpmap = astCmpMap( map1, astCmpMap( map2, map3, 1, "" ), 1, "" );
\end{terminalv}
\normalsize

The way in which the individual component Mappings are grouped within
the nested CmpMaps is not usually important.

A similar technique can be used to combine multiple Mappings in
parallel and, of course, mixed series and parallel combinations are
also possible (Figure~\ref{fig:complexcmpmap}).  There is no built-in
limit to how many CmpMaps may be nested in this way, so this mechanism
provides an indefinitely extensible method of building complex
Mappings out of the elemental building blocks provided by AST.

In practice, you might not need to construct such complex CmpMaps
yourself very frequently, but they will often be returned by AST
routines.  Nested CmpMaps underlie the library's entire ability to
represent a wide range of different coordinate transformations.

\subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images}

Consider, as a practical example of CmpMaps, two images of the
sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from
pixel coordinates to a standard celestial coordinate system, say
FK5~(J2000.0). If we wish to inter-compare these images, we can do so
by using this celestial coordinate system to align them. That is, we
first convert from pixel coordinates in the first image into FK5
coordinates and we then convert from FK5 coordinates into pixel
coordinates in the second image.

If ``mapa'' and ``mapb'' are pointers to our two original Mappings, we
could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel
coordinates of the first and second images by combining these
Mappings, as follows:

\small
\begin{terminalv}
AstCmpMap *alignmap;
AstMapping *mapa, *mapb;

...

astInvert( mapb );
alignmap = astCmpMap( mapa, mapb, 1, "" );
astInvert( mapb );
\end{terminalv}
\normalsize

Here, we have used \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}) to invert
``mapb'' before inserting it into the CmpMap because, as supplied, it
converted in the wrong direction. Afterwards, we invert it again to
return it to its original state. The CmpMap, however, will ignore this
subsequent change (\secref{ss:cmpmapcomponents}).

The forward transformation of the resulting CmpMap will now transform
from pixel coordinates in the first image to pixel coordinates in the
second image, while its inverse transformation will convert in the
opposite direction.

\subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings}

While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing
arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it
unfortunately also provides an opportunity for representing simple
Mappings in complex ways. Sometimes, unnecessary complexity can be
difficult to avoid but can obscure important simplifications.

Consider the example above (\secref{ss:cmpmapexample}), in which we
inter-related two images of the sky \emph{via} a CmpMap.  If the two
images turned out to be simply offset from each other by a shift along
each pixel axis, then this approach would align them correctly, but it
would be inefficient. This is because it would introduce unnecessary
and expensive transformations to and from an intermediate celestial
coordinate system, whereas a simple shift of pixel origin would
suffice.

Recognising that a simpler and more efficient solution exists
obviously requires a little more than simply joining two Mappings
end-to-end. We must also determine whether the resulting CmpMap is
more complex than it needs to be, \emph{i.e.}\ contains redundant
information. If it is, we then need a way to simplify it.

The problem is not always just one of efficiency, however. Sometimes
we may also need to know something about the actual form a \htmlref{Mapping}{Mapping}
takes---\emph{i.e.}\ the nature of the operations it performs.
Unnecessary complexity can obscure this, but such complexity can
easily accumulate during normal data processing.

For example, a Mapping that transforms pixel coordinates into
positions on the sky might be repeatedly modified as changes are made
to the shape and size of the image. Typically, on each occasion,
another Mapping will be concatenated to reflect what has happened to
the image. This could soon make it difficult to discern the overall
nature of the transformation from the complex CmpMap that
accumulates. If only shifts of origin were involved on each occasion,
however, they could be combined into a single shift which could be
represented much more simply.

Suppose we now wanted to represent our image's celestial coordinate
calibration using FITS conventions (\secref{ss:foreignfits}). This
requires AST to determine whether the Mapping which relates pixel
coordinate to sky positions conforms to the FITS model (for example,
whether it is equivalent to applying a single set of shifts and scale
factors followed by a map projection). Clearly, there is an important
use here for some means of simplifying the internal structure of a
CmpMap.

\subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings}

The ability to simplify compound Mappings is provided by the
\htmlref{astSimplify}{astSimplify} function. This function encapsulates a number of
heuristics for converting Mappings, or combinations of Mappings within
a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap,
astSimplify tries to reduce the number of individual Mappings within
it by merging neighbouring component Mappings together. It will do
this with both series and parallel combinations of Mappings, or both,
and will handle CmpMaps nested to any depth
(\secref{ss:complexcmpmap}).

   To illustrate how astSimplify works, consider the combination of
   Mappings shown in Figure~\ref{fig:simplifyexample}.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/simpexamp}
   \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps,
   ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single
   UnitMap.  The enclosing nested CmpMaps have been omitted for clarity.}
   \label{fig:simplifyexample}
   \end{center}
   \end{figure}

If this were contained in a CmpMap, it could be simplified as follows:

\small
\begin{terminalv}
AstMapping *simpler;

...

simpler = astSimplify( cmpmap );
\end{terminalv}
\normalsize

In this case, the result would be a simple 3-dimensional UnitMap (the
identity \htmlref{Mapping}{Mapping}).  To reach this conclusion, astSimplify will have
made a number of deductions, roughly as follows:

\begin{enumerate}
\item The two 2-dimensional ZoomMaps in series are equivalent to a
single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is
equivalent to a 2-dimensional UnitMap.

\item This UnitMap in parallel with the other 1-dimensional UnitMap is
equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched
between any other pair of Mappings, can then be eliminated.

\item The remaining two PermMaps in series are equivalent to a single
3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap
is found to be equivalent to a 3-dimensional UnitMap.
\end{enumerate}

This example is a little contrived, but illustrates how astSimplify
can deal with even quite complicated compound Mappings through a
series of incremental simplifications. Where possible, this will
result in either a simpler compound Mapping or, if feasible, an atomic
(non-compound) Mapping, as here. If no simplification is possible,
astSimplify will just return a pointer to the original Mapping.

Although astSimplify cannot identify every simplification that is
theoretically possible, sufficient rules are included to deal with the
most common and important cases.

\cleardoublepage
\section{\label{ss:frames}Representing Coordinate Systems (Frames)}

An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate
system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is
used to describe how to convert between coordinate systems. The two
concepts are complementary and we will see how they work together in
\secref{ss:framesets}.

In this section we will discuss only basic Frames, which represent
Cartesian coordinate systems. More specialised types of Frame
(\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate
systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate
systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes})
and, naturally, inherit the properties and behaviour of the simple Frames
discussed here.

\subsection{The Frame Model}

The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would
plot around a graph. In two dimensions, you would have an ``$x$'' and
a ``$y$'' axis, a title on the graph and labels on the axes, together
with an indication of the physical units being plotted. The values
marked along each axis would be formatted in a human-readable way. The
frame around a graph therefore defines a coordinate space within which
you can locate points, draw lines, calculate distances, \emph{etc.}

An AST Frame works in much the same way, embodying all of these
concepts and a few more. It also allows any number of axes, which
means that a Frame can represent coordinate systems with any number of
dimensions. You specify how many when you create it.

Remember that the basic Frame we are considering here is completely
general.  It knows nothing of celestial coordinates, for example, and
all its axes are equivalent. It can be adapted to describe any general
purpose Cartesian coordinate system by setting its attributes, such as
its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values.

\subsection{\label{ss:creatingframes}Creating a Frame}

Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern:

\small
\begin{terminalv}
#include "ast.h"
astFrame *frame;

...

frame = astFrame( 2, "" );
\end{terminalv}
\normalsize

The first argument of the \htmlref{astFrame}{astFrame} constructor function specifies the
number of axes which the Frame should have.

\subsection{\label{ss:frameasmapping}Using a Frame as a Mapping}

We should briefly point out that the \htmlref{Frame}{Frame} we created above
(\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping}
(\secref{ss:mappingclass}) and therefore inherits the properties and
behaviour common to other Mappings.

One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited
from the Mapping class) to a non-zero value and pass the Frame pointer
to a coordinate transformation function, such as \htmlref{astTran2}{astTran2}.

\small
\begin{terminalv}
double xin[ 5 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 };
double yin[ 5 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0 };
double xout[ 5 ];
double yout[ 5 ];

...

astSet( frame, "Report=1" );
astTran2( frame, 5, xin, yin, 1, xout, yout );
\end{terminalv}
\normalsize

The resulting output might then look like this:

\begin{terminalv}
(1, 2) --> (1, 2)
(2, 4) --> (2, 4)
(3, 6) --> (3, 6)
(4, 8) --> (4, 8)
(5, 10) --> (5, 10)
\end{terminalv}

This is not very exciting because a Frame implements an identity
transformation just like a \htmlref{UnitMap}{UnitMap}
(\secref{ss:unitmapexample}). However, it illustrates that a Frame can
be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both
equal to the number of Frame axes.

When we consider more specialised Frames
(\emph{e.g.}~\secref{ss:framesets}), we will see that using them as
Mappings can be very useful indeed.

\subsection{\label{ss:frameaxisattributes}Frame Axis Attributes}

Frames have a number of attributes which can take multiple values, one
for each axis. These separate values are identified by appending the
axis number in parentheses to the attribute name. For example, the
Label(1) attribute is a character string containing the label which
appears on the first axis.

\htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes
(\secref{ss:gettingattributes}, \secref{ss:settingattributes} and
\secref{ss:defaultingattributes}). For example, the Label on the second
axis might be obtained as follows:

\small
\begin{terminalv}
const char *label;

...

label = astGetC( frame, "Label(2)" );
\end{terminalv}
\normalsize

Other attribute access functions (astSetX, \htmlref{astTest}{astTest} and \htmlref{astClear}{astClear}) may
also be applied to axis attributes in the same way.

If the axis number is stored in a program variable, then its value
must be formatted to generate a suitable attribute name before using
this to access the attribute itself. For example, the following will
print out the Label value for each axis of a \htmlref{Frame}{Frame}:

\small
\begin{terminalv}
#include <stdio.h>
char name[ 18 ];
int iaxis, naxes;

...

naxes = astGetI( frame, "Naxes" );
for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {
   (void) sprintf( name, "Label(%d)", iaxis );
   label = astGetC( frame, name );
   (void) printf( "Label %2d: %s\n", iaxis, label );
}
\end{terminalv}
\normalsize

Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame
axes.

The output from this might look like the following:

\begin{terminalv}
Label  1: Axis 1
Label  2: Axis 2
\end{terminalv}

In this case, the Frame's default axis Labels have been revealed as
rather un-exciting. Normally, you would set much more useful values,
typically when you create the Frame---perhaps something like:

\small
\begin{terminalv}
frame = astFrame( 2, "Label(1)=Offset from centre of field,"
                     "Unit(1) =mm,"
                     "Label(2)=Transmission coefficient,"
                     "Unit(2) =%" );
\end{terminalv}
\normalsize

Here, we have also set the (character string) Unit attribute for each
axis to describe the physical units represented on that axis. All the
attribute assignments have been combined into a single string,
separated by commas.

\subsection{\label{ss:frameattributes}Frame Attributes}

We will now briefly outline the various attributes associated with a
\htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the
\htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each
attribute, for which you should consult the appropriate description in
\appref{ss:attributedescriptions}. Instead, we aim simply to sketch
the range of facilities available:

\begin{quote}
\begin{description}
\item[\htmlref{Naxes}{Naxes}]\mbox{}\\
A read-only integer giving the number of Frame axes.

\item[\htmlref{Title}{Title}]\mbox{}\\
A string describing the coordinate system which the Frame represents.

\item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\
A label string for each axis.

\item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\
A string describing the physical units on each axis. You can choose
whether to make this attribute ``active'' or ``passive'' (using
\htmlref{astSetActiveUnit}{astSetActiveUnit}
). If active, its value will be taken into account when finding the
Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used
to connect two axis with units of ``km'' and ``m''). If passive, its value
is ignored. Its use is described in more detail in \secref{ss:frameunits}.

\item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\
A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X''
or ``Y'') used to represent the quantity plotted on each axis.

\item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\
The preferred number of digits of precision to be used when formatting
values for display on each axis.

\item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\
A string containing a \emph{format specifier} which determines exactly
how values should be formatted for display on each axis
(\secref{ss:formattingaxisvalues}). If this attribute is un-set, the
formatting is based on the Digits value, otherwise the Format string
over-rides the Digits value.

\item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\
A boolean (integer) value which indicates in which direction each axis
should be plotted. If it is non-zero (the default), the axis should be
plotted in the conventional direction---\emph{i.e.}\ increasing to the
right for the abscissa and increasing upwards for the ordinate. If it
is zero, the axis should be plotted in reverse.  This attribute is
provided as a hint only and programs are free to ignore it if they
wish.

\item[\htmlref{Domain}{Domain}]\mbox{}\\
A character string which identifies the \emph{physical domain} to
which the Frame's coordinate system applies. The primary purpose of
this attribute is to prevent unwanted conversions from occurring
between coordinate systems which are not related. Its use is described
in more detail in \secref{ss:framedomains}.

\item[\htmlref{System}{System}]\mbox{}\\
A character string which identifies the specific coordinate system used
to describe positions within the physical domain represented by the Frame.
For a simple Frame, this attribute currently has a fixed value of
``Cartesian'', but could in principle be extended to include options such
as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such
as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}  and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be
appropriate to the domain which they describe. For instance, the SkyFrame
allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows
values such as ``frequency'' and ``wavelength''.

\item[\htmlref{Epoch}{Epoch}]\mbox{}\\
This value is used to qualify a coordinate system by giving the moment in
time when the coordinates are correct. Usually, this will be the date of
observation. The Epoch value is important in cases where coordinates
systems move with respect to each other over time. An example of two such
coordinate systems are the FK4 and FK5 celestial coordinate systems.

\item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\
Specifies the longitude of the observer (assumed to be on the surface of
the earth). The basic Frame class does not use this value, but
specialised sub-classes may. For instance, the SpecFrame class uses it to
calculate the relative velocity of the observer and the centre of the
earth for use in converting between standards of rest.

\item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\
Specifies the latitude of the observer. Use in conjunction with ObsLon.

\end{description}
\end{quote}

There are also some further Frame attributes, not described above,
which are important when Frames are used as templates to search for
other Frames. Their use goes beyond the present discussion.
%TBW---Add reference here.

\subsection{\label{ss:formattingaxisvalues}Formatting Axis Values}

The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored
(\emph{e.g.}\ within your program) as double values. The Frame class
therefore provides a function, \htmlref{astFormat}{astFormat}, to convert these values into
formatted strings for display:

\small
\begin{terminalv}
const char *string
double value;

...

string = astFormat( frame, iaxis, value );
\end{terminalv}
\normalsize

Here, the astFormat function is passed a Frame pointer, the number of
an axis (``iaxis'') and a double precision value to format
(``value''). It returns a pointer to character string containing the
formatted value.
\label{ss:formattingwithdigits}

By default, the formatting applied will be determined by the Frame's
Digits attribute and will normally display results with seven digits
of precision (corresponding approximately to the C ``float'' data type
on many machines). Setting a different Digits value, however, allows
you to adjust the precision as necessary to suit the accuracy of the
coordinate data you are processing.  If finer control is needed, it is
also possible to set a Digits value for each individual axis by
appending an axis number to the attribute name
(\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the
effect of the Frame's main Digits value for that axis.

Even finer control is possible by setting the (character string) Format
attribute for a Frame axis. The string given should contain a C
\emph{format specifier} which explicitly determines how the values on
that axis should be formatted. This will over-ride the effects of any
Digits value\footnote{The exception to this rule is that if the Format
value includes a precision of ``$.*$'', then Digits will be used to
determine the actual precision used.}. Any valid ``printf'' format
specifier may be used so long as it consumes exactly one double value.

When setting Format values, remember that the ``\%'' which appears in
the format specifier may need to be doubled to ``\%\%'' if you are
using a function (such as \htmlref{astSet}{astSet}) which interprets ``printf'' format
specifiers itself.

It is recommended that you use astFormat whenever you display
formatted coordinate values, even although you could format them
yourself using ``sprintf''. This is because it puts the Frame in
control of formatting. When you start to handle more elaborate Frames
(representing, say, celestial coordinates), you will need different
formatting methods. This approach delivers them without any change to
your software.

You should also consider regularly using the \htmlref{astNorm}{astNorm} function,
described below (\secref{ss:normalising}), for any values that will be
made visible to the user of your software.

\subsection{\label{ss:normalising}Normalising Frame Coordinates}

The function \htmlref{astNorm}{astNorm} is provided to cope with the fact that some
coordinate systems do not extend indefinitely in all directions. Some
may have boundaries, outside which coordinates are meaningless, while
others wrap around on themselves, so that after a certain distance you
return to the beginning again (coordinate systems based on circles and
spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but
other more specialised Frames (such as SkyFrames, representing the
celestial sphere---\secref{ss:skyframes}) do.

The role played by astNorm is to \emph{normalise} any arbitrary set of
coordinates by converting them into a set which is ``within bounds'',
interpreted according to the particular Frame in question. For
example, on the celestial sphere, a right ascension value of 24~hours
or more can have a suitable multiple of 24~hours subtracted without
affecting its meaning and astNorm would perform this task. Similarly,
negative values of right ascension would have a multiple of 24~hours
added, so that the result lies in the range zero to 24~hours. The
coordinates in question are modified in place by astNorm, as follows:

\small
\begin{terminalv}
double point[ 2 ];

...

astNorm( frame, point );
\end{terminalv}
\normalsize

If the coordinates supplied are initially OK, as they would always be
with a basic Frame, then they are returned unchanged.

Because the main purpose of astNorm is to convert coordinates into the
preferred range for human consumption, its use is almost always
appropriate immediately before formatting coordinate values for
display using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}). Even if
the Frame in question does not restrict the range of coordinates, so
that astNorm does nothing, using it will allow you to process other
more specialised Frames, where normalisation is important, without
changing your software.

\subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values}

The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame}
axis, such as might be produced by \htmlref{astFormat}{astFormat}
(\secref{ss:formattingaxisvalues}), back into a numerical (double)
value ready for processing is performed by \htmlref{astUnformat}{astUnformat}.  However,
although this process is essentially the inverse of that performed by
astFormat, there are a number of additional difficulties that must be
addressed in practice.

The main use for astUnformat is in reading formatted coordinate values
which have been entered by the user of a program, or read from a
file. As such, we can rarely assume that the values are neatly
formatted in the way that astFormat would produce. Instead, it is
usually desirable to allow considerable flexibility in the form of
input that can be accommodated, so as to permit ``free-format'' data
input by the user. In addition, we may need to extract individual
coordinate values embedded in other textual data.

Underlying these requirements is the root difficulty that the textual
format used to represent a coordinate value will depend on the class
of Frame we are considering. For example, for a basic Frame,
astUnformat may have to read a value like ``1.25e-6'', whereas for a
more specialised Frame representing celestial coordinates it may have
to handle a value like ``-07d~49m~13s''. Of course, the format might
also depend on which axis is being considered.

Ideally, we would like to write software that can handle any kind of
Frame. However, this makes it a little more difficult to analyse
textual input data to extract individual coordinate values, since we
cannot make assumptions about how the values are formatted. It would
not be safe, for example, simply to assume that the values being read
are separated by white space. This is not just because they might be
separated by some other character, but also because celestial
coordinate values might themselves contain spaces. In fact, to be
completely safe, we cannot make any assumptions about how a formatted
coordinate value is separated from the surrounding text, except that
it should be separated in some way which is not ambiguous.

This is the very basic assumption upon which astUnformat works. It is
invoked as follows:

\small
\begin{terminalv}
int n;

...

n = astUnformat( frame, iaxis, string, &value );
\end{terminalv}
\normalsize

It is supplied with a Frame pointer (``frame''), the number of an axis
(``iaxis'') and a character string to be read (``string''). If it
succeeds in reading a value, astUnformat returns the resulting
coordinate to the address supplied \emph{via} the final argument
(``\&value''). The returned function value indicates how many
characters were read from the string in order to obtain this result.

The string is read as follows:

\begin{enumerate}
\item Any white space at the start is skipped over.

\item Further characters are considered, one at a time, until the next
character no longer matches any of the acceptable forms of input
(given the characters that precede it). The longest sequence of
characters which matches is then considered ``read''.

\item If a suitable sequence of characters was read successfully, it
is converted into a coordinate value which is returned. Any white
space following this sequence is then skipped over and the total
number of characters consumed is returned as the function value.

\item If the sequence of characters read is empty, or insufficient to
define a coordinate value, then the string does not contain a value to
read. In this case, the read is aborted and astUnformat returns a
function value of zero and no coordinate value.  However, it returns
without error.
\end{enumerate}

Note that failing to read a coordinate value does not constitute an
error, at least so far as astUnformat is concerned. However, an error
can occur if the sequence of characters read appears to have the
correct form but cannot be converted into a valid coordinate
value. Typically, this will be because it violates some constraint,
such as a limit on the value of one of its fields. The resulting error
message will give details.

For any given Frame axis, astUnformat does not necessarily always use
the same algorithm for converting the sequence of characters it reads
into a coordinate value. This is because some forms of input
(particularly free-format input) can be ambiguous and might be
interpreted in several ways depending on the context. For example, the
celestial longitude ``12:34:56.7'' could represent an angle in degrees
or a right ascension in hours. To decide which to use, astUnformat may
examine the Frame's attributes and, in particular, the appropriate
\htmlref{Format(axis)}{Format(axis)} string which is used by astFormat when formatting
coordinate values (\secref{ss:formattingaxisvalues}). This is done in
order that astFormat and astUnformat should complement each other---so
that formatting a value and then un-formatting it will yield the
original value, subject to any rounding error.

To give a simple (but crucially incomplete!) example, consider reading
a value for the axis of a basic Frame, as follows:

\small
\begin{terminalv}
n = astUnformat( frame, iaxis, " 1.5e6   -99.0", &value );
\end{terminalv}
\normalsize

astUnformat will skip over the initial space in the string supplied
and then examine each successive character. It will accept the
sequence ``1.5e6'' as input, but reject the space which follows
because it does not form part of the format of a floating point
number. It will then convert the characters ``1.5e6'' into a
coordinate value and skip over the three spaces which follow them. The
returned function value will therefore be 9, equal to the total number
of characters consumed. This result may be used to address the string
during a subsequent read, so as to commence reading at the start of
``-99.0''.

Most importantly, however, note that if the user of a program
mistakenly enters the string ``~1.5r6\ldots'' instead of
``~1.5e6\ldots'', a coordinate value of 1.5 and a function result of 4
will be returned, because the ``r'' would prematurely terminate the
attempt to read the value. Because this sort of mistake does not
automatically result in an error but can produce incorrect results, it
is \textbf{vital} to check the returned function value to ensure that
the expected number of characters have been read.\footnote{Anyone who
seriously uses the C run time library ``scanf'' function will know
about the need for this check!}  For example, if the string is
expected to contain exactly one value, and nothing else, then the
following would suffice:

\small
\begin{terminalv}
n = astUnformat( frame, iaxis, string, &value );
if ( astOK ) {
   if ( string[ n ] || !n ) {
      <error in input data>
   } else {
      <value read correctly>
   }
}
\end{terminalv}
\normalsize

If astUnformat does not detect an error itself, we check that it has
read to the end-of-string and consumed at least one character (which
traps the case of a zero-length input string). If this reveals an
error, the value of ``n'' indicates where it occurred.

Another common requirement is to obtain a position by reading a list
of coordinates from a string which contains one value for each axis of
a Frame. We assume that the values are separated in some unambiguous
manner, perhaps using white space and/or some unspecified
single-character separator. The choice of separator is up to the data
supplier, who must choose it so as not to conflict with the format of
the coordinate values, but our software does not need to know what it
is. The following is a template algorithm for reading data in this
form:

\small
\begin{terminalv}
const char *s;
double values[ 10 ];

...

/* Initialise a string pointer. */
s = string;

/* Obtain the number of Frame axes and loop through them. */
naxes = astGetI( frame, "Naxes" );
for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {

/* Attempt to read a value for this axis. */
   n = astUnformat( frame, iaxis, s, &values[ iaxis - 1 ] );

/* If nothing was read and this is not the first axis or the
   end-of-string, try stepping over a separator and reading again. */
   if ( !n && ( iaxis > 1 ) && *s )
      n = astUnformat( frame, iaxis, ++s, &values[ iaxis - 1 ] );

/* Quit if nothing was read, otherwise move on to the next value. */
   if ( !n ) break;
   s += n;
}

/* Check for possible errors. */
if ( astOK ) {
   if ( *s || !n ) {
      <error in input data>
   } else {
      <values read correctly>
   }
}
\end{terminalv}
\normalsize

In this case, ``s'' will point to the location of any input error.

Note that this algorithm is insensitive to the precise format of the
data and will therefore work with any class of Frame and any
reasonably unambiguous input data. For example, here is a range of
suitable input data for a 3-dimensional basic Frame:

\small
\begin{terminalv}
1 2.5 3
3.1,3.2,3.3
1.5, 2.6, -9.9e2
-1.1+0.4-1.8
    .1/.2/.3
 44.0 ; 55.1 -14
\end{terminalv}
\normalsize

\subsection{\label{ss:permutingaxes}Permuting Frame Axes}

Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number
of axes it contains, but it is possible to change the order in which
these axes occur. To do so, an integer \emph{permutation array} is
filled with the numbers of the axes so as to specify the new order,
\emph{e.g.:}

\small
\begin{terminalv}
int perm[ 2 ] = { 2, 1 };
\end{terminalv}
\normalsize

In this case, the axes of a 2-dimensional Frame could be interchanged
by passing this permutation array to the \htmlref{astPermAxes}{astPermAxes} function. That
is, an ($x_1,x_2$) coordinate system would be changed into an
($x_2,x_1$) coordinate system by:

\small
\begin{terminalv}
astPermAxes( frame, perm );
\end{terminalv}
\normalsize

If the axes are permuted more than once, the effects are cumulative.
You are, of course, not restricted to Frames with only two axes.

\subsection{Selecting Frame Axes}

An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not
allowed, is to create a new Frame by selecting axes from an existing
one. The method of doing this is very similar to the way \htmlref{astPermAxes}{astPermAxes}
is used (\secref{ss:permutingaxes}), in that we supply an integer
array filled with the numbers of the axes we want, in their new
order. In this case, however, the number of array elements need not
equal the number of Frame axes.

For example, we could select axes 3 and 2 (in that order) from a
3-dimensional Frame as follows:

\small
\begin{terminalv}
astFrame *frame1, *frame2;
astMapping *mapping;
int pick[ 2 ] = { 3, 2 };

...

frame2 = astPickAxes( frame1, 2, pick, &mapping );
\end{terminalv}
\normalsize

This would return a pointer to a 2-dimensional Frame (``frame2'')
which contains the information associated with axes 3 and 2, in that
order, from the original Frame (``frame1''). The original Frame is not
altered by this process. Beware, however, that the axis information
may still be shared by both Frames, so if you wish to alter either of
them independently you may first need to use \htmlref{astCopy}{astCopy}
(\secref{ss:copyingobjects}) to make an independent copy.

In addition to the new Frame pointer, \htmlref{astPickAxes}{astPickAxes} will also return a
pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument (you may supply a
NULL pointer as an argument if you do not want this Mapping).  This
Mapping will inter-relate the two Frames. By this we mean that its
forward transformation will convert coordinates originally in the
coordinate system represented by ``frame1'' into that represented by
``frame2'', while its inverse transformation will convert in the
opposite direction. In this particular case, the Mapping would be a
\htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following
transformations:

\begin{terminalv}
Forward:
   (1, 2, 3) --> (3, 2)
   (2, 4, 6) --> (6, 4)
   (3, 6, 9) --> (9, 6)
   (4, 8, 12) --> (12, 8)
   (5, 10, 15) --> (15, 10)

Inverse:
   (3, 2) --> (<bad>, 2, 3)
   (6, 4) --> (<bad>, 4, 6)
   (9, 6) --> (<bad>, 6, 9)
   (12, 8) --> (<bad>, 8, 12)
   (15, 10) --> (<bad>, 10, 15)
\end{terminalv}

This is our first introduction to the idea of inter-relating pairs of
Frames \emph{via} a Mapping, but this will assume a central role later on.

Note that when using astPickAxes, it is also possible to request more
axes than there were in the original Frame. This will involve
selecting axes from the original Frame that do not exist. To do this,
the corresponding axis number (in the ``pick'' array) should be set to
zero and the effect is to introduce an additional new axis which is
not derived from the original Frame. This axis will have default
values for all its attributes. You will need to do this because
astPickAxes does not allow you to select any of the original axes more
than once.\footnote{It will probably not be obvious why this
restriction is necessary, but consider creating a Frame with one
longitude axis and two latitude axes. Which latitude axis should be
associated with the longitude axis?}

\subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets}
Some complementary
functions
are provided for use with Frames to allow you to perform geometric
operations without needing to know the nature of the coordinate system
represented by the \htmlref{Frame}{Frame}.

Functions
can be used to find the distance between two points, and to offset a
specified distance along a line joining two points, \emph{etc.} In essence,
these define the metric of the coordinate space which the Frame represents. In
the case of a basic Frame, this is a Cartesian metric.

The first of these functions, \htmlref{astDistance}{astDistance}, returns a double distance
value when supplied with the Frame coordinates of two points. For
example:

\small
\begin{terminalv}
double dist;
double point1[ 2 ] = { 0.0, 0.0 };
double point2[ 2 ] = { 1.0, 1.0 };

...

dist = astDistance( frame, point1, point2 );
\end{terminalv}
\normalsize

This calculates the distance between the origin (0,0) and a point at
position (1,1). In this case, the result, as you would expect, is
$\surd{2}$. However, this is only true for the Cartesian coordinate
system which a basic Frame represents. In general, astDistance will
calculate the geodesic distance between the two points, so that with a
more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial
sphere) a great-circle distance might be returned.

The \htmlref{astOffset}{astOffset} function is really the inverse of astDistance. Given two
points in a Frame, it calculates the coordinates of a third point
which is offset a specified distance away from the first point along
the geodesic joining it to the second one. For example:

\small
\begin{terminalv}
double point1[ 2 ] = { 0.0, 0.0 };
double point2[ 2 ] = { 1.0, 1.0 };
double point3[ 2 ];

...

astOffset( frame, point1. point2, 0.5, point3 );
\end{terminalv}
\normalsize

This would fill the ``point3'' array with the coordinates of a point
which is offset 0.5 units away from the origin (0,0) in the direction
of the position (1,1). Again, this is a simple result in a Cartesian
Frame, as varying the offset will trace out a straight line. On the
celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would
trace out a great circle.

The functions \htmlref{astAxDistance}{astAxDistance} and \htmlref{astAxOffset}{astAxOffset} are similar to astDistance
and astOffset, except that the curves which they use as ``straight
lines'' are not geodesics, but curves parallel to a specified axis\footnote
{For instance, a line of constant Declination is not a geodesic}. One
reason for using these functions is to deal with the cyclic ambiguity of
longitude and latitude axes.

The \htmlref{astOffset2}{astOffset2} function is similar to astOffset, but instead of using the
geodesic which passes through two positions, it uses the geodesic which
passes at a given position angle through the starting position.

Position angles are always measured from the positive direction of the
second Frame axis to the required line, with positive angles being in the
same sense as rotation from the positive direction of the second axis to
the positive direction of the first Frame axis. This definition applies
to all classes of Frame, including SkyFrame. The default ordering of axes
in a SkyFrame makes the second axis equivalent to north, and so the
definition of position angle given above corresponds to the normal
astronomical usage, ``from north, through east''. However, it should be
remembered that it is possible to permute the axes of a SkyFrame (or
indeed any Frame), so that north becomes axis 1. In this case, an AST
``position angle'' would be the angle ``from east, through north''.
Always take the axis ordering into account when deriving an astronomical
position angle from an AST position angle.

Within a Cartesian coordinate system, the position angle of a geodesic
(\emph{i.e.}\ a straight line) is constant along its entire length, but
this is not necessarily true of other coordinate systems. Within a
spherical coordinate system, for instance, the position angle of a geodesic
will vary along its length (except for the special cases of a meridian and
the equator). In addition to returning the required offset position, the
astOffset2 function
returns the position angle of the geodesic at the
offset position. This is useful if you want to trace out a path which
involves turning through specified angles. For instance, tracing out a
rectangle in which each side is a geodesic involves turning through 90
degrees at the corners. To do this, use astOffset2 to calculate the
position of each corner, and then add (or subtract) 90 degrees from the
position angle returned by astOffset2.

The \htmlref{astAngle}{astAngle} function
calculates the angle subtended by two points, at a third point.
If used with a 2-dimensional Frame the returned angle
is signed to indicate the sense of rotation (clockwise or anti-clockwise)
in taking the ``shortest route'' from the first point to the second.
If the Frame has more than 2 axes, the result is un-signed and is always
in the range zero to $\pi$.

The \htmlref{astAxAngle}{astAxAngle} function is similar to astAngle,
but the ``reference direction'', from which angles are measured, is
a specified axis.

The \htmlref{astResolve}{astResolve} function
resolves a given displacement within a Frame into two components, parallel and
perpendicular to a given reference direction.

The displacement is specified by two positions within the Frame; the
starting and ending positions. The reference direction is defined by the
geodesic curve passing through the starting position and a third specified
position. The lengths of the two components are returned, together with
the position on the reference geodesic which is closest to the third
supplied point.

\subsection{\label{ss:framedomains}The Domain Attribute}

The \htmlref{Domain}{Domain} attribute is one of the most important properties of a
\htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little
subtle.  We will introduce it here, but its true value will probably
not become apparent until later (\secref{ss:framesetconverting}).

To understand the need for the Domain attribute, consider using
different Frames to represent the following different coordinate
systems associated with a CCD image:

\begin{enumerate}
\item A coordinate system based on pixel numbers.

\item Positions on the CCD chip, measured in $\mu$m.

\item Positions in the focal plane of the telescope, measured in mm.

\item A celestial coordinate system, measured in radians.
\end{enumerate}

If we had two such CCD images, we might legitimately want to align
them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based
on pixel numbers) in order to, say, divide by a flat-field exposure.
We might similarly consider aligning them using any of the other
coordinate systems so as to achieve different results. For example, we
might consider merging separate images from a CCD mosaic by using
focal plane positions.

It would obviously not be legitimate, however, to directly compare
positions in one image measured in pixels with positions in the other
measured in mm, nor to equate chip positions in $\mu$m with sky
coordinates in radians. If we wanted to inter-compare these
coordinates, we would need to do it indirectly, using other
information based on the experimental set-up. For instance, we might
need to know the size of the pixels expressed in mm and the
orientation of the CCD chip in the focal plane.

Note that it is not simply the difference in physical units which
prevents certain coordinates from being directly inter-compared
(because the appropriate unit scaling factors could be included
without any additional information). Neither is it the fact that
different coordinate systems are in use (because we could legitimately
inter-compare two different celestial coordinate systems without any
extra information).  Instead, it is the different nature of the
coordinate spaces to which these coordinate systems have been applied.

We normally express this by saying that the coordinate systems apply
to different \emph{physical domains}. Although we may establish
\emph{ad hoc} relationships between coordinates in different physical
domains, they are not intrinsically related to each other and we need
to supply extra information before we can convert coordinates between
them.

In AST, the role of the (character string) Domain attribute is to
assign Frames to their respective physical domains. The way it
operates is as follows:

\begin{itemize}
\item Coordinate systems which apply to the same physical domain
(\emph{i.e.}\ whose Frames have the same Domain value) can be directly
inter-compared.

If the domain has several coordinate systems associated with it
(\emph{e.g.}\ the celestial sphere), then a coordinate conversion may
be involved. Otherwise, coordinate values may simply be equated.

\item Coordinate systems which apply to different physical domains
(\emph{i.e.}\ whose Frames have different Domain values) cannot be
directly inter-compared.

If any relationship does exist between such coordinate systems---and
it need not---then additional information must be supplied in order to
establish the relationship between them in any particular case. We
will see later (\secref{ss:framesets}) how to establish such
relationships between Frames in different domains.
\end{itemize}

With the basic Frames we are considering here, each physical domain only
has a single (Cartesian) coordinate system associated with it, so that if
two such Frames have the same Domain value, their coordinate systems will
be identical and may simply be equated. With more specialised Frames,
however, more than one coordinate system may apply to each domain. In
such cases, a coordinate conversion may need to be performed.

When a basic Frame is created, its Domain attribute defaults to an
empty string. This means that all such Frames belong to the same
(null) domain by default and therefore describe the same unspecified
physical coordinate space. In order to assign a Frame to a different
domain, you simply need to set its Domain value. This is normally most
conveniently done when it is created, as follows:

\small
\begin{terminalv}
frame1 = astFrame( 2, "Domain=CCD_CHIP,"
                      "Unit(1)=micron,"
                      "Unit(2)=micron" );
frame2 = astFrame( 2, "Domain=FOCAL_PLANE,"
                      "Unit(1)=mm,"
                      "Unit(2)=mm" );
\end{terminalv}
\normalsize

Here, we have created two Frames in different physical
domains. Although their coordinate values all have units of length,
they cannot be directly inter-compared (because their axes may be
rotated with respect to each other, for instance).

All Domain values are automatically converted to upper case and white
space is removed, but there are no other restrictions on the names you
may use to label different physical domains. From a practical point of
view, however, it is worth following a few conventions
(\secref{ss:domainconventions}).

\subsection{\label{ss:domainconventions}Conventions for Domain Names}

When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it
obviously makes sense to avoid generic names which might clash with
those used for similar (but subtly different!) purposes by other
programmers. If you are developing software for an instrument, for
example, and want to identify an instrumental coordinate system, then
it is sensible to add a distinguishing prefix. For instance, you might
use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an
acronym) identifies your instrument.

For some purposes, however, a standard choice of Domain name is
desirable so that different items of software can communicate. For
this purpose, the following Domain names are reserved by AST and the
use recommended below should be carefully observed:

\begin{quote}
\begin{description}
\item[GRAPHICS]\mbox{}\\
Identifies the coordinate space used by an underlying computer
graphics system to specify plotting operations. Typically, when
performing graphical operations, AST is used to define additional
coordinate systems which are related to these ``native'' graphical
coordinates.  Plotting may be carried out in any of these coordinate
systems, but the GRAPHICS domain identifies the native coordinates
through which AST communicates with the underlying graphics system.

\item[GRID]\mbox{}\\
Identifies the instantaneous \emph{data grid} used to store and handle
data, together with an associated coordinate system. In this
coordinate system, the first element stored in an array of data always
has a coordinate value of unity at its centre and all elements have
unit extent. This applies to all dimensions.

If data are copied or transformed to a new data grid (by whatever
means), or a subset of the original grid is extracted, then the same
rules apply to the copy or subset. Its first element therefore has
GRID coordinate values of unity at its centre. Note that this means
that GRID coordinates remain attached to the first element of the data
grid and not to its data content (\emph{e.g.}\ the features in an
image).

\item[PIXEL]\mbox{}\\
Identifies an array of pixels and an associated \emph{pixel-based}
coordinate system which is related to the GRID coordinate system
(above) simply by a shift of origin along each axis. This shift may be
integral, fractional, positive, negative or zero. The data elements
retain their unit extent along each axis.

Because the amount of shift is unspecified, the PIXEL domain is
distinct from the GRID domain. The relationship between them contains
a degree of uncertainty, such as typically arises from the different
conventions used by different software systems. For instance, in some
software the first pixel is regarded as being centred at (1,1), while
in other software it is at (0.5,0.5). In addition, some software
packages implement a ``pixel origin'' which allows pixel coordinates
to start at an arbitrary value.

The GRID domain (which corresponds with the pixel-numbering convention
used by FITS) is a special case of the PIXEL domain and avoids this
uncertainty. In general, additional information is required in order
to convert from one to the other.

\item[SKY]\mbox{}\\
Identifies the domain which contains all equivalent celestial
coordinate systems. Because these are represented in AST by SkyFrames
(\secref{ss:skyframes}), it should be no surprise that the default
Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you
probably won't need to change this very often.

\item[SPECTRUM]\mbox{}\\
Identifies the domain used to describe positions within an
electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes})
class describes positions within this domain, allowing a wide range of
different coordinate systems to be used (frequency, wavelength,
\emph{etc}). The default Domain value for a SpecFrame is SPECTRUM.

\item[TIME]\mbox{}\\
Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame}
class describes positions within this domain, allowing a wide range of
different coordinate systems and timescales to be used. The default Domain
value for a TimeFrame is TIME.

\end{description}
\end{quote}

Although we have drawn a necessary distinction here between the GRID
and PIXEL domains, we will continue to refer in general terms to image
``pixels'' and ``pixel coordinates'' whenever this distinction is not
important. This should not be taken to imply that the GRID convention
for numbering pixels is excluded---in fact, it is usually to be
preferred (at the level of data handling being discussed in this
document) and we recommend it.

\subsection{\label{ss:frameunits}The Unit Attribute}
Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used
to describe positions on the axis. The index of the axis to which the
attribute refers should normally be placed in parentheses following the
attribute name (``Unit(2)'' for instance). However, if the Frame has only
a single axis, then the axis index can be omitted.

In versions of AST prior to version 2.0, the Unit attribute was nothing
more than a descriptive string intended purely for human readers---no
part of the AST system used the Unit string for any purpose (other than
inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no
account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between
two Frames. Thus if the conversion between a pair of 1-dimensional Frames
representing velocity was found (using
\htmlref{astConvert}{astConvert}
) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit
attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is
referred to below as a \emph{passive} Unit attribute.

As of AST version 2.0, a facility exists which allows the Unit attribute
to be \emph{active}; that is, differences in the
Unit attribute may be taken into account when finding the Mapping between
two Frames. In order to minimise the risk of breaking older software, the
\emph{default} behaviour of simple Frames and SkyFrames is unchanged from
previous versions (\emph{i.e.} they have passive Unit attributes). However,
the new
functions \htmlref{astSetActiveUnit}{astSetActiveUnit} and \htmlref{astGetActiveUnit}{astGetActiveUnit}
allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame}
classes \emph{always} have an active Unit attribute (attempts to change this
are ignored).

For instance, consider the above example of two 1-dimensional Frames
describing velocity. These Frames can be created as follows:

\small
\begin{terminalv}
AstFrame *frame1, *frame2;
frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" );
frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" );
\end{terminalv}
\normalsize

By default, these Frames have passive Unit attributes, and so an attempt
to find a Mapping between them would ignore the difference in their Unit
attributes and return a unit Mapping. To avoid this, we indicate that we
want these Frames to have \emph{active} Unit attributes, as follows:

\small
\begin{terminalv}
astSetActiveUnit( frame1, 1 );
astSetActiveUnit( frame2, 1 );
\end{terminalv}
\normalsize

If we then find the Mapping between them as follows:

\small
\begin{terminalv}
AstFrameSet *cvt;
...
cvt = astConvert( frame1, frame2, "" );
\end{terminalv}
\normalsize

the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by
astConvert
will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a
velocity in $km/h$) by a factor of 0.278 to create its output (a velocity
in $m/s$).

In fact we need not have set the Unit attribute active in ``frame1''
since the behaviour of astConvert is determined by its ``to'' Frame
(the second Frame parameter).

\subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings}
Conversion between units systems relies on the use of a specific syntax
for the Unit attribute. If the value of the Unit attribute does not
conform to this syntax, then an error will be reported if an attempt is
made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen
if the Unit attribute is \emph{passive}).

The adopted syntax is that described in FITS-WCS paper I "Representation
of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish
here between ``basic'' units and ``derived'' units: derived units are
defined in terms of other units (either derived or basic), whereas basic
units have no such definitions. Derived units may be represented by their
own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a
\emph{mathematical expression} which combines other symbols and constants
to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per
second). Unit symbols may be prefixed by a string representing a standard
multiple or sub-multiple.

In addition to the unit symbols listed in FITS-WCS Paper I, any other
arbitrary unit symbol may be used, with the proviso that it will not be
possible to convert between Frames using such units. The exception to
this is if both Frames refer to the same unknown unit string. For instance,
an axis with unknown unit symbol "flop" \emph{could} be converted to an axis
with  unit "Mflop" (Mega-flop).

Unit symbols (optionally prefixed with a multiple or sub-multiple) can be
combined together using a limited range of mathematical operators and
functions, to produce new units. Such expressions may also contain
parentheses and numerical constants (these may optionally use
``scientific'' notation including an ``E'' character to represent the
power of 10).

The following tables list the symbols for the basic and derived units which
may be included in a units string, the standard prefixes for multiples
and sub-multiples, and the strings which may be used to represent
mathematical operators and functions.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{{\large Basic units}} \\ \hline
\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} &
\multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline
length              & m   & metre \\
mass                & g   & gram \\
time                & s   & second \\
plane angle         & rad & radian \\
solid angle         & sr  & steradian \\
temperature         & K   & Kelvin \\
electric current    & A   & Ampere \\
amount of substance & mol & mole \\
luminous intensity  & cd  & candela \\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{small}
\begin{tabular}{|l|l|l|l|}
\hline
\multicolumn{4}{|c|}{{\large Derived units}} \\ \hline
\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} &
\multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline
area & barn & barn & 1.0E-28 m**2 \\
area & pix & pixel & \\
area & pixel & pixel & \\
electric capacitance & F & Farad & C/V \\
electric charge & C & Coulomb & A s \\
electric conductance & S & Siemens & A/V \\
electric potential & V & Volt & J/C \\
electric resistance & Ohm & Ohm & V/A \\
energy & J & Joule & N m \\
energy & Ry & Rydberg & 13.605692 eV \\
energy & eV & electron-Volt & 1.60217733E-19 J \\
energy & erg & erg & 1.0E-7 J \\
events & count & count & \\
events & ct & count & \\
events & ph & photon & \\
events & photon & photon & \\
flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\
flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\
flux density & mag & magnitude & \\
force & N & Newton & kg m/s**2 \\
frequency & Hz & Hertz & 1/s \\
illuminance & lx & lux & lm/m**2 \\
inductance & H & Henry & Wb/A \\
length & AU & astronomical unit & 1.49598E11 m \\
length & Angstrom & Angstrom & 1.0E-10 m \\
length & lyr & light year & 9.460730E15 m \\
length & pc & parsec & 3.0867E16 m \\
length & solRad & solar radius & 6.9599E8 m \\
luminosity & solLum & solar luminosity & 3.8268E26 W \\
luminous flux & lm & lumen & cd sr \\
magnetic field & G & Gauss & 1.0E-4 T \\
magnetic flux & Wb & Weber & V s \\
mass & solMass & solar mass & 1.9891E30 kg \\
mass & u & unified atomic mass unit & 1.6605387E-27 kg \\
magnetic flux density & T & Tesla & Wb/m**2 \\
plane angle  & arcmin & arc-minute & 1/60 deg \\
plane angle  & arcsec & arc-second & 1/3600 deg \\
plane angle  & mas & milli-arcsecond & 1/3600000 deg \\
plane angle & deg & degree & pi/180 rad \\
power & W & Watt & J/s \\
pressure, stress & Pa & Pascal & N/m**2 \\
time  & a & year & 31557600 s \\
time  & d & day & 86400 s \\
time  & h & hour & 3600 s \\
time  & yr & year & 31557600 s \\
time  & min & minute & 60 s \\
      & D & Debye & 1.0E-29/3 C.m \\
\hline
\end{tabular}
\end{small}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|lll|lll|}
\hline
\multicolumn{6}{|c|}{{\large Prefixes for multiples \&
sub-multiples}} \\ \hline
\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} &
\multicolumn{1}{c|}{Prefix} &
\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} &
\multicolumn{1}{c|}{Prefix} \\ \hline
$10^{-1}$ & deci & d & $10$ & deca & da \\
$10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\
$10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\
$10^{-6}$ & micro & u & $10^{6}$ & mega & M \\
$10^{-9}$ & nano & n & $10^{9}$ & giga & G \\
$10^{-12}$ & pico & p & $10^{12}$ & tera & T \\
$10^{-15}$ & femto & f & $10^{15}$ & peta & P \\
$10^{-18}$ & atto & a & $10^{18}$ & exa & E \\
$10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\
$10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\
\hline
\multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline
sym1 sym2           & multiplication (a space) \\
sym1*sym2           & multiplication (an asterisk) \\
sym1.sym2           & multiplication (a dot) \\
sym1/sym2           & division \\
sym1**y             & exponentiation ($y$ must be a numerical constant)\\
sym1\verb+^+y       & exponentiation ($y$ must be a numerical constant)\\
log(sym1)           & common logarithm \\
ln(sym1)            & natural logarithm \\
exp(sym1)           & exponential \\
sqrt(sym1)          & square root \\
\hline
\end{tabular}
\end{center}
\end{table}

\subsubsection{Side-effects of Changing the Unit attribute}
If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by
setting a new value or by clearing it so that the default value is
re-instated) may cause the Label and Symbol attributes to be changed
accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'',
``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)''
will cause AST to change its Label and Symbol to ``log(Frequency)'' and
``Log(nu)''. These changes are only made if the Unit attribute is active,
and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other
 hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change
to the Label or Symbol attributes.

\cleardoublepage
\section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)}

A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on
the celestial sphere is obviously of great importance in
astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine
the additional properties and behaviour of a SkyFrame that distinguish
it from a basic Frame (\secref{ss:frames}).

\subsection{The SkyFrame Model}

A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
behaviour of these two ancestral classes.  When used as a Mapping, a
SkyFrame implements a unit transformation, exactly like a basic Frame
(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
behaviour is not of great importance.

When used as a Frame, however, a SkyFrame represents a 2-dimensional
\emph{spherical} coordinate system, in which the shortest distance
between two points is a great circle.  A SkyFrame therefore always has
exactly two axes which represent the longitude and latitude of a
coordinate system residing on the celestial sphere. Many such
coordinate systems can be represented by a SkyFrame, as we will see
shortly.

A SkyFrame can represent any of the commonly used celestial coordinate
systems. Optionally, the origin of the longitude/latitude system can be
moved to any specified point in the standard celestial system, allowing
a SkyFrame to represent offsets from a specified sky position.

When it is first created, a SkyFrame's axes are always in the order
(longitude,~latitude) but this can be changed, if required, by using the
\htmlref{astPermAxes}{astPermAxes} function (\secref{ss:permutingaxes}). The order of the axes
can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A
SkyFrame's coordinate values are always stored as angles in (double
precision) radians, regardless of the setting of the Unit attribute
\footnote{The units used for the internal floating-point representation of an
axis value can be determined by examining the InternalUnit attribute of
the Frame. For most Frames, the Unit and InternalUnit attributes will be
equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}.

\subsection{Creating a SkyFrame}

The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a
SkyFrame with default attributes is created as follows:

\small
\begin{terminalv}
#include "ast.h"
AstSkyFrame *skyframe;

...

skyframe = astSkyFrame( "" );
\end{terminalv}
\normalsize

Such a SkyFrame would represent the default celestial coordinate
system which, at present, is the ICRS system (the default was "FK5(J2000)"
in versions of AST prior to 3.0).

\subsection{Specifying a Particular Celestial Coordinate System}

For many purposes, the ICRS coordinate system is perfectly
adequate. In order to support conversion between a variety of
celestial coordinate systems, however, you can create SkyFrames that
represent any of these.

Selection of a particular coordinate system is performed simply by
setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System}
attribute. This setting is most conveniently done when the SkyFrame is
created. For example, a SkyFrame representing the old FK4~(B1950.0)
coordinate system would be created by:

\small
\begin{terminalv}
skyframe = astSkyFrame( "System=FK4" );
\end{terminalv}
\normalsize

Note that specifying ``System$=$FK4'' also changes the associated
equinox (from J2000.0 to B1950.0). This is because the default value
of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends
on the System attribute setting.

You may change the System value at any time, although this is not
usually needed.  The values supported are set out in the attribute's
description in \appref{ss:attributedescriptions} and include a variety
of equatorial coordinate systems, together with ecliptic and galactic
coordinates.

General spherical coordinates are supported by specifying
``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be
created to convert between ``unknown'' coordinates and any of the other
celestial coordinate systems (see \secref{ss:introducingconversion} ).

\subsection{Attributes which Qualify Celestial Coordinate Systems}

Many celestial coordinate systems have some additional free parameters
which serve to identify a particular coordinate system from amongst a
broader class of related coordinate systems. For example, the
FK5~(J2010.0) system is distinguished from the FK5~(J2000.0)
system by a different equinox---and the coordinates of a fixed
astronomical source would have different values when expressed in
these two systems.

In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame}
attributes, each of which has a default appropriate to
(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System}
attribute. Each of these \emph{qualifying attributes} may, however, be
assigned an explicit value so as to select a particular coordinate
system. Note, it is usually best to assign explicit
values whenever possible rather than relying on defaults. Attribute
should only be left at their default value if you ``don't care'' what
value is used. In certain circumstances (particularly, when aligning two
Frames), a default value for an attribute may be replaced by the value
from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
assigning an explicit value to the attribute, rather than simply relying on
the default.


The main SkyFrame attributes which qualify the System attribute are:

\begin{quote}
\begin{description}

\item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\
This attribute is inherited from the Frame class. It gives the moment in
time when the coordinates are correct for the astronomical source
under study (usually the date of observation).

\item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\
This value is used to qualify celestial coordinate systems that are
notionally based on the Earth's equator and/or the ecliptic (the plane
of the Earth's orbit around the Sun). The position of either of these
planes is difficult to specify precisely, so in practice a model
\emph{mean} equator and/or ecliptic are used instead. These, together
with the point on the sky that defines the coordinate origin (termed
the \emph{mean equinox}) move with time according to some model which
smoothes out the more rapid fluctuations. The SkyFrame class supports
both the old FK4 model and the newer FK5 one.

Coordinates expressed in any of these systems vary with time due to
movement (by definition) of the coordinate system itself, and must
therefore be qualified by a moment in time (the \emph{epoch of the mean
equinox}, or ``equinox'' for short) which specifies the position of
the model coordinate system on the sky. This is the role of the
Equinox attribute.

Note that it is quite valid and common to relate the position of a
source to an equinox other than the date of observation. Usually a
standard equinox such as J2000.0 is used, meaning that the coordinates
are referred to axes defined by where the model mean equator and
ecliptic would lie on the sky at the Julian epoch J2000.0.
\end{description}
\end{quote}

For further details of these attributes you should consult their
descriptions in \appref{ss:attributedescriptions} and for details of
the System settings for which they are relevant, see the description
of the System attribute (also in \appref{ss:attributedescriptions}).
For the interested reader, an excellent overview of celestial
coordinate systems can also be found in the documentation for the
SLALIB library (\xref{SUN/67}{sun67}{}).

The value of these qualifying attributes is most conveniently set at
the same time as the System value, \emph{e.g.}\ when a SkyFrame is
created. For instance:

\small
\begin{terminalv}
skyframe = astSkyFrame( "System=Ecliptic, Equinox=J2005.5" );
\end{terminalv}
\normalsize

would create a SkyFrame representing an ecliptic coordinate system
referred to the mean equinox and ecliptic of Julian epoch J2005.5.

Note that it does no harm to assign values to qualifying attributes
which are not relevant to the main System value. Any such values are
stored, but are not used unless the System value is later set so that
they become relevant.

\subsection{Using Default SkyFrame Attributes}

The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend
on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this
means that there is usually little need to specify many of these
attributes explicitly unless you have some special requirement. This
can be illustrated by using \htmlref{astShow}{astShow} to examine a SkyFrame, as follows:

\small
\begin{terminalv}
astShow( astSkyFrame( "System=FK4-NO-E, Epoch=1958" ) );
\end{terminalv}
\normalsize

The output from this might look like the following:

\begin{terminalv}
 Begin SkyFrame         # Description of celestial coordinate system
#   Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0;
epoch B1958.0"   # Title of coordinate system
    Naxes = 2   # Number of coordinate axes
#   Domain = "SKY"      # Coordinate system domain
    Epoch = 1958        # Besselian epoch of observation
#   Lbl1 = "Right ascension"    # Label for axis 1
#   Lbl2 = "Declination"        # Label for axis 2
    System = "FK4-NO-E"         # Coordinate system type
#   Uni1 = "hh:mm:ss.s"         # Units for axis 1
#   Uni2 = "ddd:mm:ss"  # Units for axis 2
#   Dir1 = 0    # Plot axis 1 in reverse direction
#   Bot2 = -1.5707963267949     # Lowest legal axis value
#   Top2 = 1.5707963267949      # Highest legal axis value
    Ax1 =       # Axis number 1
       Begin SkyAxis    # Celestial coordinate axis
       End SkyAxis
    Ax2 =       # Axis number 2
       Begin SkyAxis    # Celestial coordinate axis
       End SkyAxis
 IsA Frame      # Coordinate system description
#   Eqnox = 1950        # Besselian epoch of mean equinox
 End SkyFrame
\end{terminalv}

Note that the defaults (indicated by the ``\verb?#?'' comment
character at the start of the line) for attributes such as the \htmlref{Title}{Title},
axis Labels and Format specifiers are all set to values appropriate
for the particular equatorial coordinate system that the SkyFrame
represents.

This means, for example, that if we were to use this SkyFrame to
format a right ascension value stored in radians using \htmlref{astFormat}{astFormat}
(\secref{ss:formattingaxisvalues}), it would automatically result in a
string in sexagesimal notation (such as ``12:14:35.7'') suitable for
display.  If we changed the value of the SkyFrame's Digits attribute
(which is inherited from the \htmlref{Frame}{Frame} class), the number of digits
appearing would also change accordingly.

These choices would be appropriate for a System value of ``FK4-NO-E'',
but if a different System value were set, the defaults would be
correspondingly different. For example, ecliptic longitude is
traditionally expressed in degrees, so setting ``System=ecliptic''
would result in coordinate values being formatted as degrees by
default.

Of course, if you do not like any of these defaults, you may always
over-ride them by setting explicit attribute values yourself.

\subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates}

SkyFrames use \htmlref{astFormat}{astFormat} for formatting coordinate values in the same
way as other Frames (\secref{ss:formattingaxisvalues}). However, they
offer a different set of formatting options more appropriate to
celestial coordinates.

The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way
as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the
precision with which celestial coordinates are displayed can also be
adjusted in this way. However, the range of format specifiers that can
be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format
resulting from any particular Digits value, is different.

The syntax of SkyFrame format specifiers is detailed under the
description of the Format(axis) attribute in
\appref{ss:attributedescriptions}.  Briefly, however, it allows
celestial coordinates to be expressed either as angles or times and to
include one or more of the fields:

\begin{quote}
\begin{itemize}
\item degrees or hours
\item arc-minutes or minutes
\item arc-seconds or seconds
\end{itemize}
\end{quote}

with a specified number of decimal places for the final field. A range
of field separators is also available, as the following examples show:

\begin{quote}
\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Format Specifier} & \textbf{Example Formatted Value}\\
\hline \hline
{\tt{d}} & {\tt{219}}\\
{\tt{d.3}} & {\tt{219.123}}\\
{\tt{dm}} & {\tt{219:05}}\\
{\tt{dm.2}} & {\tt{219:05.44}}\\
{\tt{dms}} & {\tt{219:05:42}}\\
{\tt{hms.1}} & {\tt{15:44:13.8}}\\
{\tt{bdms.2}} & {\tt{219 05 42.81}}\\
{\tt{lhms.3}} & {\tt{15h44m13.88s}}\\
{\tt{+zlhms}} & {\tt{+06h10m44s}}\\
{\tt{ms.1}} & {\tt{13145:42.8}}\\
{\tt{lmst.3}} & {\tt{876m22.854s}}\\
{\tt{s.2}} & {\tt{788742.81}}\\
\hline
\end{tabular}
\end{center}
\end{quote}

Note the following key points:

\begin{itemize}
\item The required fields are specified using characters chosen from
either ``dms'' or ``hms'' according to whether the value is to be
formatted as an angle (in degrees) or a time (in hours).

\item If no degrees or hours field is required, the distinction
between angle and time may be made by including ``t'' to request time.

\item The number of decimal places (for the final field) is indicated
using ``\texttt{.}'' followed by an integer. An asterisk can be used in
place of an integer, in which case the number of decimal places is
chosen so that the total number of digits in the formatted value is equal
to the value of the Digits attribute.

\item ``b'' causes fields to be separated by blanks, while ``l''
causes them to be separated by the appropriate letters (the default
being a colon).

\item ``z'' causes padding with leading zeros.

\item ``+'' cause a plus sign to be prefixed to positive values
(negative values always have a minus sign).
\end{itemize}

The formatting performed by a SkyFrame is also influenced by the
\htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each
SkyFrame axis.  It determines whether the default format specifier for
an axis will present values as angles (\emph{e.g.}\ in degrees) if it
is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero.

The default AsTime value depends on the celestial coordinate system
which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System}
attribute value. For example, equatorial longitude values (right
ascension) are normally expressed in hours, whereas ecliptic
longitudes are normally expressed in degrees, so their default AsTime
values will reflect this difference.

The value of the AsTime attribute may be set explicitly to over-ride
these defaults if required, with the formatting precision being
determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the
Format(axis) attribute may be set explicitly to specify both the
format and precision required. Setting an explicit Format value always
over-rides the effects of both the Digits and AsTime attributes (unless
the Format value does not specify the required number of decimal places,
in which case Digits is used to determine the default number of decimal
places)

\subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates}

The process of converting formatted celestial coordinates, such as
might be produced by the \htmlref{astFormat}{astFormat} function
(\secref{ss:formattingskyaxisvalues}), into numerical (double)
coordinate values is performed by using \htmlref{astUnformat}{astUnformat}
(\secref{ss:unformattingaxisvalues}) and passing it a pointer to a
\htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats
accepted is appropriate to positions on the sky expressed as angles
and/or times, while the returned value is in radians.

The following describes the forms of celestial coordinate which are
supported:

\begin{itemize}
\item You may supply an optional sign, followed by between one and
three fields representing either degrees, arc-minutes, arc-seconds or
hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03'').

\item Each field should consist of a sequence of one or more digits,
which may include leading zeros. At most one field may contain a
decimal point, in which case it is taken to be the final field
(\emph{e.g.}\ decimal degrees might be given as ``124.707'', while
degrees and decimal arc-minutes might be given as ``$-$13~33.8'').

\item The first field given may take any value, allowing angles and
times outside the conventional ranges to be represented. However,
subsequent fields must have values of less than 60 (\emph{e.g.}
``720~45~31'' is valid, whereas ``11~45~61'' is not).

\item Fields may be separated by white space or by ``:'' (colon), but
the choice of separator must be used consistently throughout the
value. Additional white space may be present around fields and
separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1'').

\item The following field identification characters may be used as
separators to replace those above (or may be appended to the final
field), in order to identify the field to which they are appended:

\begin{quote}
\begin{tabular}{lll}
d & -- & degrees \\
h & -- & hours \\
m & -- & minutes (of arc or time) \\
s & -- & seconds (of arc or time) \\
\texttt{'} & -- & arc-minutes \\
\texttt{"} & -- & arc-seconds
\end{tabular}
\end{quote}

Either lower or upper case may be used.  Fields must be given in order
of decreasing significance
(\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s'').

\item The presence of certain field identification characters
indicates whether the value is to be interpreted as an angle or a time
(with 24 hours corresponding to 360 degrees), as follows:

\begin{quote}
\begin{tabular}{lll}
d & -- & angle \\
\texttt{'} & -- & angle \\
\texttt{"} & -- & angle \\
h & -- & time
\end{tabular}
\end{quote}

Incompatible angle/time identification characters may not be mixed
(\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid).  The remaining
field identification characters and separators do not specify a
preference for an angle or a time and may be used with either.

\item If no preference for an angle or a time is expressed anywhere
within the value, then it is interpreted as an angle if the Format
attribute string associated with the SkyFrame axis generates an angle
and as a time otherwise.  This ensures that values produced by
astFormat (\secref{ss:formattingskyaxisvalues}) are correctly
interpreted by astUnformat.

\item Fields may be omitted, in which case they default to zero. The
remaining fields may be identified by using appropriate field
identification characters (see above) and/or by adding extra colon
separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field
is not identified explicitly, it is assumed that adjacent fields have
been given, after taking account of any extra separator
characters. For example:

\begin{quote}
\begin{tabular}{lll}
10d & -- & degrees \\
10d12 & -- & degrees and arc-minutes \\
11:14\texttt{"} & -- & arc-minutes and arc-seconds \\
9h13s & -- & hours and seconds of time \\
:45:33 & -- & minutes and seconds (of arc or time) \\
:55: & -- & minutes (of arc or time) \\
::13 & -- & seconds (of arc or time) \\
$-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\
07m14 & -- & minutes and seconds (of arc or time) \\
$-$8:14\texttt{'} & -- & degrees and arc-minutes \\
$-$h3:14 & -- & minutes and seconds of time \\
h:2.1 & -- & seconds of time
\end{tabular}
\end{quote}

\item If fields are omitted in such a way that the remaining ones
cannot be identified uniquely (e.g. ``01:02''), then the first field
(either given explicitly or implied by an extra leading colon
separator) is taken to be the most significant field that astFormat
would produce when formatting a value (using the Format attribute
associated with the SkyFrame axis). By default, this means that the
first field will normally be interpreted as degrees or hours. However,
if this does not result in consistent field identification, then the
last field (either given explicitly or implied by an extra trailing
colon separator) is taken to to be the least significant field that
astFormat would produce.

\end{itemize}

This final convention is intended to ensure that values formatted by
astFormat which contain less than three fields will be correctly
interpreted if read back using astUnformat, even if they do not
contain field identification characters.  However, it also affects
other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set
to ``mst.1'' (producing two fields representing minutes and seconds of
time), then formatted input would be interpreted by astUnformat as
follows:

\begin{quote}
\begin{tabular}{lll}
12 13 & -- & minutes and seconds \\
12 & -- & minutes \\
:13 & -- & seconds \\
$-$18: & -- & minutes \\
12.8 & -- & minutes \\
1 2 3 & -- & hours, minutes and seconds \\
& & \\
4\texttt{'} & -- & arc-minutes \\
60::\texttt{"} & -- & degrees \\
$-$23:\texttt{"} & -- & arc-minutes \\
$-$33h & -- & hours
\end{tabular}
\end{quote}

(in the last four cases, explicit field identification has been given
which overrides the implicit identification).

Alternatively, if the Format(axis) string were set to ``s.3''
(producing only an arc-seconds field), then formatted input would be
interpreted by astUnformat as follows:

\begin{quote}
\begin{tabular}{lll}
12.8 & -- & arc-seconds \\
12 13 & -- & arc-minutes and arc-seconds \\
:12 & -- & arc-seconds \\
13: & -- & arc-minutes \\
1 2 3 & -- & degrees, arc-minutes and arc-seconds
\end{tabular}
\end{quote}

In general, if you are preparing formatted input data containing
celestial coordinates and wish to omit certain fields, then you are
advised to identify clearly those that you do provide by using the
appropriate field identification characters and/or extra colon
separators. This prevents you depending on the implicit field
identification described above which, in turn, depends on an
appropriate Format(axis) string having been set.

When writing software, it is also a good idea to set the Format(axis)
string so that data input will be as simple as possible for the
user. Unless some special effect is desired, this normally means that
it should contain ``d'' or ``h'' to ensure that the first field
entered by the user will be interpreted as degrees or hours, unless
otherwise identified. This is the normal behaviour unless an explicit
Format(axis) value has been set to override the default.

\subsection{Representing Offsets from a Specified Sky Position}
A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are
referred to an origin at any specified sky position. Such a coordinate
system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System}
attribute should be set to represent the celestial coordinate system in
which the origin is to be specified. Then the SkyRef attribute should be
set to hold the coordinates of the origin within the selected celestial
coordinate system.

By default, ``north'' in the new offset coordinate system is parallel to
north in the original celestial coordinate system. However, the direction
of north in the offset system can be controlled by assigning a value to
the SkyRefP attribute. This attribute should be assigned the celestial
coordinates of a point which is on the zero longitude meridian and which
has non-zero latitude.

By default, the position given by the SkyRef attribute is used as the
origin of the new longitude/latitude system, but an option exists to use
it as the north pole of the system instead. This option is controlled by
the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what
sort of offset coordinate system you want. Setting SkyRefIs to
``Origin'' (the default) produces an offset coordinate system which is
approximately Cartesian close to the specified position. Setting SkyRefIs
to
``Pole'' produces an offset coordinate system which is approximately Polar
close to the specified position.

\cleardoublepage
\section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)}

The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate
systems which describe a position within an electro-magnetic spectrum.
In this section we examine the additional properties and behaviour of a
SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}).

\subsection{The SpecFrame Model}

As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
behaviour of these two ancestral classes.  When used as a Mapping, a
SpecFrame implements a unit transformation, exactly like a basic Frame
(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
behaviour is not of great importance.

When used as a Frame, however, a SpecFrame represents a wide range of
different 1-dimensional coordinate system which can be used to describe
positions within a spectrum. The options available largely mirror those
described in the FITS-WCS paper III \emph{Representations of spectral
coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen).

\subsection{Creating a SpecFrame}

The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a
SpecFrame with default attributes is created as follows:

\small
\begin{terminalv}
#include "ast.h"
AstSpecFrame *specframe;

...

specframe = astSpecFrame( "" );
\end{terminalv}
\normalsize

Such a SpecFrame would represent the default coordinate system which is
heliocentric wavelength in metres (i.e. wavelength corrected to take into
account the Doppler shift caused by the velocity of the observer around the
sun).

\subsection{Specifying a Particular Spectral Coordinate System}

Selection of a particular coordinate system is performed simply by
setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System}
attribute. This setting is most conveniently done when the SpecFrame is
created. For example, a SpecFrame representing Energy would be created by:

\small
\begin{terminalv}
specframe = astSpecFrame( "System=Energy" );
\end{terminalv}
\normalsize

Note that specifying ``System$=$Energy'' also changes the associated
Unit (from metres to Joules). This is because the default value
of the SpecFrame's Unit attribute depends on the System attribute setting.

You may change the System value at any time, although this is not
usually needed.  The values supported are set out in the attribute's
description in \appref{ss:attributedescriptions} and include a variety
of velocity systems, together with frequency, wavelength, energy,
wave-number, \emph{etc}.

\subsection{Attributes which Qualify Spectral Coordinate Systems}

Many spectral coordinate systems have some additional free parameters
which serve to identify a particular coordinate system from amongst a
broader class of related coordinate systems. For example, the
velocity systems are all parameterised by a rest frequency---the
frequency which defines zero velocity, and all coordinate systems
are qualified by a `standard of rest'' which indicates the rest frame to
which the values refer.

In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame}
attributes, each of which has a default appropriate to
(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System}
attribute. Each of these \emph{qualifying attributes} may, however, be
assigned an explicit value so as to select a particular coordinate
system. Note, it is usually best to assign explicit
values whenever possible rather than relying on defaults. Attribute
should only be left at their default value if you ``don't care'' what
value is used. In certain circumstances (particularly, when aligning two
Frames), a default value for an attribute may be replaced by the value
from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
assigning an explicit value to the attribute, rather than simply relying on
the default.


The main SpecFrame attributes which qualify the System attribute are:

\begin{quote}
\begin{description}

\item[\htmlref{Epoch}{Epoch}]\mbox{}\\
This attribute is inherited from the Frame class. It gives the moment in
time when the coordinates are correct for the astronomical source
under study (usually the date of observation). It is needed in order to
calculate the Doppler shift produced by the velocity of the observer
relative to the centre of the earth, and of the earth relative to the sun.

\item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\
This specifies the rest frame in which the coordinates are correct.
Transforming between different standards of rest involves taking account
of the Doppler shift introduced by the relative motion of the two
standards of rest.

\item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\
Specifies the frequency which correspond to zero velocity. When setting a
value for this attribute, the value may be supplied as a wavelength
(including an indication of the units being used, ``nm'' ``Angstrom'',
\emph{etc.}), which will be automatically be converted to a frequency.

\item[\htmlref{RefRA}{RefRA}]\mbox{}\\
Specifies the RA (FK5 J2000) of the source. This is used when converting
between standards of rest. It specifies the direction along which the
component of the relative velocity of the two standards of rest is taken.

\item[\htmlref{RefDec}{RefDec}]\mbox{}\\
Specifies the Dec (FK5 J2000) of the source. Used in conjunction with
REFRA.

\item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\
This defines the ``source'' standard of rest. This is a rest frame which
is moving towards the position given by RefRA and RefDec, at a velocity
given by SourceVel. The velocity is stored internally as a heliocentric
velocity, but can be given in any of the other supported standards of rest.

\end{description}
\end{quote}

For further details of these attributes you should consult their
descriptions in \appref{ss:attributedescriptions} and for details of
the System settings for which they are relevant, see the description
of the System attribute (also in \appref{ss:attributedescriptions}).

Note that it does no harm to assign values to qualifying attributes
which are not relevant to the main System value. Any such values are
stored, but are not used unless the System value is later set so that
they become relevant.

\subsection{Using Default SpecFrame Attributes}

The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend
on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this
means that there is usually little need to specify many of these
attributes explicitly unless you have some special requirement. This
can be illustrated by using \htmlref{astShow}{astShow} to examine a SpecFrame, as follows:

\small
\begin{terminalv}
astShow( astSpecFrame( "System=Vopt, RestFreq=250 GHz" ) );
\end{terminalv}
\normalsize

The output from this might look like the following:

\begin{terminalv}
 Begin SpecFrame        # Description of spectral coordinate system
#   Title = "Optical velocity, rest frequency = 250 GHz"       # Title
of coordinate system
    Naxes = 1   # Number of coordinate axes
#   Domain = "SPECTRUM"         # Coordinate system domain
#   Epoch = 2000        # Julian epoch of observation
#   Lbl1 = "Optical velocity"  # Label for axis 1
    System = "VOPT"     # Coordinate system type
#   Uni1 = "km/s"       # Units for axis 1
    Ax1 =       # Axis number 1
       Begin Axis       # Coordinate axis
       End Axis
 IsA Frame      # Coordinate system description
#   SoR = "Heliocentric"        # Standard of rest
    RstFrq = 250000000000       # Rest frequency (Hz)
 End SpecFrame
\end{terminalv}

Note that the defaults (indicated by the ``\verb?#?'' comment
character at the start of the line) for attributes such as the \htmlref{Title}{Title},
axis Labels and Unit specifiers are all set to values appropriate
for the particular velocity system that the SpecFrame represents.

These choices would be appropriate for a System value of ``Vopt'',
but if a different System value were set, the defaults would be
correspondingly different. For example, by default frequency is measured in
units of GHz, not $km/s$, so setting ``System=freq''
would change the appropriate line above from:

\begin{terminalv}
#   Uni1 = "km/s"       # Units for axis 1
\end{terminalv}

to

\begin{terminalv}
#   Uni1 = "GHz"        # Units for axis 1
\end{terminalv}

Of course, if you do not like any of these defaults, you may always
over-ride them by setting explicit attribute values yourself. For
instance, you may choose to have your frequency axis expressed in ``kHz''
rather than ``GHz''. To do this simply set the attribute value as follows:

\small
\begin{terminalv}
astSetC( specframe, "Unit", "kHz" );
\end{terminalv}
\normalsize

No error will be reported if you accidentally set an inappropriate Unit value
(say "J" - Joules)---after all, AST cannot tell what you are about to do,
and you \emph{may} be about to change the System value to ``Energy''.
However, an error \emph{will} be reported if you attempt to find a
conversion between two SpecFrames (for instance using
\htmlref{astConvert}{astConvert}
) if either SpecFrame has a Unit value which is inappropriate for its
System value.

SpecFrame attributes, like all other attributes, all have default
value. However, be aware that for some attributes these default values
can never be more than ``a legal numerical value'' and have no
astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes
(which give the source position) both have a default value of zero. So
unless your source happens to be at that point (highly unlikely!) you will
need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute
has an arbitrary default value of 1.0E5 GHz. Some operations are not
affected by inappropriate values for these attributes (for instance,
converting from frequency to wavelength, changing axis units, \emph{etc}),
but some are. For instance, converting from frequency to velocity
requires a correct rest frequency, moving between different standards of
rest requires a correct source position. The moral is, always set explicit
values for as many attributes as possible.

\subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes}
You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube
containing two spatial axes and a spectral axis. To do this you would
create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame}
(often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine
these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}.

\small
\begin{terminalv}
AstSkyFrame *skyframe;
AstSpecFrame *specframe;
AstCmpFrame *cmpframe;
...
skyframe = astSkyFrame( "Epoch=J2002" );
specframe = astSpecFrame( "System=Freq,StdOfRest=LSRK" );
cmpframe = astCmpFrame( skyframe, specframe, "" );
\end{terminalv}
\normalsize

In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis
3 will be Frequency. If this is not the order you want, you can permute
the axes using
\htmlref{astPermAxes}{astPermAxes}.

There is one potential problem with this approach if you are interested in
unusually high accuracy. Conversion between different standards of rest
involves taking account of the Doppler shift caused by the relative
motion of the two standards of rest. At some point this involves finding
the component of  the relative velocity in the direction of interest.
For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}
attributes, even if the SpecFrame is embedded within a CmpFrame as above.
It would be more appropriate if this ``direction of interest'' was
specified by the values passed into the CmpFrame on the RA and DEC axes,
allowing each pixel within a data cube to have a slightly different
correction for Doppler shift.

Unfortunately, the SpecFrame class cannot do this (since it is purely a
1-dimensional Frame), and so some small degree of error will be
introduced when converting between standards of rest, the size of the
error varying from pixel to pixel. It is hoped that at some point in the
future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which
allows for this spatial variation in Doppler shift.

The maximum velocity error introduced by this problem is of the order of
$V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the
relative velocity of the two standards of rest. As an example, when
correcting from the observers rest frame (i.e. the topocentric rest
frame) to the kinematic local standard of rest the maximum value of $V$
is about 20 $km/s$, so for 5 arc-minute field of view the maximum
velocity error introduced by the correction will be about 0.03 $km/s$. As
another example, the maximum error when correcting from the observers
rest frame to the local group is about 5 $km/s$ over a 1 degree field of
view.

\subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra}
Dual sideband super-heterodyne receivers produce spectra in which each channel
contains contributions from two different frequencies, referred to as the
``upper sideband frequency'' and the ``lower sideband frequency''. In the
rest frame of the observer (topocentric), these are related to each other as
follows:

\begin{quote}
\begin{small}
\begin{equation}
\label{eqn:dsb}
   f_{lsb} = 2.f_{LO} - f_{usb}
\end{equation}
\end{small}
\end{quote}

where $f_{LO}$ is a fixed frequency known as the ``local oscillator
frequency''. In other words, the local oscillator frequency is always
mid-way between any pair of corresponding upper and lower sideband
frequencies\footnote{Note, this simple relationship only applies if all
frequencies are topocentric.}. If you want to describe the spectral axis
of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the
SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot
describe both sidebands simultaneously. However, there is a sub-class of
SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty.

A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the
DSBSpecFrame is currently being used to describe the upper or lower
sideband spectral axis. The value of this attribute can be changed at any
time. If you use the
\htmlref{astConvert}{astConvert}
function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for
the two SideBand attributes will be taken into account. Thus, if you take
a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use
astConvert
to find a Mapping from the original to the modified copy, the resulting
Mapping will be of the form of equation \ref{eqn:dsb} (if the
DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric'').

In general, when finding a Mapping between two arbitrary DSBSpecFrames,
the total Mapping is made of of three parts in series:

\begin{enumerate}
\item A Mapping which converts the first DSBSpecFrame into its upper
sideband representation. If the DSBSpecFrame already represents its upper
sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}.
\item A Mapping which converts from the first to the second DSBSpecFrame,
treating them as if they were both basic SpecFrames. This takes account of
any difference in units, standard of rest, system, \emph{etc} between the
two DSBSpecFrames.
\item A Mapping which converts the second DSBSpecFrame from its upper
sideband representation to its current sideband. If the DSBSpecFrame
currently represents its upper sideband, this Mapping will be a UnitMap.
\end{enumerate}

If an attempt is made to find the Mapping between a DSBSpecFrame and a
basic SpecFrame, then the DSBSpecFrame will be treated like a basic
SpecFrame. In other words, the returned Mapping will not be affected by
the setting of the SideBand attribute (or any of the other attributes
specific to the DSBSpecFrame class).

In practice, the local oscillator frequency for a dual sideband
instrument may not be easily available to an observer. Instead, it is
common practice to specify the spectral position of some central feature
in the observation (commonly the centre of the instrument passband),
together with an ``intermediate frequency''. Together, these two values
allow the local oscillator frequency to be determined. The intermediate
frequency is the difference between the topocentric frequency at the
central spectral position and the topocentric frequency of the local
oscillator. So:

\begin{quote}
\begin{small}
\begin{equation}
\label{eqn:dsb2}
   f_{LO} = f_{central} + f_{if}
\end{equation}
\end{small}
\end{quote}

The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central
spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the
intermediate frequency ($f_{if}$). The DSBCentre value is given and returned
in the spectral system described by the DSBSpecFrame (thus you do not need to
calculate the corresponding topocentric frequency yourself - this will be
done automatically by the DSBSpecFrame when you assign a new value to the
DSBCentre attribute). The value assigned to the IF attribute should
always be a topocentric frequency in units of Hz, however a negative
value may be given to indicate that the DSBCentre value is in the upper
sideband (that is, if $IF < 0$  then $f_{central} > f_{LO}$). A positive
value for IF indicates that the DSBCentre value is in the lower sideband
(that is, if $IF > 0$  then $f_{central} < f_{LO}$).


\cleardoublepage
\section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)}

The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in
time. In this section we examine the additional properties and behaviour of a
TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}).

\subsection{The TimeFrame Model}

As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
behaviour of these two ancestral classes.  When used as a Mapping, a
TimeFrame implements a unit transformation, exactly like a basic Frame
(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
behaviour is not of great importance.

When used as a Frame, however, a TimeFrame represents a wide range of
different 1-dimensional coordinate system which can be used to describe
moments in time. Absolute times and relative (i.e. elapsed) times are
supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales
(attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can
be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch},
\emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to
allow them to be used with any unit of time (attribute Unit). The TimeFrame
class also allows times to formatted as either a simple floating point value
or as a Gregorian date and time of day (attribute Format).

\subsection{Creating a TimeFrame}

The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a
TimeFrame with default attributes is created as follows:

\small
\begin{terminalv}
#include "ast.h"
AstTimeFrame *timeframe;

...

timeframe = astTimeFrame( "" );
\end{terminalv}
\normalsize

Such a TimeFrame would represent the default coordinate system which is
Modified Julian Date (with the usual units of days) in the International
Atomic Time (TAI) time scale.

\subsection{Specifying a Particular Time System}
By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent
Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the
time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}).

Selection of a particular coordinate system is performed simply by
setting a value for the TimeFrame's (character string) System
attribute. This setting is most conveniently done when the TimeFrame is
created. For example, a TimeFrame representing Julian Epoch would be created
by:

\small
\begin{terminalv}
timeframe = astTimeFrame( "System=JEPOCH" );
\end{terminalv}
\normalsize

Note that specifying ``System$=$JEPOCH'' also changes the associated
default Unit (from days to years). This is because the default value
of the TimeFrame's Unit attribute depends on the System attribute setting.

You may change the System value at any time, although this is not
usually needed.  The values supported are set out in the attribute's
description in \appref{ss:attributedescriptions}.

\subsection{Attributes which Qualify Time Coordinate Systems}

Time coordinate systems require some additional free parameters to identify
a particular coordinate system from amongst a broader class of related
coordinate systems. For example, all TimeFrames are qualified by the time
scale (that is, the physical process used to define the flow of time),
and some require the position of the observer's clock.

In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame}
attributes, each of which has a default appropriate to (\emph{i.e.}\ defined
by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying
attributes} may, however, be assigned an explicit value so as to select a
particular coordinate system. Note, it is usually best to assign explicit
values whenever possible rather than relying on defaults. Attribute
should only be left at their default value if you ``don't care'' what
value is used. In certain circumstances (particularly, when aligning two
Frames), a default value for an attribute may be replaced by the value
from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
assigning an explicit value to the attribute, rather than simply relying on
the default.

The main TimeFrame attributes which qualify the System attribute are:

\begin{quote}
\begin{description}

\item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\
This specifies the time scale.

\item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\
This specifies the offset from Local Time to UTC in hours (time zones
east of Greenwich have positive values). Note, AST uses the value as
supplied without making any correction for daylight saving.

\item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\
This specifies the zero point from which time values are measured, within
the system specified by the System attribute. Thus, a value of zero (the
default) indicates that time values represent absolute times. Non-zero
values may be used to indicate that the TimeFrame represents elapsed time
since the specified origin.

\end{description}
\end{quote}

For further details of these attributes you should consult their
descriptions in \appref{ss:attributedescriptions} and for details of
the System settings for which they are relevant, see the description
of the System attribute (also in \appref{ss:attributedescriptions}).

Note that it does no harm to assign values to qualifying attributes
which are not relevant to the main System or TimeScale value. Any such
values are stored, but are not used unless the System and/or TimeScale
value is later set so that they become relevant.

\cleardoublepage
\section{\label{ss:cmpframes}Compound Frames (CmpFrames)}

We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The
Frames we have considered so far have been atomic, in the sense that
they represent pre-defined elementary physical domains. A CmpFrame,
however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for
containing other Frames and its purpose is to allow those Frames
to work together in various combinations while appearing as a single
\htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is
determined by the other Frames it contains (its ``component'' Frames).

As with compound Mappings, compound Frames can be nested within each
other, forming arbitrarily complex Frames.

\subsection{Creating a CmpFrame}
A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a
``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes
represents position within a spectrum, and the other two axes represent
position on the sky (or some other spatial domain such as the focal plane
of a telescope). As an example, we create such a CmpFrame in which axes
1 and 2 represent Right Ascension and Declination (ICRS), and axis 3
represents wavelength (these are the default coordinate Systems
represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively):

\small
\begin{terminalv}
AstSkyFrame *skyframe;
AstSpecFrame *specframe;
AstCmpFrame *cmpframe;
...
skyframe = astSkyFrame( "" );
specframe = astSpecFrame( "" );
cmpframe = astCmpFrame( skyframe, specframe, "" );
\end{terminalv}
\normalsize

If it was desired to make RA and Dec correspond to axes 1 and 3, with
axis 2 being the spectral axis, then the axes of the CmpFrame created
above would need to be permuted as follows:

\small
\begin{terminalv}
int perm[ 3 ];
...

perm[ 0 ] = 0;
perm[ 1 ] = 2;
perm[ 2 ] = 1;
astPermAxes( cmpframe, perm );
\end{terminalv}
\normalsize

\subsection{The Attributes of a CmpFrame}

A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame.
The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by
concatenating the Domains of the two component Frames, separated by a
minus sign (``-'').\footnote{If both component Frames have blank Domains,
then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed)
value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to
change the System value of a CmpFrame is ignored.} A CmpFrame has no
further attributes over and above those common to all Frames. However,
attributes of the two component Frames can be accessed as if they were
attributes of the CmpFrame, as described below.

Frame attributes which are specific to individual axes (such as Label(2),
Format(1), \emph{etc}) simply mirror the corresponding axes of the
relevant component Frame. That is, if the ``Label(2)'' attribute of a
CmpFrame is accessed, the CmpFrame will forward the access request to the
component Frame which contains axis 2. Thus, default values for axis
attributes will be the same as those provided by the component Frames.

An axis index can optionally be appended to the name of Frames attributes
which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title},
\emph{etc}). If this is done, the access request is forwarded to the
component Frame containing the indicated axis. For instance, if a
CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes
have not been permuted, then getting the value of attribute ``System'' will
return  ``Compound'' as mentioned above (that is, the System value of the
CmpFrame as a whole), whereas getting the value of attribute
``System(1)'' will return ``Spectral''(that is, the System value of the
component Frame containing axis 1 --- the SpecFrame).

This technique is not limited to attributes common to all Frames. For
instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is
not held by other classes of Frames. To set a value for the Equinox
attribute of the SkyFrame contained within the above CmpFrame, assign the
value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame
defines both axes 2 and 3 of the CmpFrame, we could equivalently have set
a value for ``Equinox(3)'' since this would also result in the attribute
access being forwarded to the SkyFrame.

Finally, if an attribute is not qualified by a axis index, attempts will
be made to access it using each of the CmpFrame axes in turn. Using the
above example of the spectral cube, if an attempt was made to get the
value of attribute ``Equinox'' (with no axis index), each axis in turn
would be used. Since axis 1 is contained within a SpecFrame, the first
attempt would fail since the SpecFrame class does not have an Equinox
attribute. However, the second attempt would succeed because axis 2 is
contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus
the returned attribute value would be that obtained from the SkyFrame
containing axis 2. When getting or testing an attribute value, the
returned value is determined by the \emph{first} axis which recognises
the attribute. When setting an attribute value, \emph{all} axes
which recognises the attribute have the attribute value set to the given
value. Likewise, when clearing an attribute value, all axes
which recognises the attribute have the attribute value cleared.

\cleardoublepage
\section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions}

In this section, we start to look at techniques for converting between
different coordinate systems.  At this stage, the tools we have available
are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}),
SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and
various Mappings (\secref{ss:mappings}). These are sufficient to allow us to
begin examining the problem, but more sophisticated approaches will also emerge
later (\secref{ss:framesetconverting}).

\subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems}

We begin by examining how to convert between two celestial coordinate
systems represented by SkyFrames, as this is both an illuminating and
practical example.  Consider the problem of converting celestial
coordinates between:

\begin{enumerate}
\item The old FK4 system, with no E terms, a Besselian epoch of
1958.0 and a Besselian equinox of 1960.0.

\item An ecliptic coordinate system based on the mean equinox and
ecliptic of Julian epoch 2010.5.
\end{enumerate}

This example is arbitrary but not completely unrealistic. Unless you
already have expertise with such conversions, you are unlikely to find
it straightforward.

Using AST, we begin by creating two SkyFrames to represent these
coordinate systems, as follows:

\small
\begin{terminalv}
#include "ast.h"
AstSkyFrame *skyframe1, *skyframe2;

...

skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" );
skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" );
\end{terminalv}
\normalsize

Note how specifying the coordinate systems consists simply of
initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately.  The next
step is to find a way of converting between these SkyFrames. This is
done using \htmlref{astConvert}{astConvert}, as follows:

\small
\begin{terminalv}
AstFrameSet *cvt;

...

cvt = astConvert( skyframe1, skyframe2, "" );
if ( cvt == AST__NULL ) {
   <conversion is not possible>
} else {
   <conversion is possible>
}
\end{terminalv}
\normalsize

The third argument of astConvert is not used here and should be an
empty string.

astConvert will return a null result, AST\_\_NULL (as defined in the
``ast.h'' header file), if conversion is not possible. In this
example, conversion is possible, so it will return a pointer to a new
\htmlref{Object}{Object} that describes the conversion.

The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed
FrameSets yet (\secref{ss:framesets}), but for the present purposes we
can consider them simply as Objects that can behave both as Mappings
and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we
are mainly interested here, because the Mapping it implements is the
one we require---\emph{i.e.}\ it converts between the two celestial
coordinate systems (\secref{ss:framesetsfromconvert}).

For example, if ``alpha1'' and ``delta1'' are two arrays containing
the longitude and latitude, in radians, of N points on the sky in the
original coordinate system (corresponding to ``skyframe1''), then they
could be converted into the new coordinate system (represented by
``skyframe2'') as follows:

\small
\begin{terminalv}
#define N 10
double alpha1[ N ], delta1[ N ];
double alpha2[ N ], delta2[ N ];

...

astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 );
\end{terminalv}
\normalsize

The new coordinates are returned \emph{via} the ``alpha2'' and
``delta2'' arrays.  To transform coordinates in the opposite
direction, we simply invert the 5th (boolean int) argument to
\htmlref{astTran2}{astTran2}, as follows:

\small
\begin{terminalv}
astTran2( cvt, N, alpha2, delta2, 0, alpha1, delta1 );
\end{terminalv}
\normalsize

The FrameSet returned by astConvert also contains information about
the SkyFrames used in the conversion
(\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet
may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the
``destination'' Frame used in the conversion (\emph{i.e.}\ like
``skyframe2'').  We could therefore use the ``cvt'' FrameSet to
calculate the distance between two points (with coordinates in
radians) in the destination coordinate system, using \htmlref{astDistance}{astDistance}:

\small
\begin{terminalv}
double distance, point1[ 2 ], point2[ 2 ];

...

distance = astDistance( cvt, point1, point2 );
\end{terminalv}
\normalsize

and the result would be the same as if the ``skyframe2'' SkyFrame had
been used.

Another way to see how the FrameSet produced by astConvert retains
information about the coordinate systems involved is to set its \htmlref{Report}{Report}
attribute (inherited from the Mapping class) so that it displays the
coordinates before and after conversion (\secref{ss:transforming}):

\small
\begin{terminalv}
astSet( cvt, "Report=1" );
astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 );
\end{terminalv}
\normalsize

The output from this might look like the following:

\begin{terminalv}
(2:06:03.0, 34:22:39) --> (42.1087, 20.2717)
(2:08:20.6, 35:31:24) --> (43.0197, 21.1705)
(2:10:38.1, 36:40:09) --> (43.9295, 22.0716)
(2:12:55.6, 37:48:55) --> (44.8382, 22.9753)
(2:15:13.1, 38:57:40) --> (45.7459, 23.8814)
(2:17:30.6, 40:06:25) --> (46.6528, 24.7901)
(2:19:48.1, 41:15:11) --> (47.5589, 25.7013)
(2:22:05.6, 42:23:56) --> (48.4644, 26.6149)
(2:24:23.1, 43:32:41) --> (49.3695, 27.5311)
(2:26:40.6, 44:41:27) --> (50.2742, 28.4499)
\end{terminalv}

Here, we see that the input FK4 equatorial coordinate values (given in
radians) have been formatted automatically in sexagesimal notation
using the conventional hours for right ascension and degrees for
declination. Conversely, the output ecliptic coordinates are shown in
decimal degrees, as is conventional for ecliptic coordinates. Both are
displayed using the default precision of 7 digits.\footnote{The
leading digit is zero and is therefore not seen in this particular
example.}

In fact, the ``cvt'' FrameSet has access to all the information in the
original SkyFrames which were passed to astConvert. If you had set a
new Digits attribute value for either of these, the formatting above
would reflect the different precision you requested by displaying a
greater or smaller number of digits.


\subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems}
The principles described in the previous section for converting between
celestial coordinate systems also apply to the task of converting between
spectral coordinate systems. As an example, let's look at how we might
convert between frequency measured in $GHz$ as measured in the rest frame
of the telescope, and radio velocity measured in $km/s$ measured with
respect the kinematic Local Standard of Rest.

First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to
describe the required radio velocity system (this is slightly more
convenient, given the relatively large number of attributes, than
specifying the attribute values in a single string such as would be
passed to the SpecFrame constructor). We then take a copy of this
SpecFrame, and change the attribute values so that the copy describes the
original frequency system (modifying a copy, rather than creating a new
SpecFrame from scratch, avoids the need to specify the epoch, reference
position, \emph{etc} a second time since they are all inherited by the copy):

\small
\begin{terminalv}
#include "ast.h"
AstSpecFrame *specframe1, *specframe2;

...

specframe1 = astSpecFrame( "" );
astSet( specframe1, "System=vradio" );
astSet( specframe1, "Unit=km/s" );
astSet( specframe1, "Epoch=1996-Oct-2 12:13:56.985" );
astSet( specframe1, "ObsLon=W155:28:18" );
astSet( specframe1, "ObsLat=N19:49:34" );
astSet( specframe1, "RefRA=18:14:50.6" );
astSet( specframe1, "RefDec=-4:40:49" );
astSet( specframe1, "RestFreq=230.538 GHz" );
astSet( specframe1, "StdOfRest=LSRK" );

specframe2 = astCopy( specframe1 );
astSet( specframe1, "System=freq" );
astSet( specframe1, "Unit=GHz" );
astSet( specframe1, "StdOfRest=Topocentric" );

\end{terminalv}
\normalsize

Note, the fact that a SpecFrame has only a single axis means that we were
able to refer to the Unit attribute without an axis index. The other
attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical
position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source
on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the
standard of rest (\htmlref{StdOfRest}{StdOfRest}).

The next step is to find a way of converting between these SpecFrames. We
use exactly the same code that we did in the previous section where we were
converting between celestial coordinate systems:

\small
\begin{terminalv}
AstFrameSet *cvt;

...

cvt = astConvert( specframe1, specframe2, "" );
if ( cvt == AST__NULL ) {
   <conversion is not possible>
} else {
   <conversion is possible>
}
\end{terminalv}
\normalsize

A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible,
which should always be the case for our example), and we can use the
FrameSet to convert between the two spectral coordinate systems. We use
\htmlref{astTran1}{astTran1} in place of \htmlref{astTran2}{astTran2}
since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two).

For example, if ``frq'' is an array containing the observed frequency, in
GHz, of N spectral channels (describe by ``specframe1''), then they
could be converted into the new coordinate system (represented by
``specframe2'') as follows:

\small
\begin{terminalv}
#define N 10
double frq[ N ];
double vel[ N ];

...

astTran1( cvt, N, frq, 1, vel );
\end{terminalv}
\normalsize

The radio velocity values are returned in the ``vel'' array.


\subsection{Converting between Time Coordinate Systems}
All the principles outlined in the previous section about aligning
spectral cocordinate systems (SpecFrames) can be applied directly to the
problem of aligning time coordinate systems (TimeFrames).

\subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations}

We can illustrate an important point if we swap the axis order of
either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes})
before identifying the conversion. Let's assume we use \htmlref{astPermAxes}{astPermAxes}
(\secref{ss:permutingaxes}) to do this to the second SkyFrame, before
applying \htmlref{astConvert}{astConvert}, as follows:

\small
\begin{terminalv}
int perm[ 2 ] = { 2, 1 };

...

astPermAxes( skyframe2, perm );
cvt = astConvert( skyframe1, skyframe2, "" );
\end{terminalv}
\normalsize

Now, the destination SkyFrame system no longer represents the
coordinate system:

\begin{quote}
(ecliptic~longitude, ecliptic~latitude)
\end{quote}

but instead represents the transposed system:

\begin{quote}
(ecliptic~latitude, ecliptic~longitude)
\end{quote}

As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by astConvert to
apply a coordinate transformation, we obtain something like the
following:

\begin{terminalv}
(2:06:03.0, 34:22:39) --> (20.2717, 42.1087)
(2:08:20.6, 35:31:24) --> (21.1705, 43.0197)
(2:10:38.1, 36:40:09) --> (22.0716, 43.9295)
(2:12:55.6, 37:48:55) --> (22.9753, 44.8382)
(2:15:13.1, 38:57:40) --> (23.8814, 45.7459)
(2:17:30.6, 40:06:25) --> (24.7901, 46.6528)
(2:19:48.1, 41:15:11) --> (25.7013, 47.5589)
(2:22:05.6, 42:23:56) --> (26.6149, 48.4644)
(2:24:23.1, 43:32:41) --> (27.5311, 49.3695)
(2:26:40.6, 44:41:27) --> (28.4499, 50.2742)
\end{terminalv}

When compared to the original (\secref{ss:convertingskyframes}), the
output coordinate order has been swapped to compensate for the
different destination SkyFrame axis order.

In all, there are four possible axis combinations, corresponding to two
possible axis orders for each of the source and destination SkyFrames,
and astConvert will convert correctly between any of these.
The point to note is that a SkyFrame contains knowledge about how to
convert to and from other SkyFrames. Since its two axes (longitude and
latitude) are distinguishable, the conversion is able to take account
of the axis order.

If you need to identify the axes of a SkyFrame explicitly, taking into
account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be
used. These are read-only attributes which give the indices of the
latitude and longitude axes respectively.

\subsection{\label{ss:convertingframes}Converting Between Frames}

Having seen how clever SkyFrames are (\secref{ss:convertingskyframes}
and \secref{ss:convertingpermutedaxes}), we will next examine how dumb
a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two
2-dimensional Frames and use \htmlref{astConvert}{astConvert} to derive a conversion between
them, as follows:

\small
\begin{terminalv}
AstFrame *frame1, *frame2;

...

frame1 = astFrame( 2, "" );
frame2 = astFrame( 2, "" );
cvt = astConvert( frame1, frame2, "" );
\end{terminalv}
\normalsize

then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs
will be as follows:

\begin{terminalv}
(1, 2) --> (1, 2)
(2, 4) --> (2, 4)
(3, 6) --> (3, 6)
(4, 8) --> (4, 8)
(5, 10) --> (5, 10)
\end{terminalv}

This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap}
(\secref{ss:unitmapexample}). Even if we permute the axis order of our
Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will
fare no better. The conversion between our two basic Frames will
always be an identity transformation.

The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start
life the same and have axes that are indistinguishable. Therefore,
permuting their axes doesn't make them look any different---they still
represent the same coordinate system.
%Actually, this behaviour isn't as dumb as it seems and can actually be
%very useful, as the following example illustrates.
%
%\subsection{Distinguishable and Indistinguishable Axes}
%
%c+
%Imagine you have two Frames which represent the pixel coordinates of
%two 2-dimensional images. Let's call their axes ``X'' and ``Y''.
%Suppose you now transpose the second image and swap its Frame axes
%(with \htmlref{astPermAxes}{astPermAxes}) to take account of this.
%c-
%f+
%Imagine you have two Frames which represent the pixel coordinates of
%two 2-dimensional images. Let's call their axes ``X'' and ``Y''.
%Suppose you now transpose the second image and swap its Frame axes
%(with astPermAxes) to take account of this.
%f-
%
%Next, consider what happens if you want to subtract one image from the
%other. If you have a ``subtract'' program that is intelligent and
%tries to align the two images for you, one of two things could happen:
%
%\begin{enumerate}
%c+
%\item If the axes are distinguishable, when your program invokes
%astConvert it will derive a transformation between the two images
%which swaps the X and Y coordinates (corresponding to the transposition
%you applied to the second image). However, in aligning X-with-X and
%Y-with-Y, this will completely undo the effects of your transposition!
%c-
%f+
%\item If the axes are distinguishable, when your program invokes
%AST\_CONVERT it will derive a transformation between the two images
%which swaps the X and Y coordinates (corresponding to the transposition
%you applied to the second image). However, in aligning X-with-X and
%Y-with-Y, this will completely undo the effects of your transposition!
%f-
%
%\item If the axes are indistinguishable, the transformation between
%the two images will always be an identity
%(\secref{ss:convertingframes}). Therefore, your program will align
%X-with-Y and Y-with-X, so that you see the effects of your earlier
%transposition of the second image.
%\end{enumerate}
%
%Clearly, if we are considering pixel coordinates, the latter behaviour
%is preferable, since there would be no point in implementing an image
%transposition program if we could never see the effects of it. This
%indicates that a basic Frame, with is indistinguishable axes, is the
%correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where
%this behaviour is necessary.
%
%Conversely, the former behaviour would be more useful if the axes we
%were considering were, say, wavelength (in nm) and slit position (in
%mm). In this case, we would expect our ``subtract'' program to
%subtract data at corresponding wavelengths and slit positions, not
%just at corresponding pixels. This case requires distinguishable axes,
%so that corresponding axes in the two images can be matched up, just
%as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}).
%
%Of course, there may also be intermediate cases, where some axes are
%distinguishable and others aren't.

\subsection{\label{ss:alignmentsystem}The Choice of Alignment System}

In practice, when AST is asked to find a conversion between two Frames
describing two different coordinate systems on a given physical domain,
it uses an intermediate ``alignment'' system. Thus, when finding a
conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from
system A to some alignment system, system C, and then finds the Mapping
from this system C to the required system B. It finally concatenates
these two Mappings to get the Mapping from system A to system B.

One advantage of this is that it cuts down the number of conversion
algorithms required. If there are $N$ different Systems which may be used
to describe positions within the \htmlref{Domain}{Domain}, then this approach requires
about $2*N$ conversion algorithms to be written. The alternative approach
of going directly from system A to system B would require about $N*N$
conversion algorithms.

In addition, the use of an intermediate alignment system highlights the
nature of the conversion process. What do we mean by saying that a
Mapping ``converts a position in one coordinate system into the
corresponding position in another''? In practice, it means that the input
and output coordinates correspond to the same coordinates \emph{in some
third coordinate system}. The choice of this third coordinate system, the
``alignment'' system, can completely alter the nature of the Mapping. The
\htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to
specify the alignment system.

As an example, consider the case of aligning two spectra calibrated in
radio velocity, but each with a different rest frequency (each spectrum
will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a
given velocity will correspond to different frequencies in the two
spectra. So when we come to ``align'' these two spectra (that is, find a
Mapping which converts positions in one SpecFrame to the corresponding
positions in the other), we have the choice of aligning the frequencies
or aligning the velocities. Different Mappings will be required to
describe these two forms of alignment. If we set AlignSystem to ``Freq''
then the returned Mapping will align the frequencies described by the two
SpecFrames. On the other hand, if we set AlignSystem to ``Vradio''
then the returned Mapping will align the velocities.

Some choices of alignment system are redundant. For instance, in the
above example, changing the alignment system from frequency to wavelength
has no effect on the returned Mapping: if two spectra are aligned in
frequency they will also be aligned in wavelength (assuming the speed of
light doesn't change).

The default value for AlignSystem depends on the class of Frame. For a
SpecFrame, the default is wavelength (or equivalently, frequency)
since this is the system in which observations are usually made. The
SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which
allows the standard of rest of the alignment system to be specified.
Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale}
which allows the time scale of the alignment system to be specified.
Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since
this is a close approximation to an inertial frame of rest.

\cleardoublepage
\section{\label{ss:framesets}Coordinate System Networks (FrameSets)}

We saw in \secref{ss:introducingconversion} how \htmlref{astConvert}{astConvert} could be
used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems
represented by Frames. There is a limitation to this, however, in that
it can only be applied to coordinate systems that are inter-related by
suitable conventions. In the case of celestial coordinates, the
relevant conventions are standards set out by the International
Astronomical Union, and others, that define what these coordinate
systems mean. In practice, however, the relationships between many
other coordinate systems are also of practical importance.

Consider, for example, the focal plane of a telescope upon which an
image of the sky is falling. We could measure positions in this focal
plane in millimetres or, if there were a detector system such as a CCD
present, we could count pixels. We could also use celestial
coordinates of many different kinds. All of these systems are
equivalent in their effectiveness at specifying positions in the focal
plane, but some are more convenient than others for particular
purposes.

Although we could, in principle, convert between all of these focal
plane coordinate systems, there is no pre-defined convention for doing
so. This is because the conversions required depend on where the
telescope is pointing and how the CCD is mounted in the focal
plane. Clearly, knowledge about this cannot be built into the AST
library and must be supplied in some other way. Note that this is
exactly the same problem as we met in \secref{ss:framedomains} when
discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that
apply to different physical domains require that extra information be
supplied before we can convert between them.

What we need, therefore, is a general way to describe how coordinate
systems are inter-related, so that when there is no convention already
in place, we can define our own. We can then look forward to
converting, say, from pixels into galactic coordinates and {\emph{vice
versa.}  In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability.

\subsection{The FrameSet Model}

Consider a coordinate system (call it number 1) which is represented
by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to
the coordinates in system 1 yields coordinates in another system,
number 2. The Mapping therefore inter-relates coordinate systems 1 and
2.

Now consider a second Mapping which inter-relates system 1 and a
further coordinate system, number 3. If we wanted to convert
coordinates between systems 2 and 3, we could do so by:

\begin{enumerate}
\item Applying our first Mapping in reverse, so as to convert between
systems 2 and 1.

\item Applying the second Mapping, as given, to convert between
systems 1 and 3.
\end{enumerate}

We are not limited to three coordinate systems, of course. In fact, we
could continue to introduce any number of further coordinate systems,
so long as we have a suitable Mapping for each one which relates it to
one of the Frames already present. Continuing in this way, we can
build up a network in which Frames are inter-related by Mappings in
such a way that there is always a way of converting between any pair
of coordinate systems.

The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas.  It
is a network composed of Frames and associated Mappings, in which
there is always exactly one path, \emph{via} Mappings, between any
pair of Frames.  Since we assemble FrameSets ourselves, they can be
used to represent any coordinate systems we choose and to set up the
particular relationships between them that we want.

\subsection{\label{ss:creatingaframeset}Creating a FrameSet}

Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to
put into it, so let's create a simple one:

\small
\begin{terminalv}
#include "ast.h"
AstFrame *frame1;

...

frame1 = astFrame( 2, "Domain=A" );
\end{terminalv}
\normalsize

We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to
A so that it will be distinct from the others we will be using. We can
now create a new FrameSet containing just this Frame, as follows:

\small
\begin{terminalv}
AstFrameSet *frameset;

...

frameset = astFrameSet( frame1, "" );
\end{terminalv}
\normalsize

So far, however, this Frame isn't related to any others.

\subsection{\label{ss:addingframes}Adding New Frames to a FrameSet}

We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above
(\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame}
and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that
are already present (there is only one present so far).  To keep the
example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates
by 10. The required Objects are created as follows:

\small
\begin{terminalv}
AstFrame *frame2;
AstMapping *mapping12;

...

frame2 = astFrame( 2, "Domain=B" );
mapping12 = astZoomMap( 2, 10.0, "" );
\end{terminalv}
\normalsize

To add the new Frame into our FrameSet, we use the \htmlref{astAddFrame}{astAddFrame}
function:

\small
\begin{terminalv}
astAddFrame( frameset, 1, mapping12, frame2 );
\end{terminalv}
\normalsize

Whenever a Frame is added to a FrameSet, it is assigned an integer
index. This index starts with 1 for the initial Frame used to create
the FrameSet (\secref{ss:creatingaframeset}) and increments by one
every time a new Frame is added. This index is the primary way of
identifying the Frames within a FrameSet.

When a Frame is added, we also have to specify which of the existing
ones the new Frame is related to. Here, we chose number 1, the only
one present so far, and the new one we added became number 2.

Note that a FrameSet does not make copies of the Frames and Mappings
that you insert into it. Instead, it holds pointers to them. This
means that if you retain the original pointers to these Objects and
alter them, you will indirectly be altering the FrameSet's
contents. You can, of course, always use \htmlref{astCopy}{astCopy}
(\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if
you need to ensure its independence.

We could also add a third Frame into our FrameSet, this time defining
a coordinate system which is reached by multiplying the original
coordinates (of ``frame1'') by 5:

\small
\begin{terminalv}
astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) );
\end{terminalv}
\normalsize

Here, we have avoided storing unnecessary pointer values by using
function invocations directly as arguments for astAddFrame. This
assumes that we are using \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} (\secref{ss:contexts}) to
ensure that Objects are correctly deleted when no longer required.

   Our example FrameSet now contains three Frames and two Mappings with
   the arrangement shown in Figure~\ref{fig:fsexample}.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/fsexample}
   \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to
   Frame~1 by multiplying its coordinates by factors of 10 and 5
   respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its
   \htmlref{Current}{Current} attribute has the value 3. The transformation performed when
   the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to
   its current Frame) is shown in bold.}
   \label{fig:fsexample}
   \end{center}
   \end{figure}
   The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute.

\subsection{\label{ss:baseandcurrent}The Base and Current Frames}

At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its
\emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame
(Figure~\ref{fig:fsexample}). These Frames are identified by two
integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices
of the nominated Frames within the FrameSet.

The existence of the base and current Frames reflects an important
application of FrameSets, which is to attach coordinate systems to
entities such as data arrays, data files, plotting surfaces (for
graphics), \emph{etc.}  In this context, the base Frame represents the
``native'' coordinate system of the attached entity---for example, the
pixel coordinates of an image or the intrinsic coordinates of a
plotting surface. The other Frames within the FrameSet represent
alternative coordinate systems which may also be used to refer to
positions within that entity.  The current Frame represents the
particular coordinate system which is currently selected for use. For
instance, if an image were being displayed, you would aim to label it
with coordinates corresponding to the current Frame. In order to see a
different coordinate system, a software user would arrange for a
different Frame to be made current.

The choice of base and current Frames may be changed at any time,
simply by assigning new values to the FrameSet's Base and Current
attributes. For example, to make the Frame with index 3 become the
current Frame, you could use:

\small
\begin{terminalv}
astSetI( frameset, "Current", 3 );
\end{terminalv}
\normalsize

You can nominate the same Frame to be both the base and current Frame
if you wish.
\label{ss:baseandcurrentdefault}

By default (\emph{i.e.}\ if the Base or Current attribute is un-set),
the first Frame added to a FrameSet becomes its base Frame and the
last one added becomes its current Frame.\footnote{Although this is
reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a
new Frame is added to a FrameSet, the Current attribute is modified so
that the new Frame becomes the current one. This behaviour is
reflected in the state of the example FrameSet in
Figure~\ref{fig:fsexample}.

\subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames}

It is often necessary to refer to the base and current Frames
(\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be
cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current}
attributes on each occasion. To make this easier, two macros,
AST\_\_BASE and AST\_\_CURRENT, are defined in the ``ast.h'' header
file and may be used to represent the indices of the base and current
Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is
required.

For example, when adding a new Frame to a FrameSet
(\secref{ss:addingframes}), you could use the following to indicate
that the new Frame is related to the existing current Frame, whatever
its index happens to be:

\small
\begin{terminalv}
AstFrame *frame;
AstMapping *mapping;

...

astAddFrame( frameset, AST__CURRENT, mapping, frame );
\end{terminalv}
\normalsize

Of course, the Frame you added would then become the new current
Frame.

\subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping}

The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame}
class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class
(\secref{ss:mappings}). Its behaviour when used as a Mapping is
particularly important.

Consider, for instance, passing a FrameSet pointer to a coordinate
transformation function such as \htmlref{astTran2}{astTran2}:

\small
\begin{terminalv}
#define N 10
double xin[ N ], yin[ N ], xout[ N ], yout[ N ];

...

astTran2( frameset, N, xin, yin, 1, xout, yout );
\end{terminalv}
\normalsize

The coordinate transformation applied by this FrameSet would be the
one which converts between its base and current Frames. Using the
FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates
would be multiplied by a factor of 5.  If we instead requested the
FrameSet's inverse transformation, we would be transforming from its
current Frame to its base Frame, so our example FrameSet would then
multiply by a factor of 0.2.

Whenever the choice of base and current Frames changes, the
transformations which a FrameSet performs when used as a Mapping also
change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in
consequence, because they are determined by the numbers of axes in the
FrameSet's base and current Frames respectively. These numbers need
not necessarily be equal, of course.

Like any Mapping, a FrameSet may also be inverted by changing the
boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{astInvert}{astInvert}
(\secref{ss:invertingmappings}). If this is happens, the values of the
FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with
its Nin and Nout attributes, so that its base and current Frames swap
places. When used as a Mapping, the FrameSet will therefore perform
the inverse transformation to that which it performed previously.

To summarise, a FrameSet may be used exactly like any other Mapping
which inter-relates the coordinate systems described by its base and
current Frames.

\subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet}

Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is
required (\secref{ss:framesetasmapping}), a FrameSet necessarily
contains additional information and sometimes this might cause
inefficiency or confusion.  For example, if you wanted to use a
Mapping contained in one FrameSet and insert it into another, it would
probably not be efficient to insert the whole of the first FrameSet
into the second one, although it would work.

In such a situation, the \htmlref{astGetMapping}{astGetMapping} function allows you to extract
a Mapping from a FrameSet. You do this by specifying the two Frames
which the Mapping should inter-relate using their indices within the
FrameSet. For example:

\small
\begin{terminalv}
map = astGetMapping( frameset, 2, 3 );
\end{terminalv}
\normalsize

would return a pointer to a Mapping that converted between Frames~2
and 3 in the FrameSet. Its inverse transformation would then convert
in the opposite direction, \emph{i.e.}\ between Frames~3 and 2.  Note
that this Mapping might not be independent of the Mappings contained
within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so
\htmlref{astCopy}{astCopy} should be used to make a copy if you need to guarantee
independence (\secref{ss:copyingobjects}).

Very often, the Mapping returned by astGetMapping will be a compound
Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that
conversion between the two Frames may need to be done \emph{via} an
intermediate coordinate system so that several stages may be involved.
You can, however, easily simplify this Mapping (where this is possible)
by using the \htmlref{astSimplify}{astSimplify} function (\secref{ss:simplifyingcmpmaps}) and
this is recommended if you plan to use it for transforming a large
amount of data.

\subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame}

A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost
always behaves as if its current Frame had been used instead. For
example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using:

\small
\begin{terminalv}
const char *title;

...

title = astGetC( frameset, "Title" );
\end{terminalv}
\normalsize

the result will be the Title of the current Frame, or a suitable
default if the current Frame's Title attribute is un-set. The same
also applies to other attribute operations---\emph{i.e.}\ setting,
clearing and testing attributes.  Most attributes shared by both
Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)},
\htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions:

\begin{quote}
\begin{description}
\item[\htmlref{Class}{Class}]\mbox{}\\
Has the value ``FrameSet''.

\item[\htmlref{ID}{ID}]\mbox{}\\
Identifies the particular FrameSet (not its current Frame).

\item[\htmlref{Nin}{Nin}]\mbox{}\\
Equals the number of axes in the FrameSet's base Frame.

\item[\htmlref{Invert}{Invert}]\mbox{}\\
Is independent of any of the Objects within the FrameSet.

\item[\htmlref{Nobject}{Nobject}]\mbox{}\\
Counts the number of active FrameSets.

\item[\htmlref{RefCount}{RefCount}]\mbox{}\\
Counts the number of active pointers to the FrameSet (not to its
current Frame).
\end{description}
\end{quote}

Note that the set of attributes possessed by a FrameSet can vary,
depending on the nature of its current Frame. For example, if the
current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet
will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired,
\emph{etc.}  However, if the current Frame is changed to be a basic
Frame, which does not have an Equinox attribute, then this attribute
will be absent from the FrameSet as well. Any attempt to reference it
will then result in an error.

\subsection{Extracting a Frame from a FrameSet}

Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most
situations, it is sometimes convenient to have direct access to a
specified Frame within it. This may be obtained using the \htmlref{astGetFrame}{astGetFrame}
function, as follows:

\small
\begin{terminalv}
frame = astGetFrame( frameset, AST__BASE );
\end{terminalv}
\normalsize

This would return a pointer (not a copy) to the base Frame within the
FrameSet. Note the use of AST\_\_BASE
(\secref{ss:astbaseandastcurrent}) as shorthand for the value of the
FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index.

\subsection{Removing a Frame from a FrameSet}

Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed
using the \htmlref{astRemoveFrame}{astRemoveFrame} function. You identify the Frame you wish to
remove in the usual way, by giving its index within the FrameSet. For
example, the following would remove the Frame with index 1:

\small
\begin{terminalv}
astRemoveFrame( frameset, 1 );
\end{terminalv}
\normalsize

The only restriction is that you cannot remove the last remaining
Frame because a FrameSet must always contain at least one Frame.  When
a Frame is removed, the Frames which follow it are re-numbered
(\emph{i.e.}\ their indices are reduced by one) so as to preserve the
sequence of consecutive Frame indices.  The FrameSet's \htmlref{Nframe}{Nframe}
attribute is also decremented.

If appropriate, astRemoveFrame will modify the FrameSet's \htmlref{Base}{Base} and/or
\htmlref{Current}{Current} attributes so that they continue to identify the same Frames
as previously. If either the base or current Frame is removed,
however, the corresponding attribute will become un-set, so that it
reverts to its default value (\secref{ss:baseandcurrentdefault}) and
therefore identifies an alternative Frame.

Note that it is quite permissible to remove any Frame from a FrameSet,
even although other Frames may appear to depend on it. For example, in
Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct
relationship between Frames~2 and 3 would still be preserved, although
they would be re-numbered as Frames~1 and 2.

\cleardoublepage
\section{\label{ss:fshigher}Higher Level Operations on FrameSets}

\subsection{\label{ss:framesetsfromconvert}Creating FrameSets with astConvert}

Before considering the important subject of using FrameSets to convert
between coordinate systems (\secref{ss:framesetconverting}), let us
return briefly to reconsider the output generated by \htmlref{astConvert}{astConvert}. We
used this function earlier (\secref{ss:introducingconversion}), when
converting between the coordinate systems represented by various kinds
of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the
coordinate conversion it identifies. We are now in a position to
examine the structure of this FrameSet.

Take our earlier example (\secref{ss:convertingskyframes}) of
converting between the celestial coordinate systems represented by two
SkyFrames:

\small
\begin{terminalv}
#include "ast.h"
AstFrameSet *cvt;
AstSkyFrame *skyframe1, *skyframe2;

...

skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" );
skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" );

cvt = astConvert( skyframe1, skyframe2, "" );
\end{terminalv}
\normalsize

   This will produce a pointer, ``cvt'', to the FrameSet shown in
   Figure~\ref{fig:fsconvert}.
   \begin{figure}[bhtp]
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/fsconvert}
   \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when astConvert is used to convert
   between the coordinate systems represented by two SkyFrames. The
   source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame
   becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the
   required conversion.}
   \label{fig:fsconvert}
   \end{center}
   \end{figure}

As can be seen, this FrameSet contains just two Frames.  The source
Frame supplied to astConvert becomes its base Frame, while the
destination Frame becomes its current Frame. (The FrameSet, of course,
simply holds pointers to these Frames, rather than making copies.) The
Mapping which relates the base Frame to the current Frame is the one
which implements the required conversion.

As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet
returned by astConvert may be used both as a Mapping and as a Frame to
perform most of the functions you are likely to need. However, the
Mapping may be extracted for use on its own if necessary, using
\htmlref{astGetMapping}{astGetMapping} (\secref{ss:extractingamapping}), for example:

\small
\begin{terminalv}
AstMapping *mapping;

...

mapping = astGetMapping( cvt, AST__BASE, AST__CURRENT );
\end{terminalv}
\normalsize

\subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems}

   We now consider the process of converting between the coordinate
   systems represented by two FrameSets. This is a most important
   operation, as a subsequent example (\secref{ss:registeringimages})
   will show, and is illustrated in Figure~\ref{fig:fsalign}.
   \begin{figure}
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/fsalign}
   \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion
   between two FrameSets is performed by establishing
   a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion
   between these two Frames is possible, then a route for converting
   between the current Frames of both FrameSets can also be found. In
   practice, there may be many ways of pairing Frames to find the
   ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to
   narrow the choice.}
   \label{fig:fsalign}
   \end{center}
   \end{figure}

Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave
like its current \htmlref{Frame}{Frame} when necessary, conversion between two
FrameSets is performed using \htmlref{astConvert}{astConvert}
(\secref{ss:convertingskyframes}), but supplying pointers to FrameSets
instead of Frames. The effect of this is to convert between the
coordinate systems represented by the current Frames of each FrameSet:

\small
\begin{terminalv}
AstFrameSet *frameseta, *framesetb;

...

cvt = astConvert( frameseta, framesetb, "SKY" );
\end{terminalv}
\normalsize

When using FrameSets, we are presented with considerably more
conversion options than when using Frames alone. This is because each
current Frame is related to all the other Frames in its respective
FrameSet. Therefore, if we can establish a link between any pair of
Frames, one from each FrameSet, we can form a complete conversion path
between the two current Frames (Figure~\ref{fig:fsalign}).

This expanded range of options is, of course, precisely the
intention. By connecting Frames together within a FrameSet, we have
extended the range of coordinate systems that can be reached from any
one of them.  We are therefore no longer restricted to converting
between Frames with the same Domain value (\secref{ss:framedomains}),
but can go \emph{via} a range of intermediate coordinate systems in
order to make the connection we require. Transformation between
different domains has therefore become possible because, in assembling
the FrameSets, we provided the additional information needed to
inter-relate them.

It is important to appreciate, however, that the choice of ``missing
link'' is crucial in determining the conversion that results.
Although each FrameSet may be perfectly self-consistent internally,
this does not mean that all conversion paths through the combined
network of Mappings are equivalent. Quite the contrary in fact:
everything depends on where the inter-connecting link between the two
FrameSets is made.  In practice, there may be a large number of
possible pairings of Frames and hence of possible links. Other factors
must therefore be used to restrict the choice. These are:

\begin{enumerate}
\item Not every possible pairing of Frames is legitimate. For example,
you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which
belong to different classes, so such pairings will be ignored.

\item In a similar way, you cannot convert directly between Frames
with different Domain values (\secref{ss:framedomains}). If the Domain
attribute is used consistently (typically only one Frame in each
FrameSet will have a particular Domain value), then this further
restricts the choice.

\item The third argument of astConvert may then be used to specify
explicitly which Domain value the paired Frames should have. You may
also supply a comma-separated list of preferences here (see below).

\item If the above steps fail to uniquely identify the link, then the
first suitable pairing of Frames is used, so that any ambiguity is
resolved by the order in which Frames are considered for pairing (see
the description of the astConvert function in
\appref{ss:functiondescriptions} for details of the search
order).\footnote{If you find that how this ambiguity is resolved
actually makes a difference to the conversion that results, then you
have probably constructed a FrameSet which lacks internal
self-consistency. For example, you might have two Frames representing
indistinguishable coordinate systems but inter-related by a non-null
\htmlref{Mapping}{Mapping}.}
\end{enumerate}

In the example above we supplied the string ``SKY'' as the third
argument of astConvert. This constitutes a request that a pair of
Frames with
the Domain value SKY (\emph{i.e.}\ representing celestial coordinate
systems) should be used to inter-relate the two FrameSets. Note that
this does not specify which celestial coordinate system to use, but is
a general request that the two FrameSets be inter-related using
coordinates on the celestial sphere.

Of course, it may be that this request cannot be met because there may
not be a celestial coordinate system in both FrameSets. If this is
likely to happen, we can supply a list of preferences, or a
\emph{domain search path},
as the third argument to astConvert, such as
the following:

\small
\begin{terminalv}
cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID," );
\end{terminalv}
\normalsize

Now, if the two FrameSets cannot be inter-related using the SKY domain,
astConvert will attempt to use the PIXEL domain instead. If this
also fails, it will try the GRID domain. A blank field in the domain
search path (here indicated by the final comma) allows any Domain
value to be used. This can be employed as a last resort when all else
has failed.

If astConvert succeeds in identifying a conversion, it will return a
pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the
source and destination Frames are inter-connected by the required
Mapping. In this case, of course, these Frames will be the current
Frames of the two FrameSets, but in all other respects the returned
FrameSet is the same as when converting between Frames.

Very importantly, however, astConvert may modify the FrameSets you are
converting between. It does this, in order to indicate which pairing
of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base}
attribute for each FrameSet so that the Frame used in the pairing
becomes its base Frame (\secref{ss:baseandcurrent}).

Finally, note that astConvert may also be used to convert between a
FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is
supplied for either the first or second argument, it will behave like
a FrameSet containing only a single Frame.

\subsection{\label{ss:registeringimages}Example---Registering Two Images}

Consider two images which have been calibrated by attaching FrameSets
to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the
raw data grid coordinates of each image (the GRID domain of
\secref{ss:domainconventions}). Suppose, also, that these FrameSets
contain an unknown number of other Frames, representing alternative
world coordinate systems.  What we wish to do is register these two
images, such that we can transform from a position in the data grid of
one into the corresponding position in the data grid of the other.
This is a very practical example because images will typically be
calibrated using FrameSets in precisely this way.

The first step will probably involve making a copy of both FrameSets
(using \htmlref{astCopy}{astCopy}---\secref{ss:copyingobjects}), since we will be
modifying them. Let ``frameseta'' and ``framesetb'' be pointers to
these copies. Since we want to convert between the base Frames of
these FrameSets (\emph{i.e.}\ their data grid coordinates), the next
step is to make these Frames current. This is simply done by inverting
both FrameSets, which interchanges their base and current
Frames. \htmlref{astInvert}{astInvert} will perform this task:

\small
\begin{terminalv}
astInvert( frameseta );
astInvert( framesetb );
\end{terminalv}
\normalsize

To identify the required conversion, we now use \htmlref{astConvert}{astConvert}, supplying
a suitable domain search path with which we would like our two images
to be registered:

\small
\begin{terminalv}
cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID" );
if ( cvt == AST__NULL ) {
   <no conversion was possible>
} else {
   <conversion was possible>
}
\end{terminalv}
\normalsize

The effects of this are:

\begin{enumerate}
\item astConvert first attempts to register the two images on the
celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it
searches for a celestial coordinate system, although not necessarily
the same one, attached to each image.  If it finds a suitable pair of
coordinate systems, it then registers the images by matching
corresponding positions on the sky.

\item If this fails, astConvert next tries to match positions in the
PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two
images will then be registered so that their corresponding pixel
positions correspond. If the PIXEL domain is offset from the data grid
(as typically happens in data reduction systems which implement a
``pixel origin''), then this will be correctly accounted for.

\item If this also fails, the GRID domain is finally used. This will
result in image registration by matching corresponding points in the
data grids used by both images. This means they will be
aligned so that the first element their data arrays correspond.

\item If all of the above fail, astConvert will return the value
AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned.
\end{enumerate}

The resulting ``cvt'' FrameSet may then be used directly
(\secref{ss:convertingskyframes}) to convert between positions in the
data grid of the first image and corresponding positions in the data
grid of the second image.

To determine which domain was used to achieve registration,
we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by
astConvert to indicate which intermediate Frames were used. We
can therefore simply invert either FrameSet (to make its base Frame
become the current one) and then enquire the \htmlref{Domain}{Domain} value:

\small
\begin{terminalv}
const char *domain;

...

astInvert( frameseta );
domain = astGetC( frameseta, "Domain" );
\end{terminalv}
\normalsize

If conversion was successful, the result will be one of the strings
``SKY'', ``PIXEL'' or ``GRID''.

\subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System}

As discussed earlier (\secref{ss:baseandcurrent}), an important
application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to
be attached to entities such as images in order to calibrate them. In
addition, one of the main objectives of AST is to simplify the
propagation of such information through successive stages of data
processing, so that it remains consistent with the associated image
data.

In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with
the image's data grid coordinates and its other Frames (if any) with
the various alternative world coordinate systems associated with the
image.  If the data processing being performed does not change the
relationship between the image's data grid coordinates and any of the
associated world coordinate systems, then propagation of the WCS
information is straightforward and simply involves copying the
FrameSet associated with the image.

If any of these relationships change, however, then corresponding
changes must be made to the way Frames within the FrameSet are
inter-related. By far the most common case occurs when the image
undergoes some geometrical transformation resulting in ``re-gridding''
on to another data grid, but the same principles can be applied to any
re-definition of a coordinate system.

To pursue the re-gridding example, we would need to modify our
FrameSet to account for the fact that the image's data grid coordinate
system (corresponding to the FrameSet's base Frame) has
changed. Looking at the steps needed in detail, we might proceed as
follows:

\begin{enumerate}
\item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the
original data grid coordinate system and the new one.

\item Obtain a Frame to represent the new data grid coordinate system
(we could re-use the original base Frame here, using \htmlref{astGetFrame}{astGetFrame} to
obtain a pointer to it).

\item Add the new Frame to the FrameSet, related to the original base
Frame by the new Mapping. This Frame now represents the new data grid
coordinate system and is correctly related to all the other Frames
present.\footnote{This is because any transformation to or from this
new Frame must go \emph{via} the base Frame representing the original
data grid coordinate system, which we assume was correctly related to
all the other Frames present.}

\item Remove the original base Frame (representing the old data grid
coordinate system).

\item Make the new Frame the base Frame and restore the original
current Frame.
\end{enumerate}

   The effect of these steps is to change the relationship between the
   base Frame and all the other Frames present. It is as if a new Mapping
   has been interposed between the Frame we want to alter and all the
   other Frames within the FrameSet (Figure~\ref{fig:fsremap}).
   \begin{figure}[hbtp]
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/fsremap}
\caption[Interposing a Mapping into a FrameSet]{The effect
   of \htmlref{astRemapFrame}{astRemapFrame} is to interpose a Mapping between
   a nominated Frame within a FrameSet and the remaining contents of the
   FrameSet. This effectively ``re-defines'' the coordinate system
   represented by the affected Frame. It may be used to compensate (say)
   for geometrical changes made to an associated image. The
   inter-relationships between all the other Frames within the FrameSet
   remain unchanged.}
   \label{fig:fsremap}
   \end{center}
   \end{figure}

Performing the steps above is rather lengthy, however, so the
astRemapFrame function is provided to perform all of these operations
in one go. A practical example of its use is given below
(\secref{ss:wcsprocessingexample}).

\subsection{\label{ss:wcsprocessingexample}Example---Binning an Image}

As an example of using \htmlref{astRemapFrame}{astRemapFrame}, consider a case where the pixels
of a 2-dimensional image have been binned 2$\times$2, so as to reduce
the image size by a factor of two in each dimension.  We must now
modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the
image. Much the same process would be needed for any other geometrical
change the image might undergo.

We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the
data grid coordinates in the original image to those in the new one:

\small
\begin{terminalv}
AstWinMap *winmap;
double ina[ 2 ] = { 0.5, 0.5 };
double inb[ 2 ] = { 2.5, 2.5 };
double outa[ 2 ] = { 0.5, 0.5 };
double outb[ 2 ] = { 1.5, 1.5 };

...

winmap = astWinMap( 2, ina, inb, outa, outb, "" );
\end{terminalv}
\normalsize

Here, we have simply set up arrays containing the data grid
coordinates of the bottom left and top right corners of the first
element in the output image (``outa'' and ``outb'') and the
corresponding coordinates in the input image (``ina'' and
``inb''). \htmlref{astWinMap}{astWinMap} then creates a WinMap which performs the required
transformation. We do not need to know the size of the image.

We can then pass this WinMap to astRemapFrame. This modifies the
relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in
the FrameSet, so that the base Frame represents the data grid
coordinate system of the new image rather than the old one:

\small
\begin{terminalv}
AstFrameSet *frameset;

...

astRemapFrame( frameset, AST__BASE, winmap );
\end{terminalv}
\normalsize

Any other coordinate systems described by the FrameSet, no matter how
many of these there might be, are now correctly associated with the
new image.

\subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets}

When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into
which you can place any combination of Frames and Mappings that you
wish. There are relatively few constraints on this process and no
checks are performed to see whether the FrameSet you construct makes
physical sense.  It is quite possible, for example, to construct a
FrameSet containing two identical SkyFrames which are inter-related by
a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes
no sense, because applying a non-unit Mapping to any set of celestial
coordinates cannot yield positions that are still in the original
coordinate system.  If you use such a FrameSet to perform coordinate
conversions, you are likely to get unpredictable results because the
information in the FrameSet is corrupt.

It is, of course, your responsibility as a programmer to ensure the
validity of any information which you insert into a
FrameSet. Normally, this is straightforward and simply consists of
formulating your problem correctly (a diagram can often help to
clarify how coordinate systems are inter-related) and writing the
appropriate bug-free code to construct the FrameSet. However, once you
start to modify an existing FrameSet, there are new opportunities for
corrupting it!

Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a
\htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute
simply by using \htmlref{astSet}{astSet} on the FrameSet, as follows:

\small
\begin{terminalv}
astSet( frameset, "Equinox=J2010" );
\end{terminalv}
\normalsize

The effect of this will be to change the celestial coordinate system
which the current Frame represents. You can see, however, that this
has the potential to make the FrameSet corrupt unless corresponding
changes are also made to the Mapping which relates this SkyFrame to
the other Frames within the FrameSet. In fact, it is a general rule
that any change to a FrameSet which affects its current Frame can
potentially require corresponding changes to the FrameSet's Mappings
in order to maintain its overall integrity.

Fortunately, once you have stored valid information in a FrameSet, AST
will look after these details for you automatically, so that the
FrameSet's integrity is maintained. In the example above, it would do
this by appropriately re-mapping the current Frame (as if
\htmlref{astRemapFrame}{astRemapFrame} had been used---\secref{ss:remapframe}) in response to
the use of astSet. One way of illustrating this process is as follows:

\small
\begin{terminalv}
AstSkyFrame *skyframe;

...

skyframe = astSkyFrame( "" );
frameSet = astFrameSet( skyframe );
astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe );
\end{terminalv}
\normalsize

This constructs a trivial FrameSet whose base and current Frames are
both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this
as a ``pipe'' connecting two coordinate systems. At present, these two
systems represent identical ICRS coordinates, so the FrameSet
implements a unit Mapping. We can change the coordinate system on the
current end of this pipe as follows:

\small
\begin{terminalv}
astSet( frameset, "System=Ecliptic, Equinox=J2010" );
\end{terminalv}
\normalsize

and the Mapping which the FrameSet implements would change
accordingly. To change the coordinate system on the base end of the
pipe, we might use:

\small
\begin{terminalv}
astInvert( frameset );
astSet( frameset, "System=Galactic" );
astInvert( frameset );
\end{terminalv}
\normalsize

The FrameSet would then convert between galactic and ecliptic
coordinates.

Note that astSet is not the only function which has this effect:
\htmlref{astClear}{astClear} behaves similarly, as also does \htmlref{astPermAxes}{astPermAxes}
(\secref{ss:permutingaxes}). If you need to circumvent this mechanism
for any reason, this can be done by going behind the scenes and
obtaining a pointer directly to the Frame you wish to modify. Consider
the following, for example:

\small
\begin{terminalv}
skyframe = astGetFrame( frameset, AST__CURRENT );
astSet( skyframe, "Equinox=J2010" );
skyframe = astAnnul( skyframe );
\end{terminalv}
\normalsize

Here, astSet is applied to the SkyFrame pointer rather than the
FrameSet pointer, so the usual checks on FrameSet integrity do not
occur. The SkyFrame's Equinox attribute will therefore be modified
without any corresponding change to the FrameSet's Mappings.  In this
case you must take responsibility yourself for maintaining the
FrameSet's integrity, perhaps through appropriate use of
astRemapFrame.

\subsection{Merging FrameSets}

   As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet}
   (\secref{ss:addingframes}), it is also possible to add complete sets of
   inter-related Frames which are contained within another
   FrameSet. This, of course, corresponds to the process of merging two
   FrameSets (Figure~\ref{fig:fsmerge}).
   \begin{figure}[hbtp]
   \begin{center}
   \includegraphics[width=0.7\textwidth]{sun211_figures/fsmerge}
   \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using
   \htmlref{astAddFrame}{astAddFrame}. FrameSet~B is being added to FrameSet~A by supplying a
   new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1)
   and the current Frame of B. In the merged FrameSet, the Frames
   contributed by B will be re-numbered to become Frames~4, 5 and 6. The
   base Frame will remain unchanged, but the current Frame of B becomes
   the new current Frame. Note that FrameSet~B itself is not
   altered by this process.}
   \label{fig:fsmerge}
   \end{center}
   \end{figure}



This process is performed by adding one FrameSet to another using
astAddFrame, in much the same manner as when adding a new Frame to an
existing FrameSet (\secref{ss:addingframes}). It is simply a matter of
providing a FrameSet pointer, instead of a Frame pointer, for the 4th
argument. In performing the merger you must, as usual, supply a
Mapping, but in this case the Mapping should relate the current Frame
of the FrameSet being added to one of the Frames already present. For
example, you might perform the merger shown in
Figure~\ref{fig:fsmerge} as follows:

\small
\begin{terminalv}
AstMapping *mapping;

...

astAddFrame( frameseta, 1, mapping, framesetb );
\end{terminalv}
\normalsize

The Frames acquired by ``frameseta'' from the FrameSet being added
(``framesetb'') are re-numbered so that they retain their original
order and follow on consecutively after the Frames that were already
present, whose indices remain unchanged. The base Frame of
``frameseta'' remains unchanged, but the current Frame of
``framesetb'' becomes its new current Frame. All the
inter-relationships between Frames in both FrameSets remain in place
and are preserved in the merged FrameSet.

Note that while this process modifies the first FrameSet
(``frameseta''), it leaves the original contents of the one being
added (``framesetb'') unchanged.

%\cleardoublepage
%\section{\label{ss:searching}TBW - Searching for Coordinate Systems}

\cleardoublepage
\section{\label{ss:channels}Saving and Restoring Objects (Channels)}

Facilities are provided by the AST library for performing input and
output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible
to write any Object into various external representations for
storage, and then to read these representations back in, so as to
restore the original Object. Typically, an Object would be written by
one program and read back in by another.

We refer to ``external representations'' in the plural because AST is
designed to function independently of any particular data storage
system. This means that Objects may need converting into a number of
different external representations in order to be compatible with
(say) the astronomical data storage system in which they will reside.

In this section, we discuss the basic I/O facilities which support
external representations based on a textual format referred to as the AST
``native format''. These are implemented using a new kind of Object---a
\htmlref{Channel}{Channel}. We will examine later how to use other representations, based on
an XML format or on the use of FITS headers, for storing Objects. These
are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan}
(\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}).

\subsection{The Channel Model}

The best way to start thinking about a \htmlref{Channel}{Channel} is like a C file
stream, and to think of the process of creating a Channel as that
of opening a file and obtaining a FILE pointer.  Subsequently, you can
read and write Objects \emph{via} the Channel.

This analogy is not quite perfect, however, because a Channel has, in
principle, two ``files'' attached to it. One is used when reading, and
the other when writing. These are termed the Channel's \emph{source}
and \emph{sink} respectively. In practice, the source and sink may
both be the same, in which case the analogy with the C file stream is
correct, but this need not always be so. It is not necessarily so with
the basic Channel, as we will now see (\secref{ss:creatingachannel}).

\subsection{\label{ss:creatingachannel}Creating a Channel}

The process of creating a \htmlref{Channel}{Channel} is straightforward. As you
might expect, it uses the constructor function \htmlref{astChannel}{astChannel}:

\small
\begin{terminalv}
#include "ast.h"
AstChannel *channel;

...

channel = astChannel( NULL, NULL, "" );
\end{terminalv}
\normalsize

The first two arguments to astChannel specify the external source and
sink that the Channel is to use. There arguments are pointers to C
functions and we will examine their use in more detail later
(\secref{ss:channelsource} and \secref{ss:channelsink}).

In this very simple example we have supplied NULL pointers for both
the source and sink functions. This requests the default behaviour,
which means that textual input will be read from the program's
standard input stream (typically, this means your keyboard) while
textual output will go to the standard output stream (typically
appearing on your screen). On UNIX systems, of course, either of these
streams can easily be redirected to files. This default behaviour can be
changed by assigning values to the Channel's \htmlref{SinkFile}{SinkFile} and/or \htmlref{SourceFile}{SourceFile}
attributes. These attributes specify the paths to text files that are to
be used in place of the standard input and output streams.

\subsection{\label{ss:writingtoachannel}Writing Objects to a Channel}

The process of saving Objects is very straightforward. You can
simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{astWrite}{astWrite}
function, as follows:

\small
\begin{terminalv}
int nobj;
AstObject *object;

...

nobj = astWrite( channel, object );
\end{terminalv}
\normalsize

The effect of this will be to produce a textual description of the
Object which will appear, by default, on your program's standard
output stream. Any class of Object may be converted into text in this
way.

astWrite returns a count of the number of Objects written. Usually,
this will be one, unless the Object supplied cannot be
represented. With a basic Channel all Objects can be represented, so a
value of one will always be returned unless there has been an
error. We will see later, however, that more specialised forms of
Channel may impose restrictions on the kind of Object you can write
(\secref{ss:foreignfitslimitations}). In such cases, astWrite may
return zero to indicate that the Object was not acceptable.

\subsection{\label{ss:readingfromachannel}Reading Objects from a Channel}

Before discussing the format of the output produced above
(\secref{ss:writingtoachannel}), let us consider how to read it back,
so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first
need to save the output in a file. We can do that either by using the
\htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output
to a file using a shell command like:

\small
\begin{terminalv}
program1 >file
\end{terminalv}
\normalsize

Within a subsequent program, we can read this Object back in by
using the \htmlref{astRead}{astRead} function, having first created a suitable
\htmlref{Channel}{Channel}:

\small
\begin{terminalv}
object = astRead( channel );
\end{terminalv}
\normalsize

By default, this function will read from the standard input stream
(the default source for a basic Channel), so we would need to ensure
that our second program reads its input from the file in which the
Object description is stored. On UNIX systems, we could again use a
shell redirection command such as:

\small
\begin{terminalv}
program2 <file
\end{terminalv}
\normalsize

Alternatively, we could have assigned a value to the SinkFile attribute
before invoking
astRead.

\subsection{Saving and Restoring Multiple Objects}

I/O operations performed on a basic \htmlref{Channel}{Channel} are sequential. This
means that if you write more than one \htmlref{Object}{Object} to a Channel,
each new Object's textual description is simply appended to the
previous one. You can store any number of Objects in this way,
subject only to the storage space you have available.

After you read an Object back from a basic Channel, the
Channel is ``positioned'' at the end of that Object's
textual description. If you then perform another read, you will
read the next Object's textual description and therefore
retrieve the next Object.  This process may be repeated to read
each Object in turn. When there are no more Objects to be
read, \htmlref{astRead}{astRead} will return the value AST\_\_NULL to indicate an
\emph{end-of-file}.

\subsection{\label{ss:validatinginput}Validating Input}

The pointer returned by \htmlref{astRead}{astRead} (\secref{ss:readingfromachannel}) could
identify any class of \htmlref{Object}{Object}---this is determined entirely by the
external data being read. If it is necessary to test for a particular
class (say a \htmlref{Frame}{Frame}), this may be done as follows using the appropriate
member of the \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$} family of functions:

\small
\begin{terminalv}
int ok;

...

ok = astIsAFrame( object );
\end{terminalv}
\normalsize

Note, however, that this will accept any Frame, so would be equally
happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}.  An alternative validation
strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute
and then test this character string, as follows:

\small
\begin{terminalv}
#include <string.h>

...

ok = !strcmp( astGetC( object, "Class" ), "Frame" );
\end{terminalv}
\normalsize

This would only accept a basic Frame and would reject a SkyFrame.

\subsection{Storing an ID String with an Object}

Occasionally, you may want to store a number of Objects and later
retrieve them and use each for a different purpose. If the Objects are
of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish
them when you read them back
(\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the
order in which they are stored is a possible solution, this becomes
complicated if some of the Objects are optional and may not always be
present. It also makes extending your data format in future more
difficult.

To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident}
attribute, both of which allows you, in effect, to attach a textual
identification label to it. You simply set the ID or Ident attribute before
writing the Object:

\small
\begin{terminalv}
astSet( object, "ID=Calibration" );
nobj = astWrite( channel, object );
\end{terminalv}
\normalsize

You can then test its value after you read the Object back:

\small
\begin{terminalv}
object = astRead( channel );
if ( !strcmp( astGetC( object, "ID" ), "Calibration" ) ) {
   <the Calibration Object has been read>
} else {
   <some other Object has been read>
}
\end{terminalv}
\normalsize

The only difference between the ID and Ident attributes is that the ID
attribute is unique to a particular Object and is lost if, for example,
you make a copy of the Object. The Ident attrubute, on the other hand, is
transferred to the new Object when a copy is made. Consequently, it is
safest to set the value of the ID attribute immediately before you
perform the write.

\subsection{\label{ss:textualoutputformat}The Textual Output Format}

Let us now examine the format of the textual output produced by
writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel}
(\secref{ss:writingtoachannel}). To give a concrete example, suppose
the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows:

\small
\begin{terminalv}
AstSkyFrame *skyframe;

...

nobj = astWrite( channel, skyframe );
\end{terminalv}
\normalsize

The output should then look like the following:

\small
\begin{terminalv}
 Begin SkyFrame 	# Description of celestial coordinate system
#   Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" 	# Title of coordinate system
    Naxes = 2 	# Number of coordinate axes
#   Domain = "SKY" 	# Coordinate system domain
#   Lbl1 = "Right Ascension" 	# Label for axis 1
#   Lbl2 = "Declination" 	# Label for axis 2
#   Uni1 = "hh:mm:ss.s" 	# Units for axis 1
#   Uni2 = "ddd:mm:ss" 	# Units for axis 2
#   Dir1 = 0 	# Plot axis 1 in reverse direction (hint)
    Ax1 = 	# Axis number 1
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
    Ax2 = 	# Axis number 2
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
 IsA Frame 	# Coordinate system description
    System = "FK4-NO-E" 	# Celestial coordinate system type
    Epoch = 1958 	# Besselian epoch of observation
#   Eqnox = 1950 	# Besselian epoch of mean equinox
 End SkyFrame
\end{terminalv}
\normalsize

You will notice that this output is designed both for a human reader,
in that it is formatted, and also to be read back by a computer in
order to reconstruct the SkyFrame. In fact, this is precisely the way
that \htmlref{astShow}{astShow} works (\secref{ss:displayingobjects}), this function being
roughly equivalent to the following use of a Channel:

\small
\begin{terminalv}
channel = astChannel( NULL, NULL, "" );
(void) astWrite( channel, object );
channel = astAnnul( channel );
\end{terminalv}
\normalsize

Some lines of the output start with a ``\verb?#?'' comment character,
which turns the rest of the line into a comment. These lines will be
ignored when read back in by \htmlref{astRead}{astRead}.  They typically contain default
values, or values that can be derived in some way from the other data
present, so that they do not actually need to be stored in order to
reconstruct the original Object. They are provided purely for human
information. The same comment character is also used to append
explanatory comments to most output lines.

It is not sensible to attempt a complete description of this output
format because every class of Object is potentially different and each
can define how its own data should be represented. However, there are
some basic rules, which mean that the following common features will
usually be present:

\begin{enumerate}
\item Each Object is delimited by matching ``Begin'' and ``End''
lines, which also identify the class of Object involved.

\item Within each Object description, data values are represented
by a simple ``keyword~$=$~value'' syntax, with one value to a line.

\item Lines beginning ``IsA'' are used to mark the divisions between
data belonging to different levels in the class hierarchy
(\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data
associated with the Frame class and the start of data associated with
some derived class (a SkyFrame in the above example). ``IsA'' lines
may be omitted if associated data values are absent and no confusion
arises.

\item Objects may contain other Objects as data. This is
indicated by an absent value, with the description of the data
Object following on subsequent lines.

\item Indentation is used to clarify the overall structure.
\end{enumerate}

Beyond these general principles, the best guide to what a particular
line of output represents will generally be the comment which
accompanies it together with a general knowledge of the class of
Object being described.

\subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output}

It is not always necessary for the output from \htmlref{astWrite}{astWrite}
(\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has
attributes that allow the amount of detail in the output to be
controlled.

The first of these is the integer attribute \htmlref{Full}{Full}, which controls the
extent to which optional, commented out, output lines are produced. By
default, Full is zero, and this results in the standard style of
output (\secref{ss:textualoutputformat}) where default values that may
be helpful to humans are included. To suppress these optional lines,
Full should be set to $-$1. This is most conveniently done when the
Channel is created, so that:

\small
\begin{terminalv}
channel = astChannel( NULL, NULL, "Full=-1" );
(void) astWrite( channel, skyframe );
channel = astAnnul( channel );
\end{terminalv}
\normalsize

would result in output containing only the essential information, such
as:

\small
\begin{terminalv}
 Begin SkyFrame 	# Description of celestial coordinate system
    Naxes = 2 	# Number of coordinate axes
    Ax1 = 	# Axis number 1
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
    Ax2 = 	# Axis number 2
       Begin SkyAxis 	# Celestial coordinate axis
       End SkyAxis
 IsA Frame 	# Coordinate system description
    System = "FK4-NO-E" 	# Celestial coordinate system type
    Epoch = 1958 	# Besselian epoch of observation
 End SkyFrame
\end{terminalv}
\normalsize

In contrast, setting Full to $+$1 will result in additional output
lines which will reveal every last detail of the \htmlref{Object}{Object}'s
construction. Often this will be rather more than you want, especially
for more complex Objects, but it can sometimes help when debugging
programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail:

\small
\begin{terminalv}
 Begin SkyFrame 	# Description of celestial coordinate system
#   RefCnt = 1 	# Count of active Object pointers
#   Nobj = 1 	# Count of active Objects in same class
 IsA Object 	# Astrometry Object
#   Nin = 2 	# Number of input coordinates
#   Nout = 2 	# Number of output coordinates
#   Invert = 0 	# Mapping not inverted
#   Fwd = 1 	# Forward transformation defined
#   Inv = 1 	# Inverse transformation defined
#   Report = 0 	# Don't report coordinate transformations
 IsA Mapping 	# Mapping between coordinate systems
#   Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" 	# Title of coordinate system
    Naxes = 2 	# Number of coordinate axes
#   Domain = "SKY" 	# Coordinate system domain
#   Lbl1 = "Right Ascension" 	# Label for axis 1
#   Lbl2 = "Declination" 	# Label for axis 2
#   Sym1 = "RA" 	# Symbol for axis 1
#   Sym2 = "Dec" 	# Symbol for axis 2
#   Uni1 = "hh:mm:ss.s" 	# Units for axis 1
#   Uni2 = "ddd:mm:ss" 	# Units for axis 2
#   Dig1 = 7 	# Individual precision for axis 1
#   Dig2 = 7 	# Individual precision for axis 2
#   Digits = 7 	# Default formatting precision
#   Fmt1 = "hms.1" 	# Format specifier for axis 1
#   Fmt2 = "dms" 	# Format specifier for axis 2
#   Dir1 = 0 	# Plot axis 1 in reverse direction (hint)
#   Dir2 = 1 	# Plot axis 2 in conventional direction (hint)
#   Presrv = 0 	# Don't preserve target axes
#   Permut = 1 	# Axes may be permuted to match
#   MinAx = 2 	# Minimum number of axes to match
#   MaxAx = 2 	# Maximum number of axes to match
#   MchEnd = 0 	# Match initial target axes
#   Prm1 = 1 	# Axis 1 not permuted
#   Prm2 = 2 	# Axis 2 not permuted
    Ax1 = 	# Axis number 1
       Begin SkyAxis 	# Celestial coordinate axis
#         RefCnt = 1 	# Count of active Object pointers
#         Nobj = 2 	# Count of active Objects in same class
       IsA Object 	# Astrometry Object
#         Label = "Angle on Sky" 	# Axis Label
#         Symbol = "delta" 	# Axis symbol
#         Unit = "ddd:mm:ss" 	# Axis units
#         Digits = 7 	# Default formatting precision
#         Format = "dms" 	# Format specifier
#         Dirn = 1 	# Plot in conventional direction
       IsA Axis 	# Coordinate axis
#         Format = "dms" 	# Format specifier
#         IsLat = 0 	# Longitude axis (not latitude)
#         AsTime = 0 	# Display values as angles (not times)
       End SkyAxis
    Ax2 = 	# Axis number 2
       Begin SkyAxis 	# Celestial coordinate axis
#         RefCnt = 1 	# Count of active Object pointers
#         Nobj = 2 	# Count of active Objects in same class
       IsA Object 	# Astrometry Object
#         Label = "Angle on Sky" 	# Axis Label
#         Symbol = "delta" 	# Axis symbol
#         Unit = "ddd:mm:ss" 	# Axis units
#         Digits = 7 	# Default formatting precision
#         Format = "dms" 	# Format specifier
#         Dirn = 1 	# Plot in conventional direction
       IsA Axis 	# Coordinate axis
#         Format = "dms" 	# Format specifier
#         IsLat = 0 	# Longitude axis (not latitude)
#         AsTime = 0 	# Display values as angles (not times)
       End SkyAxis
 IsA Frame 	# Coordinate system description
    System = "FK4-NO-E" 	# Celestial coordinate system type
    Epoch = 1958 	# Besselian epoch of observation
#   Eqnox = 1950 	# Besselian epoch of mean equinox
 End SkyFrame
\end{terminalv}
\normalsize

\subsection{\label{ss:channelcommenting}Controlling Commenting}

Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the
boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments
are appended to describe the purpose of each value. Comment has the
value 1 by default but, if set to zero, will suppress these
comments. This is normally appropriate only if you wish to minimise
the amount of output, for example:

\small
\begin{terminalv}
astSet( channel, "Full=-1, Comment=0" );
nobj = astWrite( channel, skyframe );
\end{terminalv}
\normalsize

might result in the following more compact output:

\small
\begin{terminalv}
 Begin SkyFrame
    Naxes = 2
    Ax1 =
       Begin SkyAxis
       End SkyAxis
    Ax2 =
       Begin SkyAxis
       End SkyAxis
 IsA Frame
    System = "FK4-NO-E"
    Epoch = 1958
 End SkyFrame
\end{terminalv}
\normalsize

\subsection{Editing Textual Output}

The safest advice about editing the textual output from \htmlref{astWrite}{astWrite} (or
\htmlref{astShow}{astShow}) is ``don't!''---unless you know what you are doing.

Having given that warning, however, it is sometimes possible to make
changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from
scratch, and to read the results back in to construct new
Objects. Normally, simple changes to numerical values are safest, but
be aware that this is a back door method of creating Objects, so
you are on your own! There are a number of potential pitfalls. In
particular:

\begin{itemize}
\item \htmlref{astRead}{astRead} is intended for retrieving data written by astWrite and
not for reading data input by humans. As such, the data validation
provided is very limited and is certainly not foolproof. This makes it
quite easy to construct Objects that are internally inconsistent by
this means. In contrast, the normal programming interface incorporates
numerous checks designed to make it impossible to construct invalid
Objects. You should not necessarily think you have found a bug if your
changes to an Object's textual description fail to produce the results
you expected!

\item In many instances the names associated with values in textual
output will correspond with Object attributes. Sometimes, however,
these names may differ from the attribute name. This is mainly because
of length restrictions imposed by other common external formats, such
as FITS headers. Some of the names used do not correspond with
attributes at all.

\item It is safest to change single numerical or string values.
Beware of changing the size or shape of Objects (\emph{e.g.}\ the
number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others
stored elsewhere within the Object and changing them in a haphazard
fashion will not produce useful results.

\item Be wary about un-commenting default values. Sometimes this will
work, but often these values are derived from other Objects stored
more deeply in the structure and the proper place to insert a new
value is not where the default itself appears.
\end{itemize}

\subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text}

By default, when you use \htmlref{astRead}{astRead} to read from a basic \htmlref{Channel}{Channel}
(\secref{ss:readingfromachannel}), it is assumed that you are reading a
stream of text containing only AST Objects, which follow each other
end-to-end. If any extraneous input data are encountered which do not
appear to form part of the textual description of an \htmlref{Object}{Object}, then an
error will result. In particular, the first input line must identify
the start of an Object description, so you cannot start reading half
way through an Object.

Sometimes, however, you may want to store AST Object descriptions
intermixed with other textual data. You can do this by setting the
Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every
read to skip over extraneous data until the start of a new AST Object
description, if any, is found. So long as your other data do not mimic
the appearance of an AST Object description, the two sets of data can
co-exist.

For example, by setting Skip to 1, the following complete C program
will read all the AST Objects whose descriptions appear in the source
of this document, ignoring the other text. \htmlref{astShow}{astShow} is used to display
those found:

\small
\begin{terminalv}
#include "ast.h"
main() {
   AstChannel *channel;
   AstObject *object;

   channel = astChannel( NULL, NULL, "Skip=1" );
   while ( ( object = astRead( channel ) ) != AST__NULL ) {
      astShow( object );
      object = astAnnul( object );
   }
   channel = astAnnul( channel );
}
\end{terminalv}
\normalsize

\subsection{\label{ss:channelsource}Reading Objects from Files}

Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel}
in reading and writing Objects through a program's standard input and
output streams. We will now consider how to access Objects stored in
files more directly.

The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of
the Channel. For instance, the following will read a pair of Objects from
a text file called ``fred.txt'':

\small
\begin{terminalv}
astSet( channel, "SourceFile=fred.txt" );
obj1 = astRead( channel );
obj2 = astRead( channel );
astClear( channel, "SourceFile" );
\end{terminalv}
\normalsize

Note, the act of clearing the attribute tells AST that no more Objects
are to be read from the file and so the file is then closed. If the
attribute is not cleared, the file will remain open and further Objects
can be read from it. The file will always be closed when the Channel is
deleted.

This simple approach will normally be sufficient. However, because the
AST library is designed to be used from more than one language, it has
to be a little careful about reading and writing to files. This is due
to incompatibilities that may exist between the file I/O facilities
provided by different languages. If such incompatibilities prevent the
above simple system being used, we need to adopt a system that off-loads
all file I/O to external code.

What this means in practice is that if the above simple approach cannot
be used, you must instead provide some simple C
functions that perform the actual transfer of data to and from files
and similar external data stores. The functions you provide are
supplied as the source and/or sink function arguments to \htmlref{astChannel}{astChannel}
when you create a Channel (\secref{ss:creatingachannel}). An example is
the best way to illustrate this.

Consider the following simple function called Source. It reads a
single line of text from a C input stream and returns a pointer to it,
or NULL if there is no more input:

\small
\begin{terminalv}
#include <stdio.h>
#define LEN 200
static FILE *input_stream;

const char *Source( void ) {
   static char buffer[ LEN + 2 ];
   return fgets( buffer, LEN + 2, input_stream );
}
\end{terminalv}
\normalsize

Note that the input stream is a static variable which we will also
access from our main program. This might look something like this
(omitting error checking for brevity):

\small
\begin{terminalv}
/* Open the input file. */
input_stream = fopen( "infile.ast", "r" );

/* Create a Channel and read an Object from it. */
channel = astChannel( Source, NULL, "" );
object = astRead( channel );

...

/* Annul the Channel and close the file when done. */
channel = astAnnul( channel );
(void) fclose( input_stream );
\end{terminalv}
\normalsize

Here, we first open the required input file, saving the resulting FILE
pointer. We then pass a pointer to our Source function as the first
argument to astChannel when creating a new Channel. When we read
an \htmlref{Object}{Object} from this Channel with \htmlref{astRead}{astRead}, the Source
function will be called to obtain the textual data from the file, the
end-of-file being detected when this function returns NULL.

Note, if a value is set for the SourceFile attribute,
the astRead function will ignore any source function
specified when the Channel was created.

\subsection{\label{ss:channelsink}Writing Objects to Files}

As for reading, writing Objects to files can be done in two different ways.
Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}.
For instance, the following will write a pair of Objects to a text file
called ``fred.txt'':

\small
\begin{terminalv}
astSet( channel, "SinkFile=fred.txt" );
nobj = astWrite( channel, object1 );
nobj = astWrite( channel, object2 );
astClear( channel, "SinkFile" );
\end{terminalv}
\normalsize

Note, the act of clearing the attribute tells AST that no more output
will be written to the file and so the file is then closed. If the
attribute is not cleared, the file will remain open and further Objects
can be written to it. The file will always be closed when the Channel is
deleted.

If the details of the language's I/O system on the computer you are using
means that the above approach cannot be used, then we can write a Sink function,
that writes a line of output text to a file, and use it in basically the same
way as the Source function in the previous section (\secref{ss:channelsource}):

\small
\begin{terminalv}
static FILE *output_stream;

void Sink( const char *line ) {
   (void) fprintf( output_stream, "%s\n", line );
}
\end{terminalv}
\normalsize

Note that we must supply the final newline character ourselves.

In this case, our main program would supply a pointer to this Sink
function as the second argument to \htmlref{astChannel}{astChannel}, as follows:

\small
\begin{terminalv}
/* Open the output file. */
output_stream = fopen( "outfile.ast", "w" );

/* Create a Channel and write an Object to it. */
channel = astChannel( Source, Sink, "" );
nobj = astWrite( channel, object );

   ...

/* Annul the Channel and close the file when done. */
channel = astAnnul( channel );
(void) fclose( output_stream );
\end{terminalv}
\normalsize

Note that we can specify a source and/or a sink function for the
Channel, and that these may use either the same file, or different
files according to whether we are reading or writing. AST has no
knowledge of the underlying file system, nor of file positioning. It
just reads and writes sequentially. If you wish, for example, to
reposition a file at the beginning in between reads and writes, then
this can be done directly (and completely independently of AST) using
standard C functions.

If an error occurs in your source or sink function, you can
communicate this to the AST library by setting its error status to any
error value using \htmlref{astSetStatus}{astSetStatus} (\secref{ss:errordetection}). This will
immediately terminate the read or write operation.

Note, if a value is set for the SinkFile attribute,
the \htmlref{astWrite}{astWrite} function will ignore any sink function
specified when the Channel was created.

\subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places}

It should be obvious from the above (\secref{ss:channelsource} and
\secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink functions
provide a flexible means of intercepting textual data that describes
AST Objects as it flows in and out of your program. In fact, you might
like to regard a Channel simply as a filter for converting AST Objects
to and from a stream of text which is then handled by your source and
sink functions, where the real I/O occurs.

This gives you the ability to store AST Objects in virtually any data
system, so long as you can convert a stream of text into something
that can be stored (it need no longer be text) and retrieve it
again. There is generally no need to retain comments.  Other
possibilities, such as inter-process and network communication, could
also be implemented \emph{via} source and sink functions in basically
the same way.

\cleardoublepage
\section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)}

A FITS header is a sequence of 80-character strings, formatted
according to particular rules defined by the Flexible Image Transport
\htmlref{System}{System}
(FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/}
is a widely-used standard for data interchange in astronomy and has
also been adopted as a data processing format in some astronomical
data reduction systems.  The individual 80-character strings in a FITS
header are usually called \emph{cards} or \emph{header cards} (for
entirely anachronistic reasons).

A sequence of FITS cards appears as a header at the start of every
FITS data file, and sometimes also at other points within it, and is
used to provide ancillary information which qualifies or describes the
main array of data stored in the file. As such, FITS headers are prime
territory for storing information about the coordinate systems
associated with data held in FITS files.

In this section, we will examine how to store information in FITS
headers directly in the form of AST Objects---a process which is
supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our
discussion here will turn out to be a transitional step that
emphasises the similarities between a FitsChan and a Channel
(\secref{ss:channels}). At the same time, it will prepare us for the
next section (\secref{ss:foreignfits}), where we will examine how to
use a FitsChan to tackle some of the more difficult problems that FITS
headers can present.

\subsection{\label{ss:nativeencoding}The Native FITS Encoding}

As it turns out, we are not the first to have thought of storing WCS
information in FITS headers. In fact, the original FITS standard (1981
vintage) defined a set of header keywords for this purpose which have
been widely used, although they have proved too limited for many
practical purposes.

At the time of writing, a number of different ways of using FITS
headers for storing WCS information are in use, most (although not
all) based on the original standard. We will refer to these
alternative ways of storing the information as FITS \emph{encodings}
but will defer a discussion of their advantages and limitations until
the next section (\secref{ss:foreignfits}).

Here, we will examine how to store AST Objects directly in FITS
headers. In effect, this defines a new encoding, which we will term
the \emph{native encoding}. This is a special kind of encoding,
because not only does it allow us to associate conventional
WCS calibration information with FITS data, but it also allows any other
information that can be expressed in terms of AST Objects to be stored
as well.  In fact, the native encoding provides us with facilities
roughly analogous to those of the \htmlref{Channel}{Channel}
(\secref{ss:channels})---\emph{i.e.}\ a lossless way of
transferring AST Objects from program to program---but based on FITS
headers instead of free-format text.

\subsection{The FitsChan Model}

I/O between AST Objects and FITS headers is supported by a specialised
form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which
may hold any number, including zero, of FITS header cards. This buffer
forms a workspace in which you can assemble FITS cards and manipulate
them before writing them out to a file.

By default, when a FitsChan is first created, it contains no cards and
there are five ways of inserting cards into it:

\begin{enumerate}
\item You may add cards yourself, one at a time, using \htmlref{astPutFits}{astPutFits}
(\secref{ss:addingfitscards}).

\item You may add cards yourself, supplying all cards concatenated into a
single string, using \htmlref{astPutCards}{astPutCards}
(\secref{ss:addingmulticards}).

\item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{astWrite}{astWrite}),
which will have the effect of creating new cards within the FitsChan
which describe the Object (\secref{ss:writingnativefits}).

\item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan.
The value should be the path to a text file holding a set of FITS header
cards, one per line. When the SourceFile value is set (using
astSetC or \htmlref{astSet}{astSet}),
the file is opened and the headers copied from it into the FitsChan.
The file is then immediately closed.

\item You may specify a source function which reads data from some
external store of FITS cards, just like the source associated with a
basic Channel (\secref{ss:channelsource}). If you supply a source
function, it will be called when the FitsChan is created in order to
fill it with an initial set of cards (\secref{ss:fitssourceandsink}).
\end{enumerate}

There are also four ways of removing cards from a FitsChan:

\begin{enumerate}
\item You may delete cards yourself, one at a time, using \htmlref{astDelFits}{astDelFits}
(\secref{ss:findingandchangingfits}).

\item You may read an AST Object from the FitsChan (using \htmlref{astRead}{astRead}),
which will have the effect of removing those cards from the FitsChan
which describe the Object (\secref{ss:readingnativefits}).

\item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When
the FitsChan is deleted, any remaining headers are written out to a text
file with path equal to the value of the SinkFile attribute.

\item Alternatively, you may specify a sink function which writes data to some
external store of FITS cards, just like the sink associated with a
basic Channel (\secref{ss:channelsink}). If you supply a sink function,
it will be called when the FitsChan is deleted in order to write out
any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note,
the sink function is not called if the SinkFile attribute has been set.
\end{enumerate}

Note, in particular, that reading an AST Object from a FitsChan is
\emph{destructive}. That is, it deletes the FITS cards that describe the
Object. The reason for this is explained in
\secref{ss:destructiveread}.

In addition to the above, you may also read individual cards from a
FitsChan using the function \htmlref{astFindFits}{astFindFits} (which is not
destructive). This is the main means of writing out FITS cards if you
have not supplied a sink function.  astFindFits also provides a means
of searching for particular FITS cards (by keyword, for example) and
there are other facilities for overwriting cards when required
(\secref{ss:findingandchangingfits}).

\subsection{\label{ss:creatingafitschan}Creating a FitsChan}

The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{astFitsChan}{astFitsChan}, is straightforward to
use:

\small
\begin{terminalv}
#include "ast.h"
AstFitsChan *fitschan;

...

fitschan = astFitsChan( NULL, NULL, "Encoding=NATIVE" );
\end{terminalv}
\normalsize

Here, we have omitted any source or sink functions by supplying NULL
pointers for the first two arguments.
We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to
NATIVE. This indicates that we will be using the native encoding
(\secref{ss:nativeencoding}) to store and retrieve Objects. If this
was left unspecified, the default would depend on the FitsChan's
contents. An attempt is made to use whatever encoding appears to have
been used previously. For an empty FitsChan, the default is NATIVE,
but it does no harm to be sure.

\subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan}

Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a
mechanism is needed for addressing them. This allows you to specify
where new cards are to be added, for example, or which card is to be
deleted.

This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which
gives the index of the \emph{current card} in the FitsChan.  You can
nominate any card you like to be current, simply by setting a new
value for the Card attribute, for example:

\small
\begin{terminalv}
int icard;

...

astSetI( fitschan, "Card", icard )
\end{terminalv}
\normalsize

where ``icard'' contains the index of the card on which you wish to
operate next.  Some functions will update the Card attribute as a
means of advancing through the sequence of cards, when reading them
for example, or to indicate which card matches a search criterion.

The default value for Card is one, which is the index of the first
card. This means that you can ``rewind'' a FitsChan to access its
first card by clearing the Card attribute:

\small
\begin{terminalv}
astClear( fitschan, "Card" );
\end{terminalv}
\normalsize

The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard}
attribute. This is a read-only attribute whose value is automatically
updated as you add or remove cards. It means you can address all the
cards in sequence using a loop such as the following:

\small
\begin{terminalv}
int ncard;

...

ncard = astGetI( fitschan, "Ncard" );
for ( icard = 1; icard <= ncard; icard++ ) {
   astSetI( fitschan, "Card", icard );
   <access the current card>
}
\end{terminalv}
\normalsize

However, it is usually possible to write slightly tidier loops based
on the \htmlref{astFindFits}{astFindFits} function described later
(\secref{ss:extractingfitscards} and
\secref{ss:findingandchangingfits}).

If you set the Card attribute to a value larger than Ncard, the
FitsChan is regarded as being positioned at its \emph{end-of-file}. In
this case there is no current card and an attempt to obtain a value
for the Card attribute will always return the value Ncard~$+$~1. When
a FitsChan is empty, it is always at the end-of-file.

\subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan}

Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you
can write any AST \htmlref{Object}{Object} to it in the native encoding using the
\htmlref{astWrite}{astWrite} function. Let us assume we are writing a
\htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet},
but for purposes of illustration a SkyFrame contains a more manageable
amount of data.} as follows:

\small
\begin{terminalv}
AstSkyFrame *skyframe;
int nobj;

...

nobj = astWrite( fitschan, skyframe );
\end{terminalv}
\normalsize

Since we have selected the native encoding
(\secref{ss:nativeencoding}), there are no restrictions on the class
of Object we may write, so astWrite should always return a value of
one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel}
(\secref{ss:writingtoachannel}), this write operation will not produce
any output from our program. The FITS headers produced are simply
stored inside the FitsChan.

After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to
reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card}
attribute will point at the card immediately after the last one
written. Since our FitsChan was initially empty, the Card attribute
will, in this example, point at the end-of-file
(\secref{ss:addressingfitscards}).

The FITS standard imposes a limit of 68 characters on the length of
strings which may be stored in a single header card. Sometimes, a
description of an AST Object involves the use of strings which exceed
this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If
this occurs, the long string will be split over two or more header cards.
Each ``continuation'' card will have the keyword \texttt{CONTINUE} in
columns 1 to 8, and will contain a space in column 9 (instead of the
usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of
each of the strings (except the last one) to indicate that the string is
continued on the next card.

Note, this splitting of long strings over several cards only occurs when
writing AST Objects to a FitsChan using the astWrite function and the
\emph{native} encoding. If a long string is stored in a FitsChan using
(for instance) the \htmlref{astPutFits}{astPutFits} or \htmlref{astPutCards}{astPutCards} function, it will simply be truncated.


\subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan}

To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame}
above (\secref{ss:writingnativefits}), we must write a simple loop to
extract each card in turn and print it out. We must also remember to
rewind the FitsChan first, \emph{e.g.}\ using \htmlref{astClear}{astClear}. The following
loop would do:

\small
\begin{terminalv}
#include <stdio.h>
char card[ 81 ];

...

astClear( fitschan, "Card" );
while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card );
\end{terminalv}
\normalsize

Here, we have used the \htmlref{astFindFits}{astFindFits} function to find a FITS card by
keyword. It is given a keyword template of ``\%f'', which matches any
FITS keyword, so it always finds the current card, which it
returns. Its fourth argument is set to 1, to indicate that the \htmlref{Card}{Card}
attribute should be incremented afterwards so that the following card
will be found the next time around the loop. astFindFits returns zero
when it reaches the end-of-file and this terminates the loop.

If we were storing the FITS headers in an output FITS file instead of
printing them out, we might use a loop like this but replace
``printf'' with a suitable data storage operation. This would only be
necessary if we had not provided a sink function for the FitsChan
(\secref{ss:fitssourceandsink}).

\subsection{The Native FitsChan Output Format}

If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote
earlier (\secref{ss:writingnativefits}), we should obtain something
like the following:

\small
\begin{terminalv}
COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST
COMMENT AST            Beginning of AST data for SkyFrame object             AST
COMMENT AST ................................................................ AST
BEGAST_A= 'SkyFrame'           / Description of celestial coordinate system
NAXES_A =                    2 / Number of coordinate axes
AX1_A   = '        '           / Axis number 1
BEGAST_B= 'SkyAxis '           / Celestial coordinate axis
ENDAST_A= 'SkyAxis '           / End of object definition
AX2_A   = '        '           / Axis number 2
BEGAST_C= 'SkyAxis '           / Celestial coordinate axis
ENDAST_B= 'SkyAxis '           / End of object definition
ISA_A   = 'Frame   '           / Coordinate system description
SYSTEM_A= 'FK4-NO-E'           / Celestial coordinate system type
EPOCH_A =               1958.0 / Besselian epoch of observation
ENDAST_C= 'SkyFrame'           / End of object definition
COMMENT AST ................................................................ AST
COMMENT AST               End of AST data for SkyFrame object                AST
COMMENT AST ---------------------------------------------------------------- AST
\end{terminalv}
\normalsize

As you can see, this resembles the information that would be written
to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame
(\secref{ss:textualoutputformat}), except that it has been formatted
into 80-character header cards according to FITS conventions.

There are also a number of other differences worth noting:

\begin{enumerate}
\item There is no unnecessary information about default values
provided for the benefit of the human reader. This is because the \htmlref{Full}{Full}
attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this
information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You
can restore the information if you wish by setting Full to 0 or $+$1,
in which case additional COMMENT cards will be generated to hold it.

\item The information is not indented, because FITS does not allow
this. However, if you change the Full attribute to 0 or $+$1, comments
will be included that are intended to help break up the sequence of
headers and highlight its structure. This will probably only be of use
if you are attempting to track down a problem by examining the FITS
cards produced in detail.

\item The FITS keywords which appear to the left of the ``$=$'' signs
have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to
them. This is done in order to make each keyword unique.
\end{enumerate}

This last point is worth further comment and is necessary because the
FITS standard only allows for certain keywords (such as COMMENT and
HISTORY) to appear more than once. \htmlref{astWrite}{astWrite} therefore appends an
arbitrary sequence of two characters to each new keyword it generates
in order to ensure that it does not duplicate any already present in
the FitsChan.

The main risk from not following this convention is that some software
might ignore (say) all but the last occurrence of a keyword before
passing the FITS headers on. Such an event is unlikely, but would
obviously destroy the information present, so astWrite enforces the
uniqueness of the keywords it uses. The extra characters added are
ignored when the information is read back.

As with a basic Channel, you can also suppress the comments produced
in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to
zero (\secref{ss:channelcommenting}). However, FITS headers are
traditionally generously commented, so this is not recommended.

\subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan}

To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back
as Objects for example, you should use the \htmlref{astPutFits}{astPutFits} function. You
can insert a card in front of the current one as follows:

\small
\begin{terminalv}
astPutFits( fitschan, card, 0 );
\end{terminalv}
\normalsize

where the third argument of zero indicates that the current card
should not be overwritten. Note that facilities are not provided by
AST for formatting the card contents.

After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the
original Card, or at the end-of-file if the FitsChan was originally
empty. Entering a sequence of cards is therefore straightforward. If
``cards'' is an array of pointers to strings containing FITS header
cards and ``ncards'' is the number of cards, then a loop such as the
following will insert the cards in sequence into a FitsChan:

\small
\begin{terminalv}
#define MAXCARD 100
char *cards[ MAXCARD ];
int ncard;

...

for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 );
\end{terminalv}
\normalsize

The string containing a card need not be null terminated if it is at
least 80 characters long (we have not allocated space for the strings
themselves in this brief example).

Note that astPutFits enforces the validity of a FitsChan by rejecting
any cards which do not adhere to the FITS standard. If any such cards
are detected, an error will result.

\subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan}

If you have all your cards concatenated together into a single long string,
each occupying 80 characters (with no delimiters), you can insert them
into a \htmlref{FitsChan}{FitsChan} in a single call using
\htmlref{astPutCards}{astPutCards}.
This call first empties the supplied FitsChan of any existing cards, then
inserts the new cards, and finally rewinds the FitsChan so that a
subsequent call to
\htmlref{astRead}{astRead}
will start reading from the first supplied card. The
astPutCards function uses \htmlref{astPutFits}{astPutFits}
internally to interpret and store each individual card, and so the
caveats in \secref{ss:addingfitscards} should be read.

For instance, if you are using the CFITSIO library for access to FITS
files, you can use the CFITSIO fits\_hdr2str function to obtain a string suitable
for passing to astPutCards:

\small
\begin{terminalv}


if( !fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) )
   fitschan = astFitsChan( NULL, NULL, "" );
   astPutCards( fitschan, header );
   header = free( header );
   wcsinfo = astRead( fitschan );

   ...
}
\end{terminalv}
\normalsize



\subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan}

Once you have stored a FITS header description of an \htmlref{Object}{Object} in a
\htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}),
you can read it back using \htmlref{astRead}{astRead} in much the same way as with a
basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments
about validating the Object you read also apply
(\secref{ss:validatinginput}).  If you have just written to the
FitsChan, you must remember to rewind it first:

\small
\begin{terminalv}
AstObject *object;

...

astClear( fitschan, "Card" );
object = astRead( fitschan );
\end{terminalv}
\normalsize

An important feature of a FitsChan is that read operations are
destructive. This means that if an Object description is found, it
will be consumed by astRead which will remove all the cards involved,
including associated COMMENT cards, from the FitsChan. Thus, if you
write an Object to a FitsChan, rewind, and read the same Object back,
you should end up with the original FitsChan contents.  If you need to
circumvent this behaviour for any reason, it is a simple matter to
make a copy of a FitsChan using \htmlref{astCopy}{astCopy}
(\secref{ss:copyingobjects}). If you then read from the copy, the
original FitsChan will remain untouched.

After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the
card immediately following the last card read, or the end-of-file of
there are no more cards.

Since the \emph{native} encoding is being used, any long strings involved
in the object description will have been split into two or more adjacent
contuation cards when the Object was stored in the header using function
\htmlref{astWrite}{astWrite}. The astRead function reverses this process by concatenating any
such adjacent continuation cards to re-create the original long string.


\subsection{Saving and Restoring Multiple Objects in a FitsChan}

When using the native FITS encoding, multiple Objects may be stored
and all I/O operations are sequential.  This means that you can simply
write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation,
the \htmlref{Card}{Card} attribute will be updated so that the next write appends the
next \htmlref{Object}{Object} description to the previous one.

If you then rewind the FitsChan, you can read the Objects back in the
original order. Reading them back will, of course, remove their
descriptions from the FitsChan (\secref{ss:readingnativefits}) but the
behaviour of the Card attribute is such that successive reads will
simply return each Object in sequence.

The only thing that may require care, given that a FitsChan can always
be addressed randomly by setting its Card attribute, is to avoid
writing one Object on top of another. For obvious reasons, the Object
descriptions in a FitsChan must remain separate if they are to make
sense when read back.

\subsection{Mixing Native Objects with Other FITS Cards}

Of course, any real FITS header will contain other information besides
AST Objects, if only the mandatory FITS cards that must accompany all
FITS data. When FITS headers are read in from a real dataset,
therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with
many other cards.

Because this is the normal state of affairs, the boolean (integer)
\htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when
you read an Object From a FitsChan, any irrelevant cards will simply
be skipped over until the start of the next Object description, if
any, is found. If you start reading part way through an Object
description, no error will result. The remainder of the description
will simply be skipped.

Setting Skip to zero will change this behaviour to resemble that of a
basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data
are not permitted by default, but this will probably rarely be useful.

\subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan}

You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by
keyword, using the function \htmlref{astFindFits}{astFindFits}. This performs a search,
starting at the current card, until it finds a card whose keyword
matches the template you supply, or the end-of-file is reached.

If a suitable card is found, astFindFits optionally returns the card's
contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to
identify the card found, or the one following it. The way you want the
Card attribute to be set is indicated by the final boolean (int)
argument to astFindFits. A value of one is returned to indicate
success.  If a suitable card cannot be found, astFindFits returns a
value of zero to indicate failure and sets the FitsChan's Card
attribute to the end-of-file.

Requesting that the Card attribute be set to indicate the card that
astFindFits finds is useful if you want to replace that card with a
new one, as in this example:

\small
\begin{terminalv}
char newcard[ 81 ];

...

(void) astFindFits( fitschan, "AIRMASS", NULL, 0 );
astPutFits( fitschan, newcard, 1 );
\end{terminalv}
\normalsize

Here, astFindFits is used to search for a card with the keyword
AIRMASS, with a NULL pointer being given to indicate that we do not
want the card's contents returned. If the card is found, \htmlref{astPutFits}{astPutFits}
then overwrites it with a new card.  Otherwise, the Card attribute
ends up pointing at the end-of-file and the new card is simply
appended to the end of the FitsChan.

A similar approach can be used to delete selected cards from a
FitsChan using \htmlref{astDelFits}{astDelFits}, which deletes the current card:

\small
\begin{terminalv}
if ( astFindFits( fitschan, "BSCALE", NULL, 0 ) ) astDelFits( fitschan );
\end{terminalv}
\normalsize

This deletes the first card, if any, with the BSCALE keyword.

Requesting that astFindFits increments the Card attribute to identify
the card following the one found is more useful when writing loops.
For example, the following loop extracts each card whose keyword
matches the template ``CD\%6d'' (that is, ``CD'' followed by six
decimal digits):

\small
\begin{terminalv}
while ( astFindFits( fitschan, "CD%6d", card, 1 ) {
   <process the card's contents>
}
\end{terminalv}
\normalsize

For further details of keyword templates, see the description of
astFindFits in \appref{ss:functiondescriptions}.

\subsection{\label{ss:fitssourceandsink}Source and Sink Functions for FitsChans}

The use of source and sink functions with a \htmlref{FitsChan}{FitsChan} is optional. This
is because you can always arrange to explicitly fill a FitsChan with
FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards})
and you can also extract any
cards that remain and write them out yourself
(\secref{ss:extractingfitscards}) before you delete the FitsChan.

If you choose to use these functions, however, they behave in a very
similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource}
and \secref{ss:channelsink}). You supply pointers to these functions,
as arguments to the constructor function \htmlref{astFitsChan}{astFitsChan} when you create
the FitsChan (\secref{ss:creatingafitschan}). The source function is
invoked implicitly at this point to fill the FitsChan with FITS cards
and the FitsChan is then rewound, so that the first card becomes
current. The sink function is automatically invoked later, when the
FitsChan is deleted, in order to write out any cards that remain in
it.

The only real difference between the source and sink functions for a
FitsChan and a basic Channel is that FITS cards are limited in length
to 80~characters, so the choice of buffer size is simplified.  The
``Source'' and ``Sink'' functions in \secref{ss:channelsource} and
\secref{ss:channelsink} could therefore be used to access FITS headers
stored in text files simply by changing LEN to be 80.  If you were not
accessing a text file, however, appropriate changes to the I/O
statements would be needed since the separating newline characters
would be absent. The details obviously depend on the format of the
file you are handling, which need not necessarily be a true FITS file.


\cleardoublepage
\section{\label{ss:foreignfits}Using Foreign FITS Encodings}

We saw in the previous section (\secref{ss:nativefits}) how to store
and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a
\htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to
NATIVE. However, the Objects we wrote could then only be read back by
other programs that use AST.

In practice, we will also encounter FITS headers containing WCS
information written by other software systems.  We will probably also
need to write FITS headers in a format that can be understood by these
systems. Indeed, this interchange of data is one of the main reasons
for the existence of FITS, so in this section we will examine how to
accommodate these requirements.

\subsection{\label{ss:foreignencodings}The Foreign FITS Encodings}

As mentioned previously (\secref{ss:nativeencoding}), there are a
number of conventions currently in use for storing WCS information in
FITS headers, which we call \emph{encodings}. Here, we are concerned
with those encodings defined by software systems other than AST, which
we term \emph{foreign encodings}.

Currently, AST supports six foreign encodings, which may be selected
by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the
following (character string) values:

\begin{quote}
\begin{description}
\item[DSS]\mbox{}\\
This encoding stores WCS information using the convention developed at
the Space Telescope Science Institute for the Digitised Sky Survey
(DSS) astrometric plate calibrations.  DSS images which use this
convention are widely available and it is understood by a number of
important and well-established astronomy applications.

However, the calibration model used (based on a polynomial fit) is not
easily applicable to other types of data and creating the polynomial
coefficients needed to calibrate your own images can prove
difficult. For this reason, the DSS encoding is probably best viewed
as a ``read-only'' format. It is possible, however, to read in WCS
information using this encoding and then to write it back out again,
so long as only minor changes have been made.

\item[FITS-WCS]\mbox{}\\
This encoding is very important because it is based on a new FITS standard
which should, for the first time, address the problem of celestial coordinate
systems in a proper manner, by considerably extending the original FITS
standard.

The conventions used are described in a series of papers by
E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the
``FITS-WCS papers''. They are described at
\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers
in this series have been agreed, this encoding should be understood by any
FITS-WCS compliant software and it is likely to be adopted widely for FITS
data in future.  For details of the coverage of these conventions provided
by the FitsChan class, see \appref{ss:fitswcscoverage}.

\item[FITS-IRAF]\mbox{}\\
This encoding is based on the conventions described in the document
``World Coordinate Systems Representations Within the FITS Format'' by R.J.
Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from
fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed
by the IRAF data analysis facility, so its use will facilitate data
exchange with IRAF. This encoding is in effect a sub-set of the current
FITS-WCS encoding.

\item[FITS-PC]\mbox{}\\
This encoding is based on a previous version of the proposed new FITS WCS
standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe
axis rotation and scaling. Versions of AST prior to V1.5 used this scheme
for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j}
keywords instead.\footnote{There are many other differences between the
previous and the current FITS-WCS encodings. The keywords to describe
axis rotation and scaling is used purely as a label to identify the
scheme.} The FITS-PC encoding is included in AST V1.5 only to allow
FITS-WCS data created with previous versions to be read. It should not,
in general, be used to create new data sets.

\item[FITS-AIPS]\mbox{}\\
This encoding is based on the conventions described in the document
``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th
September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu
/fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS
data analysis facility, so its use will facilitate data exchange with
AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to
describe axis rotation and scaling.

\item[FITS-AIPS++]\mbox{}\\
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-PC and FITS-IRAF.
\end{description}
\end{quote}

For more detail about the above encodings, see the description of the
Encoding attribute in \appref{ss:attributedescriptions}.

\subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings}

The foreign encodings available for storing WCS information in FITS
headers have a number of limitations when compared with the native
encoding of AST Objects (\secref{ss:nativefits}). The main ones are:

\begin{enumerate}
\item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented
using a foreign FITS encoding. This should not come as a surprise,
because the purpose of storing WCS information in FITS headers is to
attach coordinate systems to an associated array of data. Since the
FrameSet is the AST Object designed for the same purpose
(\secref{ss:baseandcurrent}), there is a natural correspondence.

The way in which a FrameSet is translated to and from the foreign
encoding also follows from this correspondence. The FrameSet's base
\htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS
data. These are the same as FITS pixel coordinates, in which the first
pixel (in 2 dimensions) has coordinates (1,1) at its
centre. Similarly, the current Frame of the FrameSet identifies the
FITS world coordinate system associated with the data.

\item You may store a representation of only a single FrameSet in any
individual set of FITS header cards (\emph{i.e.}\ in a single
\htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may
over-write the previous one or generate an invalid representation of
your WCS information.

This is mainly a consequence of the use of fixed FITS keywords by
foreign encodings and the fact that you cannot, in general, have
multiple FITS cards with the same keyword.

\item In general, it will not be possible to store every possible
FrameSet that you might construct. Depending on the encoding, only
certain FrameSets that conform to particular restrictions can be
represented and, even then, some of their information may be lost. See
the description of the \htmlref{Encoding}{Encoding} attribute in
\appref{ss:attributedescriptions} for more details of these
limitations.
\end{enumerate}

It should be understood that using foreign encodings to read and write
information held in AST Objects is essentially a process of converting
the data format. As such, it potentially suffers from the same
problems faced by all such processes, \emph{i.e.}\ differences between
the AST data model and that of the foreign encoding may cause some
information to be lost.  Because the AST model is extremely flexible,
however, any data loss can largely be eliminated when reading.
Instead, this effect manifests itself in the form of the above
encoding-dependent restrictions on the kind of AST Objects which may
be written.

One of the aims of the AST library, of course, is to insulate you from
the details of these foreign encodings and the restrictions they
impose. We will see shortly, therefore, how AST provides a mechanism
for determining whether your WCS information satisfies the necessary
conditions and allows you to make an automatic choice of which
encoding to use.

\subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input}

Let us now examine the practicalities of extracting WCS information
from a set of FITS header cards which have been written by some other
software system. We will pretend that our program does not know which
encoding has been used for the WCS information and must discover this
for itself. In order to have a concrete example, however, we will use
the following set of cards. These use the FITS-AIPS encoding and
contain a typical mix of other FITS cards which are irrelevant to the
WCS information in which we are interested:

\small
\begin{terminalv}
SIMPLE  =                    T / Written by IDL:  30-Jul-1997 05:35:42.00
BITPIX  =                  -32 / Bits per pixel.
NAXIS   =                    2 / Number of dimensions
NAXIS1  =                  300 / Length of x axis.
NAXIS2  =                  300 / Length of y axis.
CTYPE1  = 'GLON-ZEA'           / X-axis type
CTYPE2  = 'GLAT-ZEA'           / Y-axis type
CRVAL1  =           -149.56866 / Reference pixel value
CRVAL2  =           -19.758201 / Reference pixel value
CRPIX1  =              150.500 / Reference pixel
CRPIX2  =              150.500 / Reference pixel
CDELT1  =             -1.20000 / Degrees/pixel
CDELT2  =              1.20000 / Degrees/pixel
CROTA1  =              0.00000 / Rotation in degrees.
SURVEY  = 'COBE DIRBE'
BUNITS  = 'MJy/sr  '           /
ORIGIN  = 'CDAC    '           / Cosmology Data Analysis Center
TELESCOP= 'COBE    '           / COsmic Background Explorer satellite
INSTRUME= 'DIRBE   '           / COBE instrument [DIRBE, DMR, FIRAS]
PIXRESOL=                    9 / Quad tree pixel resolution [6, 9]
DATE    = '27/09/94'           / FITS file creation date (dd/mm/yy)
DATE-MAP= '16/09/94'           / Date of original file creation (dd/mm/yy)
COMMENT     COBE specific keywords
DATE-BEG= '08/12/89'           / date of initial data represented (dd/mm/yy)
DATE-END= '25/09/90'           / date of final data represented   (dd/mm/yy)
\end{terminalv}
\normalsize

The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into
it. If ``cards'' is an array of pointers to character strings holding
the header cards and ``ncards'' is the number of cards, this could be
done as follows:

\small
\begin{terminalv}
#include "ast.h"
#define MAXCARD 100
AstFitsChan *fitschan;
char *cards[ MAXCARD ];
int icard, ncard;

...

fitschan = astFitsChan( NULL, NULL, "" );
for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 );
\end{terminalv}
\normalsize

Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the
FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to
use the native encoding. This is because we are pretending not to know
which encoding to use and want AST to determine this for us. By
leaving the Encoding attribute un-set, its default value will adjust
to whichever encoding AST considers to be most appropriate, according
to the FITS header cards present. For details of how this choice is
made, see the description of the Encoding attribute in
\appref{ss:attributedescriptions}.

This approach has the obvious advantages of making our program simpler
and more flexible and of freeing us from having to know about the
different encodings available. As a bonus, it also means that the
program will be able to read any new encodings that AST may support in
future, without needing to be changed.

At this point, we could enquire the default value of the Encoding
attribute, which indicates which encoding AST intends to use, as
follows:

\small
\begin{terminalv}
const char *encode;

...


encode = astGetC( fitschan, "Encoding" );
\end{terminalv}
\normalsize

The result of this enquiry would be the string ``FITS-AIPS''.  Note
that we could also have set the FitsChan's Encoding attribute
explicitly, such as when creating it:

\small
\begin{terminalv}
fitschan = astFitsChan( NULL, NULL, "Encoding=FITS-AIPS" );
\end{terminalv}
\normalsize

If we tried to read information using this encoding
(\secref{ss:readingforeignfits}), but failed, we could then change the
encoding and try again.  This would allow our program to take control
of how the optimum choice of encoding is arrived at. However, it would
also involve using explicit knowledge of the encodings available and
this is best avoided if possible.

\subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header}

Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined
how the WCS information is encoded
(\secref{ss:identifyingfitsencoding}), the next step is to read an AST
\htmlref{Object}{Object} from the FitsChan using \htmlref{astRead}{astRead}. We must also remember to
rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card}
attribute, which defaults to 1:

\small
\begin{terminalv}
AstObject *wcsinfo;

...

astClear( fitschan, "Card" );
wcsinfo = astRead( fitschan );
\end{terminalv}
\normalsize

If the pointer returned by astRead is not equal to AST\_\_NULL, then
an Object has been read successfully. Otherwise, there was either no
information to read or the choice of FITS encoding
(\secref{ss:identifyingfitsencoding}) was inappropriate.

At this point you might like to indulge in a little data validation
along the lines described in \secref{ss:validatinginput}, for example:

\small
\begin{terminalv}
if ( !strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) {
   <the Object is a FrameSet, so use it>
} else {
   <something unexpected was read>
}
\end{terminalv}
\normalsize

If a foreign encoding has definitely been used, then the Object will
automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so
this stage can be omitted. However, if the native encoding
(\secref{ss:nativeencoding}) might have been employed, which is a
possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then
any class of Object might have been read and a quick check would be
worthwhile.

If you used \htmlref{astShow}{astShow} (\secref{ss:displayingobjects}) to examine the
FrameSet which results from reading our example FITS header
(\secref{ss:identifyingfitsencoding}), you would find that its base
\htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its
current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These
two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which
incorporates the effects of various rotations, scalings and a
``zenithal equal area'' sky projection, so that each pixel of the FITS
image is mapped on to a corresponding sky position in galactic
coordinates.

Because this FrameSet may be used both as a Mapping
(\secref{ss:framesetasmapping}) and as a Frame
(\secref{ss:framesetasframe}), it may be employed directly to perform
many useful operations without any need to decompose it into its
component parts. These include:

\begin{itemize}
\item Transforming data grid (FITS pixel) coordinates into galactic
coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}).

\item Formatting coordinate values (either pixel or galactic
coordinates) ready for display to a user
(\secref{ss:formattingaxisvalues} and \secref{ss:normalising}).

\item Enquiring about axis labels (or other axis
information---\secref{ss:frameattributes}) which might be used, for
example, to label columns of coordinates in a table
(\secref{ss:frameaxisattributes}).

\item Aligning the image with another image from which a similar
FrameSet has been obtained (\secref{ss:registeringimages}).

\item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay
a variety of graphical information (including a coordinate
grid---Figure~\ref{fig:gridplot}) on the displayed image.

\item Generating a new FrameSet which reflects any geometrical
processing you perform on the associated image data
(\secref{ss:wcsprocessingexample}). This new FrameSet could then be
written out as FITS headers to describe the modified image
(\secref{ss:writingforeignfits}).
\end{itemize}

If the FrameSet contains other Frames (apart from the base and current
Frames), then you would also have access to information about other
coordinate systems associated with the image.

\subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read}

It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan}
after we have read a \htmlref{FrameSet}{FrameSet} from it
(\secref{ss:readingforeignfits}). The following would rewind our
FitsChan and display its contents:

\small
\begin{terminalv}
#include <stdio.h>
char card[ 81 ];

...

astClear( fitschan, "Card" );
while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card );
\end{terminalv}
\normalsize

The output, if we started with the example FITS header in
\secref{ss:identifyingfitsencoding}, might look like this:

\small
\begin{terminalv}
SIMPLE  =                    T /  Written by IDL:  30-Jul-1997 05:35:42.00
BITPIX  =                  -32 /  Bits per pixel.
NAXIS   =                    2 /  Number of dimensions
NAXIS1  =                  300 /  Length of x axis.
NAXIS2  =                  300 /  Length of y axis.
SURVEY  = 'COBE DIRBE'
BUNITS  = 'MJy/sr  '
ORIGIN  = 'CDAC    '           /  Cosmology Data Analysis Center
TELESCOP= 'COBE    '           /  COsmic Background Explorer satellite
INSTRUME= 'DIRBE   '           /  COBE instrument [DIRBE, DMR, FIRAS]
PIXRESOL=                    9 /  Quad tree pixel resolution [6, 9]
DATE    = '27/09/94'           /  FITS file creation date (dd/mm/yy)
DATE-MAP= '16/09/94'           /  Date of original file creation (dd/mm/yy)
COMMENT     COBE specific keywords
DATE-BEG= '08/12/89'           /  date of initial data represented (dd/mm/yy)
DATE-END= '25/09/90'           /  date of final data represented   (dd/mm/yy)
\end{terminalv}
\normalsize

Comparing this with the original, you can see that all the FITS cards
that represent WCS information have been removed. They have
effectively been ``sucked out'' of the FitsChan by the destructive
read that \htmlref{astRead}{astRead} performs and converted into an equivalent
FrameSet. AST remembers where they were stored, however, so that if we
later write WCS information back into the FitsChan
(\secref{ss:writingforeignfits}) they will, as far as possible, go
back into their original locations. This helps to preserve the overall
layout of the FITS header.

You can now see why astRead performs destructive reads. It is a
mechanism for removing WCS information from a FITS header while
insulating you, as a programmer, from the details of the encoding
being used. It means you can ensure that all relevant header cards
have been removed, giving you a clean slate, without having to know
which FITS keywords any particular encoding uses.

Clearing this WCS information out of a FITS header is particularly
important when considering how to write new WCS information back after
processing (\secref{ss:writingforeignfits}). If any relevant FITS
cards are left over from the input dataset and find their way into the
new processed header, they could interfere with the new information
being written.\footnote{This can happen if a particular keyword is
present in the input header but is not used in the output header
(whether particular keywords are used can depend on the WCS
information being stored). In such a case, the original value would
not be over-written by a new output value, so would remain erroneously
present.} The destructive read mechanism ensures that this doesn't
happen.

\subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps}

One of the purposes of AST is to make it feasible to propagate WCS
information through successive stages of data processing, so that it
remains consistent with the associated image data. As far as possible,
this should happen regardless of the FITS encoding used to store the
original WCS information.

If the data processing being performed does not change the
relationship between image pixel and world coordinates (whatever these
may be), then propagation of the WCS information is
straightforward. You can simply copy the FITS header from input to
output.

If this relationship changes, however, then the WCS information must
be processed alongside the image data and a new FITS header generated
to represent it. In this case, the sequence of operations within your
program would probably be as follows:

\begin{enumerate}
\item Read the image data and associated FITS header from the input
dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan}
(\secref{ss:identifyingfitsencoding}).

\item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically
using a foreign FITS encoding---\secref{ss:readingforeignfits}).

\item Process the image data and modify the FrameSet accordingly
(\emph{e.g.}~\secref{ss:wcsprocessingexample}).

\item Write the FrameSet back into the FitsChan
(\secref{ss:writingforeignfits}).

\item Perform any other modification of FITS header cards your program
may require.

\item Write the FitsChan contents (\emph{i.e.}\ processed header
cards) and image data to the output dataset.
\end{enumerate}

In stage (2), the original WCS information will be removed from the
FitsChan by a destructive read. Later, in stage (4), new WCS
information is written to replace it. This is the process which we
consider next (\secref{ss:writingforeignfits}).

\subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header}

Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back
into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS
encoding to use.  Unfortunately, we cannot simply depend on the
default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the
input information (\secref{ss:identifyingfitsencoding}), because the
destructive action of reading the WCS data
(\secref{ss:destructiveread}) will have altered the FitsChan's
contents. This, in turn, will have changed the choice of default
encoding, probably causing it to revert to NATIVE.

We will return to the question of the optimum choice of encoding
below.  For now, let's assume that we want to use the same encoding
for output as we used for input. Since we enquired what that was
before we read the input WCS data from the FitsChan
(\secref{ss:identifyingfitsencoding}), we can now set that value
explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at
the same time (because the write will fail if the FitsChan is not
rewound). \htmlref{astWrite}{astWrite} can then be used to write the output WCS
information into the FitsChan:

\small
\begin{terminalv}
int nobj;

...

astSet( fitschan, "Card=1, Encoding=%s", encode );
nobj = astWrite( fitschan, wcsinfo );
\end{terminalv}
\normalsize

The value returned by astWrite (assigned to ``nobj'') indicates how
many Objects were written. This will either be 1 or zero. A value of
zero is used to indicate that the information could not be encoded in
the form you requested. If this happens, nothing will have been
written.

If your choice of encoding proves inadequate, the probable reason is
that the changes you have made to the FrameSet have caused it to
depart from the data model which the encoding assumes.  AST knows
about the data model used by each encoding and will attempt to
simplify the FrameSet you provide so as to fit into that model, thus
relieving you of the need to understand the details and limitations of
each encoding yourself.\footnote{Storing values in the FitsChan for
FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels),
before invoking
astWrite
can sometimes help to produce a successful write.} When this attempt fails,
however, you must consider what alternative encoding to use.

Ideally, you would probably want to try a sequence of alternative
encodings, using an approach such as the following:

\small
\begin{terminalv}
/* 1. */
astSet( fitschan, "Card=1, Encoding=FITS-IRAF" );
if ( !astWrite( fitschan, wcsinfo ) ) {

/* 2. */
   astSetC( fitschan, "Encoding", encode );
   if ( !astWrite( fitschan, wcsinfo ) ) {

/* 3. */
      astSet( fitschan, "Encoding=NATIVE" );
      (void) astWrite( fitschan, wcsinfo );
   }
}
\end{terminalv}
\normalsize

That is:

\begin{enumerate}
\item Start by trying the FITS-WCS encoding, on the grounds that FITS
should provide a universal interchange standard in which all WCS
information should be expressed if possible.

\item If that fails, then try the original encoding used for the input
WCS information, on the grounds that you are at least not making the
information any harder for others to read than it originally was.

\item If that also fails, then you are probably trying to store fairly
complex information for which you need the native encoding. Only other
AST programs will then be able to read this information, but these are
probably the only programs that will be able to do anything sensible
with it anyway.
\end{enumerate}

An alternative approach might be to encode the WCS information in several
ways, since this gives the maximum chance that other software will be
able to read it. This approach is only possible if there is no
significant conflict between the FITS keywords used by the different
encodings\footnote{In practice, this means you should avoid mixing
FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share
many keywords.}.  Adopting this approach would simply require multiple
calls to astWrite, rewinding the FitsChan and changing its Encoding value
before each one.

Unfortunately, however, there is a drawback to duplicating WCS
information in the FITS header in this way, because any program which
modifies one version of this information and simply copies the
remainder of the header will risk producing two inconsistent sets of
information. This could obviously be confusing to subsequent
software. Whether you consider this a worthwhile risk probably depends
on the use to which you expect your data to be put.

\cleardoublepage
\section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)}

\htmladdnormallinkfoot{XML}{http://www.w3.org/XML/}
is fast becoming the standard format for passing structured data around
the internet, and much general purpose software has been written for
tasks such as the parsing, editing, display and transformation of XML
data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides
facilities for storing AST objects externally in the form of XML documents,
thus allowing such software to be used.

The primary XML format used by the XmlChan class is a fairly close
transliteration of the AST native format produced by the basic Channel
class. Currently, there is no DTD or schema defining the structure of data
produced in this format by an XmlChan. The following is a native AST
representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full}
attribute set to zero so that some default attribute values are included
as extra comments):

\small
\begin{terminalv}
 Begin Frame    # Coordinate system description
#   Title = "1-d coordinate system"     # Title of coordinate system
    Naxes = 1   # Number of coordinate axes
    Domain = "SCREEN"   # Coordinate system domain
#   Lbl1 = "Axis 1"     # Label for axis 1
#   Uni1 = "cm"         # Units for axis 1
    Ax1 =       # Axis number 1
       Begin Axis       # Coordinate axis
          Unit = "cm"   # Axis units
       End Axis
 End Frame
\end{terminalv}
\normalsize

The corresponding XmlChan output would look like:

\small
\begin{terminalv}
 <Frame xmlns="http://www.starlink.ac.uk/ast/xml/"
        desc="Coordinate system description">
    <_attribute name="Title" quoted="true" value="1-d coordinate system"
                desc="Title of coordinate system" default="true"/>
    <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/>
    <_attribute name="Domain" quoted="true" value="SCREEN"
                desc="Coordinate system domain"/>
    <_attribute name="Lbl1" quoted="true" value="Axis 1"
                desc="Label for axis 1" default="true"/>
    <_attribute name="Uni1" quoted="true" value="cm"
                desc="Units for axis 1" default="true"/>
    <Axis label="Ax1" desc="Coordinate axis">
       <!--Axis number 1-->
       <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/>
    </Axis>
 </Frame>
\end{terminalv}
\normalsize


Notes:

\begin{enumerate}
\item The AST class name is used as the name for an XML element which contain
a description of an AST object.

\item AST attributes are described by XML elements with the name
``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML
to refer to a ``name=value'' pair within an element start tag. So for
instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described
within an XML element with name ``\_attribute'' in which the XML attribute
``name'' has the value ``Title'', and the XML attribute ``value'' has the
value ``1-d coordinate system''. The moral is always to be clear clear
about the context (AST or XML) in which the word \emph{attribute} is being
used!

\item The XML includes comments both as XML attributes with the name ``desc'',
and as separate comment tags.

\item Elements which describe default values are identified by the fact
that they have an XML attribute called ``default'' set to the value
``true''. These elements are ignored when being read back into an XmlChan.

\item The outer-most XML element of an AST object will set the default
namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be
inherited by all nested elements.

\end{enumerate}


The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full
attributes (inherited from the base Channel class) to zero and -1,
resulting in terse output by default. With the default values for these
attributes, the above XML is reduced to the following:

\small
\begin{terminalv}
 <Frame xmlns="http://www.starlink.ac.uk/ast/xml/">
    <_attribute name="Naxes" value="1"/>
    <_attribute name="Domain" quoted="true" value="SCREEN"/>
    <Axis label="Ax1">
       <_attribute name="Unit" quoted="true" value="cm"/>
    </Axis>
 </Frame>
\end{terminalv}
\normalsize


The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel
class. If Skip is zero (the default) then an error will be reported if the text
supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If
Skip is non-zero, then initial text is skipped over without error until
the start of an AST object is found. this allows an AST object to be
located within a larger XML document.

\subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions}
The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML
documents which use a restricted subset of an early draft (V1.20) of the
IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X
finally adopted by the IVOA differs in several significant respects from
V1.20, and so the STC-X support currently provided by AST is mainly of
historical interest. Note, AST also supports the alternative ``STC-S''
linear string description of the STC model (see \secref{ss:stcschans}).

STC-X V1.20 is documented at
\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current
version is documented at
\url{http://www.ivoa.net/Documents/latest/STC-X.html}.

When an STC-X document is read using an XmlChan, the read operation
produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of
\htmlref{Region}{Region}. Specifically, each such Object will be an instance of
\htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or
\htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the
\htmlref{XmlFormat}{XmlFormat} attribute for further details.

\cleardoublepage
\section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)}

The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing
IVOA ``STC-S'' descriptions. STC-S (see
\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string
syntax that allows simple specification of the STC metadata describing a
region in an astronomical coordinate system. AST supports a
subset of the STC-S specification, allowing an STC-S description of a
region within an AST-supported astronomical coordinate system to be converted
into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further
details, see the full description of the StcsChan class in
\appref{ss:classdescriptions}.


\cleardoublepage
\section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)}

\subsection{The Need for Extensibility}

However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you
will want to transform coordinates in some way that has not been
foreseen. You might want to plot a graph in some novel curvilinear
coordinate system (perhaps you already have a WCS system in your
software and just want to use AST for its graphical capabilities).
Alternatively, you might need to calibrate a complex dataset (like an
objective prism plate) where each position must be converted to world
coordinates with reference to calibration data under the control of an
elaborate algorithm.

In such cases, it is clear that the basic pre-formed components
provided by AST for building Mappings are just not enough. What you
need is access to a programming language. However, if you write your
own software to transform coordinate values, then it must be made
available in the form of an AST class (from which you can create
Objects) before it can be used in conjunction with other AST
facilities.

At this point you might consider writing your own AST class, but this
is not recommended. Not only would the internal conventions used by
AST take some time to master, but you might also find yourself having
to change your software whenever a new version of AST was
released. Fortunately, there is a much easier route provided by the
\htmlref{IntraMap}{IntraMap} class.

\subsection{The IntraMap Model}

To allow you to write your own Mappings, AST provides a special kind
of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper''
for a coordinate transformation function written in C. You write this
function yourself and then register it with AST. This, in effect,
creates a new class from which you can create Mappings
(\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever
way your transformation function specifies.

Because IntraMaps are Mappings, they may be used in the same way as
any other Mapping. For instance, they may be combined in series or
parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}),
they may be inverted (\secref{ss:invertingmappings}), you may enquire
about their attributes (\secref{ss:gettingattributes}), they may be
inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do,
however, have some important limitations of which you should be aware
before we go on to consider how to create them.

\subsection{\label{ss:intramaplimitations}Limitations of IntraMaps}

By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is
required at all. After all, why not simply write your own coordinate
transformation functions in C, wrap them up in IntraMaps and do away
with all the other Mapping classes in AST?

The reason is not too hard to find. Any transformation function you
write is created solely by you, so it is a private extension which
does not form a permanent part of AST. If you use it to calibrate some
data and then pass that data to someone else, who has only the
standard version of AST, then they will not be able to interpret it.

Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators
(who we assume have access to the same transformation functions), it
does not address the need for universal data exchange like other AST
Mappings do. This is where the ``Intra'' in the class name
``IntraMap'' comes from, implying private or internal usage.

For this reason, it is unwise to store IntraMaps in datasets, unless
they will be used solely for communication between collaborating items
of software which share conventions about their use.  A private
database describing coordinate systems on a graphics device might be
an example where IntraMaps would be suitable, because the data would
probably never be accessed by anyone else's software. Restricting
IntraMap usage to within a single program (\emph{i.e.} never writing
it out) is, of course, completely safe.

If, by accident, an IntraMap should happen to escape as part of a
dataset, then the unsuspecting recipient is likely to receive an error
message when they attempt to read the data. However, AST will
associate details of the IntraMap's transformation function and its
author (if provided) with the data, so that the recipient can make an
intelligent enquiry to obtain the necessary software if this proves
essential.

\subsection{\label{ss:transformationfunctions}Writing a Transformation Function}

The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate
transformation function. This should have a calling interface like the
\htmlref{astTranP}{astTranP} function provided by AST (\emph{q.v.}). Here is a simple
example of a suitable transformation function which transforms
coordinates by squaring them:
\xlabel{SqrTran}

\small
\begin{terminalv}
#include "ast.h"
#include <math.h>

void SqrTran( AstMapping *this, int npoint, int ncoord_in,
              const double *ptr_in[], int forward, int ncoord_out,
              double *ptr_out[] ) {
   int point, coord;
   double x;

/* Forward transformation. */
   if ( forward ) {
      for ( point = 0; point < npoint; point++ ) {
         for ( coord = 0; coord < ncoord_in; coord++ ) {
            x = ptr_in[ coord ][ point ];
            ptr_out[ coord ][ point ] = ( x == AST__BAD ) ? AST__BAD : x * x;
         }
      }

/* Inverse transformation. */
   } else {
      for ( point = 0; point < npoint; point++ ) {
         for ( coord = 0; coord < ncoord_in; coord++ ) {
            x = ptr_in[ coord ][ point ];
            ptr_out[ coord ][ point ] =
               ( x < 0.0 || x == AST__BAD ) ? AST__BAD : sqrt( x );
         }
      }
   }
}
\end{terminalv}
\normalsize

As you can see, the function comes in two halves which implement the
forward and inverse coordinate transformations. The number of points
to be transformed (``npoint'') and the numbers of input and output
coordinates per point (``ncoord\_in'' and ``ncoord\_out''---in this
case both are assumed equal) are passed to the function. A pair of
loops then accesses all the coordinate values.  Note that it is
legitimate to omit one or other of the forward/inverse transformations
and simply not to implement it, if it will not be required. It is also
permissible to require that the numbers of input and output
coordinates be fixed (\emph{e.g.}\ at 2), or to write the function so
that it can handle arbitrary dimensionality, as here.

Before using an incoming coordinate, the function must first check
that it is not set to the value AST\_\_BAD, which indicates missing
data (\secref{ss:badcoordinates}). If it is, the same value is also
assigned to any affected output coordinates. The value AST\_\_BAD is
also generated if any coordinates cannot be transformed. In this
example, this can happen with the inverse transformation if negative
values are encountered, so that the square root cannot be taken.

There are very few restrictions on what a coordinate transformation
function may do. For example, it may freely perform I/O to access any
external data needed, it may invoke other AST facilities (but beware
of unwanted recursion), \emph{etc.} Typically, you may also want to
pass information to it \emph{via}\ global variables. Remember,
however, that whatever facilities the transformation function requires
must be available in every program which uses it.

Generally, it is not a good idea to retain context information within
a transformation function. That is, it should transform each set of
coordinates as a single point and retain no memory of the points it
has transformed before. This is in order to conform with the AST model
of a \htmlref{Mapping}{Mapping}.

If an error occurs within a transformation function, it should use the
\htmlref{astSetStatus}{astSetStatus} function (\secref{ss:errordetection}) to set the AST
status to an error value before returning. This will alert AST to the
error, causing it to abort the current operation. The error value
AST\_\_ITFER is available for this purpose, but other values may also
be used (\emph{e.g.}\ if you wish to distinguish different types of
error).

\subsection{\label{ss:registeringintramaps}Registering a Transformation Function}

Having written your coordinate transformation function, the next step
is to register it with AST. Registration is performed using
\htmlref{astIntraReg}{astIntraReg}, as follows:

\small
\begin{terminalv}
void SqrTran( AstMapping *, int, int, const double *[], int, int, double *[] );

const char *author, *contact, *purpose;

...

purpose = "Square each coordinate value";
author =  "R.F. Warren-Smith & D.S. Berry";
contact = "http://www.starlink.ac.uk/cgi-bin/htxserver/sun211.htx/?xref_SqrTran";

astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact );
\end{terminalv}
\normalsize

Note that you should also provide a function prototype to describe the
transformation function (the implementation of the function itself
would suffice, of course).

The first argument to astIntraReg is a name by which the
transformation function will be known. This will be used when we come
to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you use
the actual function name here and make this sufficiently unusual that
it is unlikely to clash with any other functions in most people's
software.

The next two arguments specify the number of input and output
coordinates which the transformation function will handle. These
correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will
create. Here, we have set them both to 2, which means that we will
only be able to create IntraMaps with 2 input and 2 output coordinates
(despite the fact that the transformation function can actually handle
other dimensionalities). We will see later
(\secref{ss:variableintramapcoordinates}) how to remove this
restriction.

The fourth argument should contain a set of flags which describe the
transformation function in a little more detail. We will return to
this shortly (\secref{ss:restrictedintramaps} \&
\secref{ss:simplifyingintramaps}). For now, we supply a value of zero.

The remaining arguments are character strings which document the
transformation function, mainly for the benefit of anyone who is
unfortunate enough to encounter a reference to it in their data which
they cannot interpret. As explained above
(\secref{ss:intramaplimitations}), you should try and avoid this, but
accidents will happen, so you should always provide strings containing
the following:

\begin{enumerate}
\item A short description of what the transformation function is for.
\item The name of the author.
\item Contact details, such as an e-mail or WWW address.
\end{enumerate}

The idea is that anyone finding an IntraMap in their data, but lacking
the necessary transformation function, should be able to contact the
author and make a sensible enquiry in order to obtain it. If you
expect many enquiries, you may like to set up a World Wide Web page
and use that instead (in the example above, we use the WWW address of
the relevant part of this document).

\subsection{Creating an IntraMap}

Once a transformation function has been registered, creating an
\htmlref{IntraMap}{IntraMap} from it is simple:

\small
\begin{terminalv}
AstIntraMap *intramap;

...

intramap = astIntraMap( "SqrTran", 2, 2, "" );
\end{terminalv}
\normalsize

We simply use the \htmlref{astIntraMap}{astIntraMap} constructor function and pass it the
name of the transformation function to use. This name is the same
(case sensitive) one that we associated with the function when we
registered it using \htmlref{astIntraReg}{astIntraReg} (\secref{ss:registeringintramaps}).

You can, of course, register any number of transformation functions
and select which one to use whenever you create an IntraMap. You can
also create any number of independent IntraMaps using each
transformation function. In this sense, each transformation function
you register effectively creates a new ``sub-class'' of IntraMap, from
which you can create Objects just like any other class. However, an
error will occur if you attempt to use a transformation function that
has not yet been registered.

The second and third arguments to astIntraMap are the numbers of input
and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for
the IntraMap that is created and they must match the corresponding
numbers given when the transformation function was registered.

The final argument is the usual attribute initialisation string. You
may set attribute values for an IntraMap in exactly the same way as
for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see
\secref{ss:intraflag}).

\subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Functions}

You may not always want to use both the forward and inverse
transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit
either from the underlying coordinate transformation
function. Consider the following, for example:

\small
\begin{terminalv}
void Poly3Tran( AstMapping *this, int npoint, int ncoord_in,
                const double *ptr_in[], int forward, int ncoord_out,
                double *ptr_out[] ) {
   double x;
   int point;

/* Forward transformation. */
   for ( point = 0; point < npoint; point++ ) {
      x = ptr_in[ 0 ][ point ];
      ptr_out[ 0 ][ point ] = ( x == AST__BAD ) ? AST__BAD :
         6.18 + x * ( 0.12 + x * ( -0.003 + x * 0.0000101 ) );
   }
}
\end{terminalv}
\normalsize

This implements a 1-dimensional cubic polynomial transformation. Since
this is somewhat awkward to invert, however, we have only implemented
the forward transformation.  When registering the function, this is
indicated via the ``flags'' argument to \htmlref{astIntraReg}{astIntraReg}, as follows:

\small
\begin{terminalv}
void Poly3Tran( AstMapping *, int, int, const double *[], int, int, double *[] );

...

astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV,
             purpose, author, contact );
\end{terminalv}
\normalsize

Here, the fifth argument has been set to the flag value AST\_\_NOINV
to indicate the lack of an inverse. If the forward transformation were
absent, we would use AST\_\_NOFOR instead. Flag values for this
argument may be combined using a bitwise OR if necessary.

\subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates}

In our earlier examples, we have used a fixed number of input and
output coordinates when registering a coordinate transformation
function. It is not necessary to impose this restriction, however, if
the transformation function can cope with a variable number of
coordinates (as with the example in
\secref{ss:transformationfunctions}). We indicate the acceptability of
a variable number when registering the transformation function by
supplying the value AST\_\_ANY for the number of input and/or output
coordinates, as follows:

\small
\begin{terminalv}
astIntraReg( "SqrTran", AST__ANY, AST__ANY, SqrTran, 0,
             purpose, author, contact );
\end{terminalv}
\normalsize

The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of
input and output coordinates. For example:

\small
\begin{terminalv}
AstIntraMap *intramap1, *intramap2;

...

intramap1 = astIntraMap( "SqrTran", 1, 1, "" );
intramap2 = astIntraMap( "SqrTran", 3, 3, "Invert=1" );
\end{terminalv}
\normalsize

It is possible to fix either the number of input or output coordinates
(by supplying an explicit number to \htmlref{astIntraReg}{astIntraReg}), but more subtle
restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin}
and \htmlref{Nout}{Nout} be equal, are not supported. This means that:

\small
\begin{terminalv}
intramap = astIntraMap( "SqrTran", 1, 2, "" );
\end{terminalv}
\normalsize

will be accepted without error, although the transformation function
cannot actually handle such a combination sensibly. If this is
important, it would be worth adding a check within the transformation
function itself, so that the error would be detected when it came to
be used.

\subsection{\label{ss:intraflag}Adapting a Transformation Function to Individual IntraMaps}

In the examples given so far, our coordinate transformation functions
have not made use of the ``this'' pointer passed to them (which
identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In
practice, this will often be the case. However, the presence of the
``this'' pointer allows the transformation function to invoke any
other AST function on the IntraMap, and this permits enquiries about
its attributes. The transformation function's behaviour can therefore
be modified according to any attribute values which are set. This
turns out to be a useful thing to do, so each IntraMap has a special
\htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose.

Consider, for instance, the case where the transformation function has
access to several alternative sets of internally-stored data which it
may apply to perform its transformation. Rather than implement many
different versions of the transformation function, you may switch
between them by setting a value for the IntraFlag attribute when you
create an instance of an IntraMap, for example:

\small
\begin{terminalv}
intramap1 = astIntraMap( "MyTran", 2, 2, "IntraFlag=A" );
intramap2 = astIntraMap( "MyTran", 2, 2, "IntraFlag=B" );
\end{terminalv}
\normalsize

The transformation function may then enquire the value of the IntraFlag
attribute (\emph{e.g.}\ using astGetC and passing it the ``this''
pointer) and use whichever dataset is required for that particular
IntraMap.

This approach is particularly useful when the number of possible
transformations is unbounded or not known in advance, in which case
the IntraFlag attribute may be used to hold numerical values encoded
as part of a character string (effectively using them as data for the
IntraMap). It is also superior to the use of a global switch for
communication (\emph{e.g.}\ setting an index to select the ``current''
data before using the IntraMap), because it continues to work when
several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping},
when you may have no control over the order in which they are used.

\subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps}

A notable disadvantage of IntraMaps is that they are ``black boxes''
as far as AST is concerned. This means that they have limited ability
to participate in the simplification of compound Mappings performed,
\emph{e.g.}, by \htmlref{astSimplify}{astSimplify} (\secref{ss:simplifyingcmpmaps}), because
AST cannot know how they interact with other Mappings. In reality, of
course, they will often implement such specialised coordinate
transformations that the simplification possibilities will be rather
limited anyway.

One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to
cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This
is important because Mappings are frequently used to relate a dataset
to some external standard (a celestial coordinate system, for
example). When inter-relating two similar datasets calibrated using
the same standard, part of the Mapping often cancels, because it is
applied first in one direction and then the other, effectively
eliminating the reference to the standard. This is often a useful
simplification and can lead to greater efficiency.

Many transformations have this property of cancelling with their own
inverse, but not necessarily all. Consider the following
transformation function, for example:

\small
\begin{terminalv}
void MaxTran( AstMapping *this, int npoint, int ncoord_in,
              const double *ptr_in[], int forward, int ncoord_out,
              double *ptr_out[] ) {
   double hi, x;
   int coord, point;

/* Forward transformation. */
   if ( forward ) {
      for ( point = 0; point < npoint; point++ ) {
         hi = AST__BAD;
         for ( coord = 0; coord < ncoord_in; coord++ ) {
            x = ptr_in[ coord ][ point ];
            if ( x != AST__BAD ) {
               if ( x > hi || hi == AST__BAD ) hi = x;
            }
         }
         ptr_out[ 0 ][ point ] = hi;
      }

/* Inverse transformation. */
   } else {
      for ( coord = 0; coord < ncoord_out; coord++ ) {
         for ( point = 0; point < npoint; point++ ) {
            ptr_out[ coord ][ point ] = ptr_in[ 0 ][ point ];
         }
      }
   }
}
\end{terminalv}
\normalsize

This function takes any number of input coordinates and returns a
single output coordinate which is the maximum value of the input
coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the
input coordinates to the value of the output
coordinate.\footnote{Remember that ``ptr\_in'' identifies the original
``output'' coordinates when applying the inverse transformation and
``ptr\_out'' identifies the original ``input'' coordinates.}

If this function is applied in the forward direction and then in the
inverse direction, it does \textbf{not} in general restore the original
coordinate values. However, if applied in the inverse direction and
then the forward direction, it does. Hence, replacing the sequence of
operations with an equivalent UnitMap is possible in the latter case,
but not in the former.

To distinguish these possibilities, two flag values are provided for
use with \htmlref{astIntraReg}{astIntraReg} to indicate what simplification (if any) is
possible. For example, to register the above transformation function,
we might use:

\small
\begin{terminalv}
void MaxTran( AstMapping *, int, int, const double *[], int, int, double *[] );

...

astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF,
             purpose, author, contact );
\end{terminalv}
\normalsize

Here, the flag value AST\_\_SIMPIF supplied for the fifth argument
indicates that simplification is possible if the transformation is
applied in the inverse direction followed by the forward direction. To
indicate the complementary case, the flag AST\_\_SIMPFI would be used
instead. If both simplifications are possible (as with the SqrTran
function in \secref{ss:transformationfunctions}), then we would use
the bitwise OR of both values.

In practice, some judgement is usually necessary when deciding whether
to allow simplification. For example, seen in one light our SqrTran
function (\secref{ss:transformationfunctions}) does not cancel with
its own inverse, because squaring a coordinate value and then taking
its square root can change the original value, if this was
negative. Therefore, replacing this combination with a UnitMap will
change the behaviour of a compound Mapping and should not be
allowed. Seen in another light, however, where the coordinates being
processed are intrinsically all positive, it is a permissible and
probably useful simplification.

If such distinctions are ever important in practice, it is simple to
register the same transformation function twice with different flag
values (use a separate name for each) and then use whichever is
appropriate when creating an \htmlref{IntraMap}{IntraMap}.

\subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps}

It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a
\htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation function
which it uses is not stored with it. To do so is impossible, because
the function has been compiled and loaded into memory ready for
execution before AST gets to see it. However, AST does store the name
associated with the transformation function and various details about
the IntraMap itself.


This means that any program attempting to read the IntraMap
(\secref{ss:readingfromachannel}) cannot make use of it unless it also
has independent access to the original transformation function. If it
does not have access to this function, an error will occur at the
point where the IntraMap is read and the associated error message will
direct the user to the author of the transformation function for more
information.

However, if the necessary transformation function is available, and
has been registered before the read operation takes place, then AST is
able to re-create the original IntraMap and will do so. Registration
of the transformation function must, of course, use the same name
(and, in fact, be identical in most particulars) as was used in the
original program which wrote the data.

This means that a set of co-operating programs which all have access
to the same set of transformation functions and register them in
identical fashion (see \secref{ss:intramaplibrary} for how this can
best be achieved) can freely exchange data that contain IntraMaps. The
need to avoid exporting such data to unsuspecting third parties
(\secref{ss:intramaplimitations}) must, however, be re-iterated.

\subsection{\label{ss:intramaplibrary}Managing Transformation Functions in Libraries}

If you are developing a large suite of data reduction software, you
may have a need to use IntraMaps at various points within it. Very
probably this will occur in unrelated modules which are compiled
separately and then stored in a library. Since the transformation
functions required must be registered before they can be used, this
makes it difficult to decide where to perform this registration,
especially since any particular data reduction program may use an
arbitrary subset of the modules in your library.

To assist with this problem, AST allows you to perform the same
registration of a transformation function any number of times, so long
as it is performed using an identical invocation of \htmlref{astIntraReg}{astIntraReg} on
each occasion (\emph{i.e.}\ all of its arguments must be
identical). This means you do not have to keep track of whether a
particular function has already been registered but could, in fact,
register it on each occasion immediately before it is required
(wherever that may be). In order that all registrations are identical,
however, it is recommended that you group them all together into a
single function, perhaps as follows:

\small
\begin{terminalv}
void MyTrans( void ) {

   ...

   astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF,
                purpose, author, contact );

   ...

   astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV,
                purpose, author, contact );

   ...

   astIntraReg( "SqrTran", 2, 2, SqrTran, 0,
                purpose, author, contact );
}
\end{terminalv}
\normalsize

You can then simply invoke this function wherever necessary. It is, in
fact, particularly important to register all relevant transformation
functions in this way before you attempt to read an \htmlref{Object}{Object} that might
be (or contain) an \htmlref{IntraMap}{IntraMap}
(\secref{ss:readingandwritingintramaps}). This is because you may not
know in advance which of these transformation functions the IntraMap
will use, so they must all be available in order to avoid an error.

\cleardoublepage
\section{\label{ss:plots}Producing Graphical Output (Plots)}

Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot},
which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the
graphical content itself, but is a route through which plotting
operations, such as drawing lines and curves, are conveyed on to a
plotting surface to appear as visible graphics.

\subsection{The Plot Model}

When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose
base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or
logarithmically (as specified by the LogPlot attribues) on to a
\emph{plotting area}. This is a rectangular region in the graphical
coordinate space of the underlying graphics system and becomes the new
base Frame of the Plot. In effect, the Plot becomes attached to the
plotting surface, in rather the same way that a basic FrameSet might be
attached to (say) an image.

The current Frame of the Plot (derived from the current Frame of the
FrameSet supplied) is used to represent a \emph{physical coordinate
system}. This is the system in which plotting operations are
performed by your program.  Every plotting operation is then
transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current
and base Frames in order to appear on the plotting surface.

An example may help here. Suppose we start with a FrameSet whose base
Frame describes the pixel coordinates of an image and whose current
Frame describes a celestial (equatorial) coordinate system. Let us
assume that these two Frames are inter-related by a Mapping within the
FrameSet which represents a particular sky projection.

When a Plot is created from this FrameSet, we specify how the pixel
coordinates (the base Frame) maps on to the plotting surface. This
simply corresponds to telling the Plot where we have previously
plotted the image data. If we now use the Plot to plot a line with
latitude zero in our physical coordinate system, as given by the
current Frame, this line would appear as a curve (the equator) on the
plotting surface, correctly registered with the image.

There are a number of plotting functions provided, which all work in a
similar way. Plotting operations are transformed through the Mapping
which the Plot represents before they appear on the plotting
surface.\footnote{Like any FrameSet, a Plot can be used as a
Mapping. In this case it is the inverse transformation which is used
when plotting (\emph{i.e.}\ that which transforms between the current
and base Frames).}  It is possible to draw symbols, lines, axes,
entire grids and more in this way.

%\subsection{TBW---Creating a Plot}

\subsection{Plotting Symbols}

The simplest form of plotting is to draw symbols (termed
\emph{markers}) at a set of points. This is performed by \htmlref{astMark}{astMark},
which is supplied with a set of physical coordinates at which to place
the markers:

\small
\begin{terminalv}
#include "ast.h"
#define NCOORD 2
#define NMARK 10
double in[ NCOORD ][ NMARK ];
int type;

...

astMark( plot, NMARK, NCOORD, NMARK, in, type );
\end{terminalv}
\normalsize

Here, NMARK specifies how many markers to plot and NCOORD specifies
how many coordinates are being supplied for each
point.\footnote{Remember, the physical coordinate space need not
necessarily be 2-dimensional, even if the plotting surface is.} The
array ``in'' supplies the coordinates and the integer ``type''
specifies which type of marker to plot.

\subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves}

There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight
line in physical coordinates can potentially turn into a curve in
graphical coordinates. We therefore start by considering how to draw
geodesic curves.  These are curves which trace the path of shortest
distance between two points in physical coordinates
 and are the basic drawing element in a Plot.

In many instances, the geodesic will, in fact, be a straight line, but
this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a
celestial coordinate system, for instance, it will be a great circle
(corresponding with the behaviour of the \htmlref{astDistance}{astDistance} function which
defines the metric of the physical coordinate space).  The geodesic
will, of course, be transformed into graphics coordinates before being
plotted. A geodesic curve is plotted using \htmlref{astCurve}{astCurve} as follows:

\small
\begin{terminalv}
double start[ NCOORD ], finish[ NCOORD ];

...

astCurve( plot, start, finish );
\end{terminalv}
\normalsize

Here, ``start'' and ``finish'' are arrays containing the starting and
finishing coordinates of the curve. The \htmlref{astOffset}{astOffset} and astDistance
functions can often be useful for computing these
(\secref{ss:distanceandoffset}).

If you need to draw a series of curves end-to-end (when drawing a
contour line, for example), then a more efficient alternative is to
use \htmlref{astPolyCurve}{astPolyCurve}. This has the same effect as a sequence of
invocations of astCurve, but allows you to supply a whole set of
points at one time. astPolyCurve then joins them, in sequence, using
geodesic curves:

\small
\begin{terminalv}
#define NPOINT 100
double coords[ NCOORD ][ NPOINT ];

...

astPolyCurve( plot, NPOINT, NCOORD, NPOINT, coords );
\end{terminalv}
\normalsize

Here, NPOINT specifies how many points are to be joined and NCOORD
specifies how many coordinates are being supplied for each point.  The
array ``coords'' supplies the coordinates of the points in the Plot's
physical coordinate system.

\subsection{Plotting Curves Parallel to Axes}

As there is no \htmlref{Plot}{Plot} function to draw a ``straight line'', drawing axes
and grid lines to represent coordinate systems requires a slightly
different approach. The problem is that for some coordinate systems,
these grid lines will not be geodesics, so \htmlref{astCurve}{astCurve} and \htmlref{astPolyCurve}{astPolyCurve}
(\secref{ss:plottinggeodesics}) cannot easily be used (you would have
to resort to approximating grid lines by many small elements). Lines
of constant celestial latitude provide an example of this, with the
exception of the equator which is a geodesic.

The \htmlref{astGridLine}{astGridLine} function allows these curves to be drawn, as follows:

\small
\begin{terminalv}
int axis;
double length;

...

astGridLine( plot, axis, start, length );
\end{terminalv}
\normalsize

Here, ``axis'' specifies which physical coordinate axis we wish to
draw parallel to. The ``start'' array contains the coordinates of the
start of the curve and ``length'' specifies the distance to draw along
the axis in physical coordinate space.

\subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves}
We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot}
class includes another method,
\htmlref{astGenCurve}{astGenCurve},
which allows curves of \emph{any} form to be drawn. The caller supplies a
\htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the
start of the curve is at offset 0.0 and the end of the curve is at offset
1.0 - offset need not be linearly related to distance.} into the
corresponding position in the current \htmlref{Frame}{Frame} of the Plot.
astGenCurve,
then takes care of Mapping these positions into graphics coordinates. The
choice of exactly which positions along the curve are to be used to
define the curve is also made by
astGenCurve,
using an adaptive algorithm which concentrates points around areas where
the curve is bending sharply or is discontinuous in graphics coordinates.

The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows
you to code your own Mappings to do any transformation you choose.


\subsection{\label{ss:clipping}Clipping}

Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics
you produce. This means that plotting is restricted to certain regions
of the plotting surface so that anything drawn outside these regions
will not appear.  All Plots automatically clip at the edges of the
plotting area specified when the Plot is created. This means that
graphics are ultimately restricted to the rectangular region of
plotting space to which you have attached the Plot.

In addition to this, you may also specify lower and upper limits on
each axis at which clipping should occur. This permits you to further
restrict the plotting region. Moreover, you may attach these clipping
limits to \emph{any} of the Frames in the Plot. This allows you to
place restrictions on where plotting will take place in either the
physical coordinate system, the graphical coordinate system, or in any
other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot.

For example, you could plot using equatorial coordinates and set up
clipping limits in galactic coordinates. In general, you could set up
arbitrary clipping regions by adding a new Frame to a Plot (in which
clipping will be performed) and inter-relating this to the other
Frames in a suitable way.

Clipping limits are defined using the \htmlref{astClip}{astClip} function, as follows:

\small
\begin{terminalv}
#define NAXES 2
int iframe;
double lbnd[ NAXES ], ubnd[ NAXES ];

...
astClip( plot, iframe, lbnd, ubnd);
\end{terminalv}
\normalsize

Here, the ``iframe'' value gives the index of the Frame within the
Plot to which clipping is to be applied, while ``lbnd'' and ``ubnd''
give the limits on each axis of the selected Frame (NAXES is the
number of axes in this Frame).

You can remove clipping by giving a value of AST\_\_NOFRAME for ``iframe''.

\subsection{Using a Plot as a Mapping}

All Plots are also Mappings (just like the FrameSets from which they
are derived), so can be used to transform coordinates.

Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert
coordinates between the base and current Frames (\emph{i.e.}\ between
graphical and physical coordinates). This would be useful if you were
(say) reading a cursor position in graphical coordinates and needed to
convert this into physical coordinates for display.

Conversely, a Plot's inverse transformation converts between its
current and base Frames (\emph{i.e.}\ from physical coordinates to
graphical coordinates). This transformation is applied automatically
whenever plotting operations are carried out by AST functions. It may
also be useful to apply it directly, however, if you wish to perform
additional plotting operations (\emph{e.g.}\ those provided by the
native graphics system) at positions specified in physical
coordinates.

There is, however, one important difference between using a \htmlref{FrameSet}{FrameSet}
and a Plot to transform coordinates, and this is that clipping may be
applied by a Plot (if it has been enabled using
\htmlref{astClip}{astClip}---\secref{ss:clipping}). Any point which lies within the
clipped region of a Plot will, when transformed, yield coordinates
with the value AST\_\_BAD. If you wish to avoid this clipping, you
should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using
\htmlref{astGetMapping}{astGetMapping}) and use this, instead of the Plot, to transform the
coordinates.

\subsection{Using a Plot as a Frame}

Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of
Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units,
\emph{etc.}, which are typically used when displaying data and/or
coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from
the current Frame of the Plot (\secref{ss:framesetasframe}). They are
also used automatically when using the Plot to plot coordinate axes
and coordinate grids (\emph{e.g.}\ for labelling
them---\secref{ss:plottingagrid}).

Because the current Frame of a Plot represents physical coordinates,
any Frame operation applied to the Plot will effectively be working in
this coordinate system. For example, the \htmlref{astDistance}{astDistance} and \htmlref{astOffset}{astOffset}
functions will compute distances and offsets in physical coordinate
space, while \htmlref{astFormat}{astFormat} and \htmlref{astNorm}{astNorm} will format physical coordinates in
an appropriate way for display.

\subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates}

When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot}
into graphics coordinates for plotting, they may not always yield
valid coordinates, irrespective of any clipping being applied
(\secref{ss:clipping}). To indicate this, the resulting coordinate
values will be set to the value AST\_\_BAD
(\secref{ss:badcoordinates}).

There are a number of reasons why this may occur, but typically it
will be because physical coordinates only map on to a subset of the
graphics coordinate space. This situation is commonly encountered with
all-sky projections where, typically, the celestial sphere appears,
when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which
does not entirely fill the graphics space. In some cases, there may
even be multiple regions of valid and invalid physical coordinates.

When plotting is performed \emph{via} a Plot, graphical output will
only appear in the regions of valid physical coordinates. Nothing will
appear where invalid coordinates occur. Such output is effectively
clipped. If you wish to plot in these areas, you must change
coordinate system and use, say, graphical coordinates to address the
plotting surface directly.

\subsection{Plotting Borders}

The \htmlref{astBorder}{astBorder} function is provided to draw a (line) border around your
graphical output. With most graphics systems, this would simply be a
rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this
boundary follows the edge of each region containing valid, unclipped
physical coordinates (\secref{ss:validphysicalcoordinates}).

This means, for example, that if you were plotting an all-sky
projection, this boundary would outline the perimeter of the celestial
sphere when projected on to your plotting surface. Of course, if there
is no clipping and all physical coordinates are valid, then you will
get the traditional rectangular box. astBorder requires only
a pointer to the Plot:

\small
\begin{terminalv}
int holes;

...

holes = astBorder( plot );
\end{terminalv}
\normalsize

It returns a boolean (integer) value to indicate if any invalid or
clipped physical coordinates were found within the plotting area. If
they were, it will draw around the valid unclipped regions and return
a value of one.  Otherwise, it will draw a simple rectangular border
and return zero.

\subsection{Plotting Text}

Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be
displayed and a position in physical coordinates where the text is to
appear. The position is transformed into graphical coordinates to
determine where the text should appear on the plotting surface. You
must also provide a 2-element ``up'' vector which gives the upward
direction of the text in graphical coordinates. This allows text to be
drawn at any angle.

Plotting is performed by \htmlref{astText}{astText}, for example:

\small
\begin{terminalv}
char text[ 21 ];
double pos[ NCOORD ];
float up[ 2 ] = { 0.0f, 1.0f };

...

astText( plot, text, pos, up, "TL" );
\end{terminalv}
\normalsize

Here, ``text'' contains the string to be drawn, ``pos'' is an array of
physical coordinates and ``up'' specifies the upward vector. In this
case, the text will be drawn horizontally. The final argument
specifies the text justification, here indicating that the top left
corner of the text should appear at the position given.

Further control over the appearance of the text is possible by setting
values for various Plot attributes, for example Colour, Font and Size.
Sub-strings within the displayed text can be given different appearances,
or turned into super-scripts or sub-scripts, by the inclusion of escape
sequences (see section~\secref{ss:escapes}) within the supplied text string.

\subsection{\label{ss:plottingagrid}Plotting a Grid}

The most comprehensive plotting function available is \htmlref{astGrid}{astGrid}, which
can be used to draw labelled coordinate axes and, optionally, to
overlay coordinate grids on the plotting area
(Figure~\ref{fig:gridplot}). The routine is straightforward to use,
simply requiring a pointer to the \htmlref{Plot}{Plot}:

\small
\begin{terminalv}
astGrid( plot );
\end{terminalv}
\normalsize

It will draw both linear and curvilinear axes and grids, as required
by the particular Plot. The appearance of the output can be modified
in a wide variety of ways by setting various Plot attributes.
The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis
labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings
within these strings can be given different appearances, or turned into
super-scripts or sub-scripts, by the inclusion of escape sequences (see
section~\secref{ss:escapes}) within the Label attributes.

\subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings}
Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be
plotted so that all characters in the string have the same font size,
colour, \emph{etc.}, specified by the appropriate attributes of the
Plot. However, it is possible to include \emph{escape sequences} within
the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be
used to change, colour, font, size, width, to introduce extra horizontal
space between characters, and to change the base line of characters (thus
allowing super-scripts and sub-scripts to be created). See the entry for
the Escape attribute in \appref{ss:attributedescriptions} for details.

As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is
plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a
super-scripted exponent. The exponent text will be 70\% of the size of
normal text (as determined by the Size attribute), and its baseline will
be raised by 50\% of the height of a normal character.

Such escape sequences can be used in the strings assigned to textual
attributes of the Plot (such as the axis Labels), and may also be
included in strings plotted using
\htmlref{astText}{astText}.

The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option
which will cause escape sequences to be included when formatting
celestial positions so that super-script characters are used as
delimiters for the various fields (a super-script ``h'' for hours, ``m''
for minutes, \emph{etc}).

Note, the facility for interpreting escape sequences is only available if
the graphics wrapper functions which provide the interface to the
underlying graphics system support all the functions included in the
\verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be
extended by the addition of new functions before escape sequences can be
interpretted.

\subsection{\label{ss:logaxes}Producing Logarithmic Axes}
In certain situations you may wish for one or both of the plotted axes to
be displayed logarithmically rather than linearly. For instance, you may
wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux
against frequency. In this case, you can cause the frequency axis to be drawn
logarithmically simply by setting the boolean LogPlot attribute for the
frequency axis to a non-zero value. This causes several things to happen:

\begin{enumerate}

\item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents
the underlying graphics world coordinate system) and the base Frame of
the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By
default, this mapping is linear on both axes, but setting LogPlot non-zero
for an axis causes the Mapping to be modified so that it is logarithmic
on the specified axis. This is only possible if the displayed section of
the axis does not include the value zero (otherwise the attempt to set
a new value for LogPlot is ignored,and it retains its default value of
zero).

\item The major tick marks drawn as part of the annotated coordinate grid
are spaced logarithmically rather than linearly. That is, major axis
values are chosen so that there is a constant ratio between adjacent
tick mark values. This ratio is constrained to be a power of ten. The
minor tick marks are drawn at linearly distributed points between the
adjoining major tick values. Thus if a pair of adjacent major tick values
are drawn at axis values 10.0 and 100.0, minor ticks will be placed at
20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick
marks are drawn).

\item If possible, numerical axis labels are shown as powers of ten.
This depends on the facilities implemented by the graphics wrapper
functions (see the next section). Extra functions were introduced to this
set of wrapper functions at AST V3.2 which enable super-scripts and
sub-scripts to be produced. Some older wrappers may not yet have
implemented these functiosn and this will result in axis labels being
drawn in usual scientific or decimal notation.

\end{enumerate}

Whilst the LogPlot attribute can be used to control all three of the above
facilities, it is possible to control them individually as well. The
LogTicks and LogLabel attributes control the behaviour specified in items
2 and 3 above, but the default values for these attributes depend on the
setting of the LogPlot attribute. This means that setting LogPlot
non-zero will swicth all three facilites on, so long as zero values have
not been assigned explicitly to LogTicks or LogLabel.


\subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package}
The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a
graphics device. Instead, it requires a set of functions to be provided
which it uses to draw the required graphics. These include functions
to draw a straight line, draw a text string, \emph{etc}. You may choose
to provide functions from your favorite graphics package, or you can even
write your own! To accomodate variations in the calling interfaces of
different graphics packages, AST defines a standard interface for these
routines. If this interface differs from the interface provided by your
graphics package (which in general it will), then you must write a set of
\emph{wrapper functions}, which provide the interface expected by AST but
which then call functions from your graphics package to provide the
required functionality. AST comes with wrapper functions suitable for
the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}).

There are two ways of indicating which wrapper functions are to be used by
the Plot class:
\begin{enumerate}

\item A file containing C functions with pre-defined names can be written
and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command.
(see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is
distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT
functions to implement the required functionality. This file can be used
as a template for writing your own.

\item The
\htmlref{astGrfSet}{astGrfSet}
method of the Plot class can be used to ``register''
wrapper functions at run-time. This allows an application to switch
between graphics systems if required. Graphics functions registered in
this way do not need to have the pre-defined names used in the link-time
method described above.

\end{enumerate}

For details of the interfaces of the wrapper routines, see
either the \texttt{grf\_pgplot.c} file included in the AST source
distribution, or the reference documentation for the astGrfSet method.

\cleardoublepage
\section{Compiling and Linking Software that Uses AST}

A small number of UNIX commands are provided by AST to assist with the
process of building software. A description of these can be found in
\appref{ss:commanddescriptions} and their use is discussed here.  Note
that in order to access these commands, the appropriate directory
(normally ``/star/bin'') should be on your PATH.\footnote{If you have
not installed AST in the usual location, then substitute the
appropriate directory in place of ``/star'' wherever it occurs.}

\subsection{\label{ss:accessingheaderfile}Accessing the ``ast.h'' Header File}

The ``ast.h'' header file defines the external interface to the AST library,
including all constants, function prototypes, macros, \emph{etc.}. This file
should be located using the usual compiler options for finding C
include files, for instance:

\small
\begin{terminalv}
cc prog.c -I/star/include -o prog
\end{terminalv}
\normalsize

This is preferable to specifying the file's absolute name within your
software.

\subsection{\label{ss:linking}Linking with AST Facilities}

C programs which use AST facilities may be linked by including
execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command
line. Thus, to compile and link a program called ``prog'', the
following might be used:

\small
\begin{terminalv}
cc prog.c -L/star/lib `ast_link` -o prog
\end{terminalv}
\normalsize

Note the use of backward quote characters, which cause the
``ast\_link'' command to be executed and its result substituted into
the compiler command. An alternative is to save the output from
``ast\_link'' in (say) a shell variable and use this instead. You may
find this a little faster if you are building software repeatedly
during development.

Programs which use AST can also be linked in a number of other ways,
depending on the facilities they require. In the example above, we
have used the default method which assumes that the program will not
be generating graphical output, so that no graphics libraries need be
linked. If you need other facilities, then various switches can be
applied to the ``ast\_link'' command in order to control the linking
process.

For example, if you were producing graphical output using the PGPLOT
graphics package, you could link with the AST/PGPLOT interface by
using the ``$-$pgplot'' switch with ``ast\_link'', as
follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use
the Starlink version of PGPLOT which uses GKS to generate its output.}

\small
\begin{terminalv}
cc prog.c -L/star/lib `ast_link -pgplot` -o prog
\end{terminalv}
\normalsize

See the ``ast\_link'' command description in
\appref{ss:commanddescriptions} for details of the options available.

\subsection{Building ADAM Applications that Use AST}

Users of Starlink's \xref{ADAM}{sg4}{} programming environment
\latex{(SG/4)} on UNIX should use the
``\xref{alink}{sun144}{ADAM_link_scripts}'' command
(\xref{SUN/144}{sun144}{}) to compile and link applications and can
access the AST library by including execution of the command
``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows:

\begin{small}
\begin{terminalv}
alink adamprog.c `ast_link_adam`
\end{terminalv}
\end{small}

Note the use of backward quote characters.

By default, AST error messages produced by applications built in this
way will be delivered \emph{via} the Starlink EMS Error Message
Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is
consistent with the \xref{\emph{inherited
status}}{sun104}{inherited_status} error handling normally used in
Starlink software.

Switches may be given to the ``ast\_link\_adam'' command (in a similar
way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with
additional AST-related facilities, such as a graphics interface. See
the ``ast\_link\_adam'' command description in
\appref{ss:commanddescriptions} for details of the options available.

\appendix
\cleardoublepage
\section{\label{ss:classhierarchy}The AST Class Hierarchy}
The following table shows the hierarchy of classes in the AST library.
For a description of each class, you should consult
\appref{ss:classdescriptions}.

\small
\begin{terminalv}
Object             - Base class for all AST Objects
   Axis            - Store axis information
      SkyAxis      - Store celestial axis information
   Channel         - Basic (textual) I/O channel
      FitsChan     - I/O Channel using FITS header cards
      XmlChan      - I/O Channel using XML
      StcsChan     - I/O Channel using IVOA STC-S descriptions
   KeyMap          - Store a set of key/value pairs
      Table        - Store a 2-dimensional table of values
   Mapping         - Inter-relate two coordinate systems
      CmpMap       - Compound Mapping
      DssMap       - Map points using Digitised Sky Survey plate solution
      Frame        - Coordinate system description
         CmpFrame  - Compound Frame
            SpecFluxFrame - Observed value versus spectral position
         FluxFrame - Observed value at a given fixed spectral position
         FrameSet  - Set of inter-related coordinate systems
            Plot   - Provide facilities for 2D graphical output
               Plot3D - Provide facilities for 3D graphical output
         Region    - Specify areas within a coordinate system
            Box    - A box region with sides parallel to the axes of a Frame
            Circle - A circular or spherical region within a Frame
            CmpRegion  - A combination of two regions within a single Frame
            Ellipse    - An elliptical region within a 2-dimensional Frame
            Interval   - Intervals on one or more axes of a Frame.
            NullRegion - A boundless region within a Frame
            PointList  - A collection of points in a Frame
            Polygon    - A polygonal region within a 2-dimensional Frame
            Prism  - An extrusion of a Region into orthogonal dimensions
            Stc    - Represents an generic instance of an IVOA STC-X description
               StcResourceProfile - Represents an an IVOA STC-X ResourceProfile
               StcSearchLocation  - Represents an an IVOA STC-X SearchLocation
               StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation
               StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation
         SkyFrame  - Celestial coordinate system description
         SpecFrame - Spectral coordinate system description
            DSBSpecFrame - Dual sideband spectral coordinate system description
         TimeFrame - Time coordinate system description
      GrismMap     - Models the spectral dispersion produced by a grism
      IntraMap     - Map points using a private transformation function
      LutMap       - Transform 1-dimensional coordinates using a lookup table
      MathMap      - Transform coordinates using mathematical expressions
      MatrixMap    - Map positions by multiplying them by a matrix
      NormMap      - Normalise coordinates using a supplied Frame
      PcdMap       - Apply 2-dimensional pincushion/barrel distortion
      PermMap      - Coordinate permutation Mapping
      PolyMap      - General N-dimensional polynomial Mapping
      RateMap      - Calculates an element of a Mapping's Jacobian matrix
      SelectorMap  - Locates positions within a set of Regions
      ShiftMap     - Shifts each axis by a constant amount
      SlaMap       - Sequence of celestial coordinate conversions
      SpecMap      - Sequence of spectral coordinate conversions
      SphMap       - Map 3-d Cartesian to 2-d spherical coordinates
      SwitchMap    - Encapuslates a set of alternate Mappings
      TimeMap      - Sequence of time coordinate conversions
      TranMap      - Combine fwd. and inv. transformations from two Mappings
      UnitMap      - Unit (null) Mapping
      UnitNormMap  - Converts a vector to a unit vector plus length
      WcsMap       - Implement a FITS-WCS sky projection
      WinMap       - Match windows by scaling and shifting each axis
      ZoomMap      - Zoom coordinates about the origin
\end{terminalv}
\normalsize

\cleardoublepage
\section{\label{ss:functiondescriptions}AST Function Descriptions}
\small
\sstroutine{
   astSet
}{
   Set attribute values for an Object
}{
   \sstdescription{
      This function assigns a set of attribute values to an \htmlref{Object}{Object},
      over-riding any previous values. The attributes and their new
      values are specified via a character string, which should
      contain a comma-separated list of the form:

         \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"}

      where \texttt{"} attribute\_n\texttt{"}  specifies an attribute name, and the value
      to the right of each \texttt{"} =\texttt{"}  sign should be a suitable textual
      representation of the value to be assigned. This value will be
      interpreted according to the attribute\texttt{'} s data type.

      The string supplied may also contain \texttt{"} printf\texttt{"} -style format
      specifiers, identified by \texttt{"} \%\texttt{"}  signs in the usual way. If
      present, these will be substituted by values supplied as
      additional optional arguments (using the normal \texttt{"} printf\texttt{"}  rules)
      before the string is used.
   }
   \sstsynopsis{
      void astSet( AstObject $*$this, const char $*$settings, ... )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         settings
      }{
         Pointer to a null-terminated character string containing a
         comma-separated list of attribute settings in the form described
         above.
      }
      \sstsubsection{
         ...
      }{
         Optional additional arguments which supply values to be
         substituted for any \texttt{"} printf\texttt{"} -style format specifiers that
         appear in the \texttt{"} settings\texttt{"}  string.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"}  );
      }{
         Sets the Report attribute for Object \texttt{"} map\texttt{"}  to the value 1 and
         the Zoom attribute to 25.0.
      }
      \sstexamplesubsection{
         astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis );
      }{
         Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"}  to a
         suitable string, where the axis number is obtained from
         \texttt{"} axis\texttt{"} , a variable of type int.
      }
      \sstexamplesubsection{
         astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring );
      }{
         Sets the Title attribute for Object \texttt{"} frame\texttt{"}  to the contents of
         the string \texttt{"} mystring\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         White space may also surround attribute values, where it will
         generally be ignored (except for string-valued attributes where
         it is significant and forms part of the value to be assigned).

         \sstitem
         To include a literal comma in the value assigned to an attribute,
         the whole attribute value should be enclosed in quotation markes.
         Alternatively, you can use \texttt{"} \%s\texttt{"}  format and supply the value as a
         separate additional argument to astSet (or use the astSetC
         function instead).

         \sstitem
         The same procedure may be adopted if \texttt{"} \%\texttt{"}  signs are to be included
         and are not to be interpreted as format specifiers (alternatively,
         the \texttt{"} printf\texttt{"}  convention of writing \texttt{"} \%\%\texttt{"}  may be used).

         \sstitem
         An error will result if an attempt is made to set a value for
         a read-only attribute.
      }
   }
}
\sstroutine{
   astAddColumn
}{
   Add a new column definition to a table
}{
   \sstdescription{
      Adds the definition of a new column to the supplied table. Initially,
      the column is empty. Values may be added subsequently using the
      methods of the \htmlref{KeyMap}{KeyMap} class.
   }
   \sstsynopsis{
      void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim,
                         int $*$dims, const char $*$unit )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Table}{Table}.
      }
      \sstsubsection{
         name
      }{
         The column name. Trailing spaces are ignored (all other spaces
         are significant). The supplied string is converted to upper case.
      }
      \sstsubsection{
         type
      }{
         The data type associated with the column. See \texttt{"} Applicability:\texttt{"}
         below.
      }
      \sstsubsection{
         ndim
      }{
         The number of dimensions spanned by the values stored in a single
         cell of the column. Zero if the column holds scalar values.
      }
      \sstsubsection{
         dims
      }{
         An array holding the the lengths of each of the axes spanned by
         the values stored in a single cell of the column. Ignored if the
         column holds scalara values.
      }
      \sstsubsection{
         unit
      }{
         A string specifying the units of the column. Supply a blank
         string if the column is unitless.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Table
      }{
         Tables can hold columns with any of the following data types -
         AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
         short int),
         AST\_\_BYTETYPE (for
         unsigned bytes - i.e. unsigned chars),
         AST\_\_DOUBLETYPE (for double
         precision floating point), AST\_\_FLOATTYPE (for single
         precision floating point), AST\_\_STRINGTYPE (for character string),
         AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
         arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
         created by
         \htmlref{astMapPutU}{astMapPutU}).
      }
      \sstsubsection{
         \htmlref{FitsTable}{FitsTable}
      }{
         FitsTables can hold columns with any of the following data types -
         AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
         short int),
         AST\_\_BYTETYPE (for
         unsigned bytes - i.e. unsigned chars),
         AST\_\_DOUBLETYPE (for double
         precision floating point), AST\_\_FLOATTYPE (for single
         precision floating point), AST\_\_STRINGTYPE (for character string).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This
         function
         returns without action if a column already exists in the Table
         with the supplied name and properties. However an error is
         reported if any of the properties differ.
      }
   }
}
\sstroutine{
   astAddFrame
}{
   Add a Frame to a FrameSet to define a new coordinate system
}{
   \sstdescription{
      This function adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a
      \htmlref{FrameSet}{FrameSet} so as to define a new coordinate system, derived from
      one which already exists within the FrameSet. The new Frame then
      becomes the FrameSet\texttt{'} s current Frame.

      This function
      may also be used to merge two FrameSets, or to append extra axes
      to every Frame in a FrameSet.
   }
   \sstsynopsis{
      void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map,
                        AstFrame $*$frame )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe
      }{
         The index of the Frame within the FrameSet which describes
         the coordinate system upon which the new one is to be based.
         This value should lie in the range from 1 to the number of
         Frames already in the FrameSet (as given by its \htmlref{Nframe}{Nframe}
         attribute). As a special case, AST\_\_ALLFRAMES may be supplied,
         in which case the axes defined by the supplied Frame are appended
         to every Frame in the FrameSet (see the Notes section for details).
      }
      \sstsubsection{
         map
      }{
         Pointer to a Mapping which describes how to convert
         coordinates from the old coordinate system (described by the
         Frame with index \texttt{"} iframe\texttt{"} ) into coordinates in the new
         system. The Mapping\texttt{'} s forward transformation should perform
         this conversion, and its inverse transformation should
         convert in the opposite direction. The supplied Mapping is ignored
         if parameter \texttt{"} iframe\texttt{"} is equal to AST\_\_ALLFRAMES.
      }
      \sstsubsection{
         frame
      }{
         Pointer to a Frame that describes the new coordinate system.
         Any class of Frame may be supplied (including Regions and
         FrameSets).

         This function may also be used to merge two FrameSets by
         supplying a pointer to a second FrameSet for this parameter
         (see the Notes section for details).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Deep copies of the supplied
         \texttt{"} mapping\texttt{"}  and \texttt{"} frame\texttt{"}
         objects are stored within the modified FrameSet. So any changes made
         to the FrameSet after calling this method will have no effect on the
         supplied Mapping and Frame objects.

         \sstitem
         A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
         Frame respectively.

         \sstitem
         This function sets the value of the \htmlref{Current}{Current} attribute for the
         FrameSet so that the new Frame subsequently becomes the current
         Frame.

         \sstitem
         The number of input coordinate values accepted by the supplied
         Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the
         Frame identified by the \texttt{"} iframe\texttt{"}  parameter. Similarly, the
         number of output coordinate values generated by this Mapping
         (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new
         Frame.

         \sstitem
         As a special case, if a pointer to a FrameSet is given for the
         \texttt{"} frame\texttt{"}  parameter, this is treated as a request to merge a pair of
         FrameSets.  This is done by appending all the new Frames (in the
         \texttt{"} frame\texttt{"}  FrameSet) to the original FrameSet, while preserving
         their order and retaining all the inter-relationships
         (i.e. Mappings) between them. The two sets of Frames are
         inter-related within the merged FrameSet by using the Mapping
         supplied. This should convert between the Frame identified by
         the \texttt{"} iframe\texttt{"}  parameter (in the original FrameSet) and the current
         Frame of the \texttt{"} frame\texttt{"}  FrameSet. This latter Frame becomes the
         current Frame in the merged FrameSet.

         \sstitem
         As another special case, if a value of AST\_\_ALLFRAMES is supplied
         for parameter
         \texttt{"} iframe\texttt{"} ,
         then the supplied Mapping is ignored, and the axes defined by the
         supplied Frame are appended to each Frame in the FrameSet. In detail,
         each Frame in the FrameSet is replaced by a \htmlref{CmpFrame}{CmpFrame} containing the
         original Frame and the Frame specified by parameter
         \texttt{"} frame\texttt{"} .
         In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap}
         containing the original Mapping and a \htmlref{UnitMap}{UnitMap} in parallel. The Nin and
         Nout attributes of the UnitMap are set equal to the number of axes
         in the supplied Frame. Each new CmpMap is simplified using
         \htmlref{astSimplify}{astSimplify}
         before being stored in the FrameSet.
      }
   }
}
\sstroutine{
   astAddParameter
}{
   Add a new global parameter definition to a table
}{
   \sstdescription{
      Adds the definition of a new global parameter to the supplied
      table. Note, this does not store a value for the parameter. To get
      or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class
      should be used, using the name of the parameter as the key.
   }
   \sstsynopsis{
      void astAddParameter( AstTable $*$this, const char $*$name )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Table}{Table}.
      }
      \sstsubsection{
         name
      }{
         The parameter name. Trailing spaces are ignored (all other spaces
         are significant). The supplied string is converted to upper case.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Unlike columns, the definition of a parameter does not specify its type,
         size or dimensionality.
      }
   }
}
\sstroutine{
   astAddVariant
}{
   Store a new variant Mapping for the current Frame in a FrameSet
}{
   \sstdescription{
      This function
      allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame}
      in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"}  attribute for more details. It can
      also be used to rename the currently selected variant Mapping.
   }
   \sstsynopsis{
      void astAddVariant( AstFrameSet $*$this, AstMapping $*$map,
                          const char $*$name, int $*$status )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         map
      }{
         Pointer to a Mapping which describes how to convert
         coordinates from the current Frame to the new variant of the
         current Frame. If
         NULL
         is supplied, then the name associated with the currently selected
         variant of the current Frame is set to the value supplied for
         \texttt{"} name\texttt{"} , but no new variant is added.
      }
      \sstsubsection{
         name
      }{
         The name to associate with the new variant Mapping (or the currently
         selected variant Mapping if
         \texttt{"} map\texttt{"}  is NULL).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The newly added Variant becomes the current variant on exit (this is
         equivalent to setting the Variant attribute to the value supplied for
         \texttt{"} name).

         \sstitem
         An error is reported if a variant with the supplied name already
         exists in the current Frame.

         \sstitem
         An error is reported if the current Frame is a mirror for the
         variant Mappings in another Frame. This is only the case if the
         \htmlref{astMirrorVariants}{astMirrorVariants} function
         has been called to make the current Frame act as a mirror.
      }
   }
}
\sstroutine{
   astAngle
}{
   Calculate the angle subtended by two points at a third point
}{
   \sstdescription{
      This function
      finds the angle at point B between the line joining points A and B,
      and the line joining points C and B. These lines will in fact be
      geodesic curves appropriate to the \htmlref{Frame}{Frame} in use. For instance, in
      \htmlref{SkyFrame}{SkyFrame}, they will be great circles.
   }
   \sstsynopsis{
      double astAngle( AstFrame $*$this, const double a[], const double b[],
                       const double c[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         a
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
      }
      \sstsubsection{
         b
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute) containing the coordinates of the second point.
      }
      \sstsubsection{
         c
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute) containing the coordinates of the third point.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAngle
      }{
         The angle in radians, from the line AB to the line CB. If the
         Frame is 2-dimensional, it will be in the range \$$\backslash$pm $\backslash$pi\$,
         and positive rotation is in the same sense as rotation from
         the positive direction of axis 2 to the positive direction of
         axis 1. If the Frame has more than 2 axes, a positive value will
         always be returned in the range zero to \$$\backslash$pi\$.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of AST\_\_BAD will also be returned if points A and B are
         co-incident, or if points B and C are co-incident.

         \sstitem
         A value of AST\_\_BAD will also be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astAnnul
}{
   Annul a pointer to an Object
}{
   \sstdescription{
      This function annuls a pointer to an \htmlref{Object}{Object} so that it is no
      longer recognised as a valid pointer by the AST library. Any
      resources associated with the pointer are released and made
      available for re-use.

      This function also decrements the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute by
      one. If this attribute reaches zero (which happens when the last
      pointer to the Object is annulled), then the Object is deleted.
   }
   \sstsynopsis{
      AstObject $*$astAnnul( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         The Object pointer to be annulled.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAnnul()
      }{
         A null Object pointer (AST\_\_NULL) is always returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function will attempt to annul the pointer even if the
         Object is not currently locked by the calling thread (see \htmlref{astLock}{astLock}).

         \sstitem
         This function attempts to execute even if the AST error
         status is set
         on entry, although no further error report will be
         made if it subsequently fails under these circumstances. In
         particular, it will fail if the pointer suppled is not valid,
         but this will only be reported if the error status is clear on
         entry.
      }
   }
}
\sstroutine{
   astAxAngle
}{
   Returns the angle from an axis, to a line through two points
}{
   \sstdescription{
      This function
      finds the angle, as seen from point A, between the positive
      direction of a specified axis, and the geodesic curve joining point
      A to point B.
   }
   \sstsynopsis{
      double astAxAngle( AstFrame $*$this, const double a[], const double b[], int axis )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Frame}{Frame}.
      }
      \sstsubsection{
         a
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
      }
      \sstsubsection{
         b
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute) containing the coordinates of the second point.
      }
      \sstsubsection{
         axis
      }{
         The number of the Frame axis from which the angle is to be
         measured (axis numbering starts at 1 for the first axis).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAxAngle
      }{
         The angle in radians, from the positive direction of the
         specified axis, to the line AB. If the Frame is 2-dimensional,
         it will be in the range [-PI/2,$+$PI/2], and positive rotation is in
         the same sense as rotation from the positive direction of axis 2
         to the positive direction of axis 1. If the Frame has more than 2
         axes, a positive value will always be returned in the range zero
         to PI.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The geodesic curve used by this function is the path of
         shortest distance between two points, as defined by the
         \htmlref{astDistance}{astDistance} function.

         \sstitem
         This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
         if any of the input coordinates has this value, or if the require
         position angle is undefined.
      }
   }
}
\sstroutine{
   astAxDistance
}{
   Find the distance between two axis values
}{
   \sstdescription{
      This function returns a signed value representing the axis increment
      from axis value v1 to axis value v2.

      For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the
      difference between the two axis values. But for other derived classes
      of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case.
   }
   \sstsynopsis{
      double astAxDistance( AstFrame $*$this, int axis, double v1, double v2 )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         axis
      }{
         The index of the axis to which the supplied values refer. The
         first axis has index 1.
      }
      \sstsubsection{
         v1
      }{
         The first axis value.
      }
      \sstsubsection{
         v2
      }{
         The second axis value.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAxDistance
      }{
         The distance from the first to the second axis value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
         any of the input values has this value.

         \sstitem
         A \texttt{"} bad\texttt{"}  value will also be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astAxNorm
}{
   Normalise an array of axis values
}{
   \sstdescription{
      This function
      modifies a supplied array of axis values so that they are normalised
      in the manner indicated by
      parameter \texttt{"} oper\texttt{"} .

      No normalisation is possible for a simple \htmlref{Frame}{Frame} and so the supplied
      values are returned unchanged. However, this may not be the case for
      specialised sub-classes of Frame. For instance, a \htmlref{SkyFrame}{SkyFrame} has a
      discontinuity at zero longitude and so a longitude value can be
      expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the
      \texttt{"} Applicability:\texttt{"}  section below for details.
   }
   \sstsynopsis{
      void astAxNorm( AstFrame $*$this, int axis, int oper, int nval,
                      double $*$values, int $*$status )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         axis
      }{
         The index of the axis to which the supplied values refer. The
         first axis has index 1.
      }
      \sstsubsection{
         oper
      }{
         Indicates the type of normalisation to be applied. If zero is
         supplied, the normalisation will be the same as that performed by
         function \htmlref{astNorm}{astNorm}.
         If 1 is supplied, the normalisation will be chosen automatically
         so that the resulting list has the smallest range.
      }
      \sstsubsection{
         nval
      }{
         The number of points in the values array.
      }
      \sstsubsection{
         values
      }{
         On entry, the axis values to be normalised. Modified on exit to
         hold the normalised values.
      }
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         If \texttt{"} oper\texttt{"}
         is 0, longitude values are returned in the range [0,2$*$PI].
         If \texttt{"} oper\texttt{"}
         is 1, longitude values are returned in either the range
         [0,2$*$PI] or [-PI,PI]. The choice is made so that that the
         resulting list has the smallest range. Latitude values are
         always returned in the range [-PI,PI].
      }
      \sstsubsection{
         All other classes of Frame
      }{
         The supplied axis values are returned unchanged.
      }
   }
}
\sstroutine{
   astAxOffset
}{
   Add an increment onto a supplied axis value
}{
   \sstdescription{
      This function returns an axis value formed by adding a signed axis
      increment onto a supplied axis value.

      For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the
      sum of the two supplied values. But for other derived classes
      of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case.
   }
   \sstsynopsis{
      double astAxOffset( AstFrame $*$this, int axis, double v1, double dist )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         axis
      }{
         The index of the axis to which the supplied values refer. The
         first axis has index 1.
      }
      \sstsubsection{
         v1
      }{
         The original axis value.
      }
      \sstsubsection{
         dist
      }{
         The axis increment to add to the original axis value.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAxOffset
      }{
         The incremented axis value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
         any of the input values has this value.

         \sstitem
         A \texttt{"} bad\texttt{"}  value will also be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astBBuf
}{
   Begin a new graphical buffering context
}{
   \sstdescription{
      This function
      starts a new graphics buffering context. A matching call to the
      function \htmlref{astEBuf}{astEBuf}
      should be used to end the context.
   }
   \sstsynopsis{
      void astBBuf( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Plot}{Plot}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The nature of the buffering is determined by the underlying
         graphics system (as defined by the current grf module). Each call
         to this function
         to this function
         simply invokes the astGBBuf function in the grf module.
      }
   }
}
\sstroutine{
   astBegin
}{
   Begin a new AST context
}{
   \sstdescription{
      This macro invokes a function to begin a new AST context.
      Any \htmlref{Object}{Object} pointers
      created within this context will be annulled when it is later
      ended using \htmlref{astEnd}{astEnd} (just as if \htmlref{astAnnul}{astAnnul} had been invoked),
      unless they have first been exported using \htmlref{astExport}{astExport} or rendered
      exempt using \htmlref{astExempt}{astExempt}. If
      annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
      fall to zero (which happens when the last pointer to it is
      annulled), then the Object will be deleted.
   }
   \sstsynopsis{
      void astBegin
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This macro applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         astBegin attempts to execute even if the AST error status
         is set on entry.

         \sstitem
         Contexts delimited by astBegin and astEnd may be nested to any
         depth.
      }
   }
}
\sstroutine{
   astBorder
}{
   Draw a border around valid regions of a Plot
}{
   \sstdescription{
      This function draws a (line) border around regions of the
      plotting area of a \htmlref{Plot}{Plot} which correspond to valid, unclipped
      physical coordinates. For example, when plotting using an
      all-sky map projection, this function could be used to draw the
      boundary of the celestial sphere when it is projected on to the
      plotting surface.

      If the entire plotting area contains valid, unclipped physical
      coordinates, then the boundary will just be a rectangular box
      around the edges of the plotting area.

      If the Plot is a \htmlref{Plot3D}{Plot3D}, this method is applied individually to
      each of the three 2D Plots encapsulated within the Plot3D (each of
      these Plots corresponds to a single 2D plane in the 3D graphics
      system). In addition, if the entire plotting volume has valid
      coordinates in the 3D current \htmlref{Frame}{Frame} of the Plot3D, then additional
      lines are drawn along the edges of the 3D plotting volume so that
      the entire plotting volume is enclosed within a cuboid grid.
   }
   \sstsynopsis{
      int astBorder( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astBorder()
      }{
         Zero is returned if the plotting space is completely filled by
         valid, unclipped physical coordinates (so that only a
         rectangular box was drawn around the edge). Otherwise, one is
         returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.

         \sstitem
         An error results if either the current Frame or the base Frame
         of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.

         \sstitem
         An error also results if the transformation between the base
         and current Frames of the Plot is not defined (i.e. the Plot\texttt{'} s
         \htmlref{TranForward}{TranForward} attribute is zero).
      }
   }
}
\sstroutine{
   astBoundingBox
}{
   Return a bounding box for previously drawn graphics
}{
   \sstdescription{
      This function returns the bounds of a box which just encompasess the
      graphics produced by the previous call to any of the \htmlref{Plot}{Plot} methods
      which produce graphical output. If no such previous call has yet
      been made, or if the call failed for any reason, then the bounding box
      returned by this function is undefined.
   }
   \sstsynopsis{
      void astBoundingBox( AstPlot $*$this, float lbnd[2], float ubnd[2] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         lbnd
      }{
         A two element array in which is returned the lower limits of the
         bounding box on each of the two axes of the graphics coordinate
         system (the base \htmlref{Frame}{Frame} of the Plot).
      }
      \sstsubsection{
         ubnd
      }{
         A two element array in which is returned the upper limits of the
         bounding box on each of the two axes of the graphics coordinate
         system (the base Frame of the Plot).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error results if the base Frame of the Plot is not
         2-dimensional.
      }
   }
}
\sstroutine{
   astBox
}{
   Create a Box
}{
   \sstdescription{
      This function creates a new \htmlref{Box}{Box} and optionally initialises its
      attributes.

      The Box class implements a \htmlref{Region}{Region} which represents a box with sides
      parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given
      range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the
      only real difference being that the Interval class allows some axis
      limits to be unspecified. Note, a Box will only look like a box if
      the Frame geometry is approximately flat. For instance, a Box centred
      close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box
      (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a
      pole).
   }
   \sstsynopsis{
      AstBox $*$astBox( AstFrame $*$frame, int form, const double point1[],
                      const double point2[], AstRegion $*$unc,
                      const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. A deep
         copy is taken of the supplied Frame. This means that any
         subsequent changes made to the Frame using the supplied pointer
         will have no effect the Region.
      }
      \sstsubsection{
         form
      }{
         Indicates how the box is described by the remaining parameters.
         A value of zero indicates that the box is specified by a centre
         position and a corner position. A value of one indicates that the
         box is specified by a two opposite corner positions.
      }
      \sstsubsection{
         point1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). If
         \texttt{"} form\texttt{"}
         is zero, this array should contain the coordinates at the centre of
         the box.
         If \texttt{"} form\texttt{"}
         is one, it should contain the coordinates at the corner of the box
         which is diagonally opposite the corner specified by
         \texttt{"} point2\texttt{"} .
      }
      \sstsubsection{
         point2
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute) containing the coordinates at any corner of the
         box.
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with the boundary of the Box being created.
         The uncertainty in any point on the boundary of the Box is found by
         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
         the boundary point being considered. The area covered by the
         shifted uncertainty Region then represents the uncertainty in the
         boundary position. The uncertainty is assumed to be the same for
         all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Box. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the Box being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Box. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astBox()
      }{
         A pointer to the new Box.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astChannel
}{
   Create a Channel
}{
   \sstdescription{
      This function creates a new \htmlref{Channel}{Channel} and optionally initialises
      its attributes.

      A Channel implements low-level input/output for the AST library.
      Writing an \htmlref{Object}{Object} to a Channel (using \htmlref{astWrite}{astWrite}) will generate a
      textual representation of that Object, and reading from a
      Channel (using \htmlref{astRead}{astRead}) will create a new Object from its
      textual representation.

      Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting text. By default, however,
      a Channel will read from standard input and write to standard
      output. Alternatively, a Channel can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.
   }
   \sstsynopsis{
      AstChannel $*$astChannel( const char $*$($*$ source)( void ),
                              void ($*$ sink)( const char $*$ ),
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         source
      }{
         Pointer to a source function that takes no arguments and
         returns a pointer to a null-terminated string.  If no value
         has been set for the SourceFile attribute, this function
         will be used by the Channel to obtain lines of input text. On
         each invocation, it should return a pointer to the next input
         line read from some external data store, and a NULL pointer
         when there are no more lines to read.

         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
         attribute, the Channel will read from standard input instead.
      }
      \sstsubsection{
         sink
      }{
         Pointer to a sink function that takes a pointer to a
         null-terminated string as an argument and returns void.
         If no value has been set for the SinkFile attribute, this
         function will be used by the Channel to deliver lines of
         output text. On each invocation, it should deliver the
         contents of the string supplied to some external data store.

         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
         attribute, the Channel will write to standard output instead.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Channel. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChannel()
      }{
         A pointer to the new Channel.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Application code can pass arbitrary data (such as file
         descriptors, etc) to source and sink functions using the
         \htmlref{astPutChannelData}{astPutChannelData} function. The source or sink function should use
         the \htmlref{astChannelData}{astChannelData} macro to retrieve this data.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astChannelData
}{
   Return a pointer to user-supplied data stored with a Channel
}{
   \sstdescription{
      This macro is intended to be used within the source or sink
      functions associated with a \htmlref{Channel}{Channel}. It returns any pointer
      previously stored in the Channel (that is, the Channel that has
      invoked the source or sink function) using \htmlref{astPutChannelData}{astPutChannelData}.

      This mechanism is a thread-safe alternative to passing file
      descriptors, etc, via static global variables.
   }
   \sstsynopsis{
      void $*$astChannelData
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         This macro applies to all Channels.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChannelData
      }{
         The pointer previously stored with the Channel using
         astPutChannelData. A NULL pointer will be returned if no such
         pointer has been stored with the Channel.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This routine is not available in the Fortran 77 interface to
         the AST library.
      }
   }
}
\sstroutine{
   astCircle
}{
   Create a Circle
}{
   \sstdescription{
      This function creates a new \htmlref{Circle}{Circle} and optionally initialises its
      attributes.

      A Circle is a \htmlref{Region}{Region} which represents a circle or sphere within the
      supplied \htmlref{Frame}{Frame}.
   }
   \sstsynopsis{
      AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[],
                            const double point[], AstRegion $*$unc,
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. A deep
         copy is taken of the supplied Frame. This means that any
         subsequent changes made to the Frame using the supplied pointer
         will have no effect the Region.
      }
      \sstsubsection{
         form
      }{
         Indicates how the circle is described by the remaining parameters.
         A value of zero indicates that the circle is specified by a
         centre position and a position on the circumference. A value of one
         indicates that the circle is specified by a centre position and a
         scalar radius.
      }
      \sstsubsection{
         centre
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of
         the circle or sphere.
      }
      \sstsubsection{
         point
      }{
         If \texttt{"} form\texttt{"}
         is zero, then this array should have one element for each Frame
         axis (Naxes attribute), and should be supplied holding the
         coordinates at a point on the circumference of the circle or sphere.
         If \texttt{"} form\texttt{"}
         is one, then this array should have one element only which should
         be supplied holding the scalar radius of the circle or sphere,
         as a geodesic distance within the Frame.
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with the boundary of the Circle being created.
         The uncertainty in any point on the boundary of the Circle is found by
         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
         the boundary point being considered. The area covered by the
         shifted uncertainty Region then represents the uncertainty in the
         boundary position. The uncertainty is assumed to be the same for
         all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, Circle, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Circle. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the Circle being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Circle. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCircle()
      }{
         A pointer to the new Circle.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astCirclePars
}{
   Returns the geometric parameters of an Circle
}{
   \sstdescription{
      This function
      returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}.
   }
   \sstsynopsis{
      void astCirclePars( AstCircle $*$this, double $*$centre, double $*$radius,
                          double $*$p1 )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Region}{Region}.
      }
      \sstsubsection{
         centre
      }{
         Pointer to an array
         in which to return the coordinates of the Circle centre.
         The length of this array should be no less than the number of
         axes in the associated coordinate system.
      }
      \sstsubsection{
         radius
      }{
         Returned holding the radius of the Circle, as an geodesic
         distance in the associated coordinate system.
      }
      \sstsubsection{
         p1
      }{
         Pointer to an array
         in which to return the coordinates of a point on the
         circumference of the Circle. The length of this array should be
         no less than the number of axes in the associated coordinate system.
         A NULL pointer can be supplied if the circumference position is
         not needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the coordinate system represented by the Circle has been
         changed since it was first created, the returned parameters refer
         to the new (changed) coordinate system, rather than the original
         coordinate system. Note however that if the transformation from
         original to new coordinate system is non-linear, the shape
         represented by the supplied Circle object may not be an accurate
         circle.
      }
   }
}
\sstroutine{
   astClear
}{
   Clear attribute values for an Object
}{
   \sstdescription{
      This function clears the values of a specified set of attributes
      for an \htmlref{Object}{Object}. Clearing an attribute cancels any value that has
      previously been explicitly set for it, so that the standard
      default attribute value will subsequently be used instead. This
      also causes the \htmlref{astTest}{astTest} function to return the value zero for
      the attribute, indicating that no value has been set.
   }
   \sstsynopsis{
      void astClear( AstObject $*$this, const char $*$attrib )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         attrib
      }{
         Pointer to a null-terminated character string containing a
         comma-separated list of the names of the attributes to be cleared.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         It does no harm to clear an attribute whose value has not been
         set.

         \sstitem
         An error will result if an attempt is made to clear the value
         of a read-only attribute.
      }
   }
}
\sstroutine{
   astClearStatus
}{
   Clear the AST error status
}{
   \sstdescription{
      This macro resets the AST error status to an OK value,
      indicating that an error condition (if any) has been cleared.
   }
   \sstsynopsis{
      void astClearStatus
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the AST error status is set to an error value (after an
         error), most AST functions will not execute and will simply
         return without action. Using astClearStatus will restore normal
         behaviour.
      }
   }
}
\sstroutine{
   astClip
}{
   Set up or remove clipping for a Plot
}{
   \sstdescription{
      This function defines regions of a \htmlref{Plot}{Plot} which are to be clipped.
      Any subsequent graphical output created using the Plot will then
      be visible only within the unclipped regions of the plotting
      area. See also the \htmlref{Clip}{Clip} attribute.
   }
   \sstsynopsis{
      void astClip( AstPlot $*$this, int iframe, const double lbnd[],
                    const double ubnd[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         iframe
      }{
         The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping
         limits supplied in \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  (below) refer. Clipping
         may be applied to any of the coordinate systems associated
         with a Plot (as defined by the Frames it contains), so this
         index may take any value from 1 to the number of Frames in
         the Plot (\htmlref{Nframe}{Nframe} attribute). In addition, the values
         AST\_\_BASE and AST\_\_CURRENT may be used to specify the base
         and current Frames respectively.

         For example, a value of AST\_\_CURRENT causes clipping to be
         performed in physical coordinates, while a value of AST\_\_BASE
         would clip in graphical coordinates. Clipping may also be
         removed completely by giving a value of AST\_\_NOFRAME. In this
         case any clipping bounds supplied (below) are ignored.
      }
      \sstsubsection{
         lbnd
      }{
         An array with one element for each axis of the clipping Frame
         (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the
         lower bound, on each axis, of the region which is to remain
         visible (unclipped).
      }
      \sstsubsection{
         ubnd
      }{
         An array with one element for each axis of the clipping Frame
         (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the
         upper bound, on each axis, of the region which is to remain
         visible (unclipped).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Only one clipping Frame may be active at a time. This function
         will deactivate any previously-established clipping Frame before
         setting up new clipping limits.

         \sstitem
         The clipping produced by this function is in addition to that
         specified by the Clip attribute which occurs at the edges of the
         plotting area
         established when the Plot is created (see \htmlref{astPlot}{astPlot}). The
         underlying graphics system may also impose further clipping.

         \sstitem
         When testing a graphical position for clipping, it is first
         transformed into the clipping Frame. The resulting coordinate on
         each axis is then checked against the clipping limits (given by
         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} ). By default, a position is clipped if any
         coordinate lies outside these limits. However, if a non-zero
         value is assigned to the Plot\texttt{'} s \htmlref{ClipOp}{ClipOp} attribute, then a
         position is only clipped if the coordinates on all axes lie
         outside their clipping limits.

         \sstitem
         If the lower clipping limit exceeds the upper limit for any
         axis, then the sense of clipping for that axis is reversed (so
         that coordinate values lying between the limits are clipped
         instead of those lying outside the limits). To produce a \texttt{"} hole\texttt{"}
         in a coordinate space (that is, an internal region where nothing
         is plotted), you should supply all the bounds in reversed order,
         and set the ClipOp attribute for the Plot to a non-zero value.

         \sstitem
         Either clipping limit may be set to the value AST\_\_BAD, which
         is equivalent to setting it to infinity (or minus infinity for a
         lower bound) so that it is not used.

         \sstitem
         If a graphical position results in any bad coordinate values
         (AST\_\_BAD) when transformed into the clipping Frame, then it is
         treated (for the purposes of producing graphical output) as if
         it were clipped.

         \sstitem
         When a Plot is used as a \htmlref{Mapping}{Mapping} to transform points
         (e.g. using \htmlref{astTran2}{astTran2}), any clipped output points are assigned
         coordinate values of AST\_\_BAD.

         \sstitem
         An error results if the base Frame of the Plot is not
         2-dimensional.
      }
   }
}
\sstroutine{
   astClone
}{
   Clone (duplicate) an Object pointer
}{
   \sstdescription{
      This function returns a duplicate pointer to an existing
      \htmlref{Object}{Object}. It also increments the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
      keep track of how many pointers have been issued.

      Note that this function is NOT equivalent to an assignment
      statement, as in general the two pointers will not have the same
      value.
   }
   \sstsynopsis{
      AstObject $*$astClone( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Original pointer to the Object.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astClone()
      }{
         A duplicate pointer to the same Object.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astCmpFrame
}{
   Create a CmpFrame
}{
   \sstdescription{
      This function creates a new \htmlref{CmpFrame}{CmpFrame} and optionally initialises
      its attributes.

      A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames
      (of any class) to be merged together to form a more complex
      Frame. The axes of the two component Frames then appear together
      in the resulting CmpFrame (those of the first Frame, followed by
      those of the second Frame).

      Since a CmpFrame is itself a Frame, it can be used as a
      component in forming further CmpFrames. Frames of arbitrary
      complexity may be built from simple individual Frames in this
      way.

      Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a
      Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap},
      but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region}
      (a sub-class of Frame), then the CmpFrame will use the Region as a
      Mapping when transforming values for axes described by the Region.
      Thus input axis values corresponding to positions which are outside the
      Region will result in bad output axis values.
   }
   \sstsynopsis{
      AstCmpFrame $*$astCmpFrame( AstFrame $*$frame1, AstFrame $*$frame2,
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame1
      }{
         Pointer to the first component Frame.
      }
      \sstsubsection{
         frame2
      }{
         Pointer to the second component Frame.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new CmpFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCmpFrame()
      }{
         A pointer to the new CmpFrame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astCmpMap
}{
   Create a CmpMap
}{
   \sstdescription{
      This function creates a new \htmlref{CmpMap}{CmpMap} and optionally initialises
      its attributes.

      A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component
      Mappings (of any class) to be connected together to form a more
      complex Mapping. This connection may either be \texttt{"} in series\texttt{"}
      (where the first Mapping is used to transform the coordinates of
      each point and the second mapping is then applied to the
      result), or \texttt{"} in parallel\texttt{"}  (where one Mapping transforms the
      earlier coordinates for each point and the second Mapping
      simultaneously transforms the later coordinates).

      Since a CmpMap is itself a Mapping, it can be used as a
      component in forming further CmpMaps. Mappings of arbitrary
      complexity may be built from simple individual Mappings in this
      way.
   }
   \sstsynopsis{
      AstCmpMap $*$astCmpMap( AstMapping $*$map1, AstMapping $*$map2, int series,
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         map1
      }{
         Pointer to the first component Mapping.
      }
      \sstsubsection{
         map2
      }{
         Pointer to the second component Mapping.
      }
      \sstsubsection{
         series
      }{
         If a non-zero value is given for this parameter, the two
         component Mappings will be connected in series. A zero
         value requests that they are connected in parallel.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new CmpMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCmpMap()
      }{
         A pointer to the new CmpMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the component Mappings are connected in series, then using
         the resulting CmpMap to transform coordinates will cause the
         first Mapping to be applied, followed by the second Mapping. If
         the inverse CmpMap transformation is requested, the two
         component Mappings will be applied in both the reverse order and
         the reverse direction.

         \sstitem
         When connecting two component Mappings in series, the number
         of output coordinates generated by the first Mapping (its \htmlref{Nout}{Nout}
         attribute) must equal the number of input coordinates accepted
         by the second Mapping (its \htmlref{Nin}{Nin} attribute).

         \sstitem
         If the component Mappings of a CmpMap are connected in
         parallel, then the first Mapping will be used to transform the
         earlier input coordinates for each point (and to produce the
         earlier output coordinates) and the second Mapping will be used
         simultaneously to transform the remaining input coordinates (to
         produce the remaining output coordinates for each point). If the
         inverse transformation is requested, each Mapping will still be
         applied to the same coordinates, but in the reverse direction.

         \sstitem
         When connecting two component Mappings in parallel, there is
         no restriction on the number of input and output coordinates for
         each Mapping.

         \sstitem
         Note that the component Mappings supplied are not copied by
         astCmpMap (the new CmpMap simply retains a reference to
         them). They may continue to be used for other purposes, but
         should not be deleted. If a CmpMap containing a copy of its
         component Mappings is required, then a copy of the CmpMap should
         be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astCmpRegion
}{
   Create a CmpRegion
}{
   \sstdescription{
      This function creates a new \htmlref{CmpRegion}{CmpRegion} and optionally initialises
      its attributes.

      A CmpRegion is a \htmlref{Region}{Region} which allows two component
      Regions (of any class) to be combined to form a more complex
      Region. This combination may be performed a boolean AND, OR
      or XOR (exclusive OR) operator. If the AND operator is
      used, then a position is inside the CmpRegion only if it is
      inside both of its two component Regions. If the OR operator is
      used, then a position is inside the CmpRegion if it is inside
      either (or both) of its two component Regions. If the XOR operator
      is used, then a position is inside the CmpRegion if it is inside
      one but not both of its two component Regions. Other operators can
      be formed by negating one or both component Regions before using
      them to construct a new CmpRegion.

      The two component Region need not refer to the same coordinate
      \htmlref{Frame}{Frame}, but it must be possible for the
      \htmlref{astConvert}{astConvert}
      function to determine a \htmlref{Mapping}{Mapping} between them (an error will be
      reported otherwise when the CmpRegion is created). For instance,
      a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame}
      with a Region defined within a Galactic SkyFrame. This is
      acceptable because the SkyFrame class knows how to convert between
      these two systems, and consequently the
      astConvert
      function will also be able to convert between them. In such cases,
      the second component Region will be mapped into the coordinate Frame
      of the first component Region, and the Frame represented by the
      CmpRegion as a whole will be the Frame of the first component Region.

      Since a CmpRegion is itself a Region, it can be used as a
      component in forming further CmpRegions. Regions of arbitrary
      complexity may be built from simple individual Regions in this
      way.
   }
   \sstsynopsis{
      AstCmpRegion $*$astCmpRegion( AstRegion $*$region1, AstRegion $*$region2,
                                  int oper, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region1
      }{
         Pointer to the first component Region.
      }
      \sstsubsection{
         region2
      }{
         Pointer to the second component Region. This Region will be
         transformed into the coordinate Frame of the first region before
         use. An error will be reported if this is not possible.
      }
      \sstsubsection{
         oper
      }{
         The boolean operator with which to combine the two Regions. This
         must be one of the symbolic constants AST\_\_AND, AST\_\_OR or AST\_\_XOR.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new CmpRegion. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCmpRegion()
      }{
         A pointer to the new CmpRegion.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If one of the supplied Regions has an associated uncertainty,
         that uncertainty will also be used for the returned CmpRegion.
         If both supplied Regions have associated uncertainties, the
         uncertainty associated with the first Region will be used for the
         returned CmpRegion.

         \sstitem
         Deep copies are taken of the supplied Regions. This means that
         any subsequent changes made to the component Regions using the
         supplied pointers will have no effect on the CmpRegion.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astColumnName
}{
   Get the name of the column at a given index within the Table
}{
   \sstdescription{
      This function returns a string holding the name of the column with
      the given index within the \htmlref{Table}{Table}.

      This function is intended primarily as a means of iterating round all
      the columns in a Table. For this purpose, the number of columns in
      the Table is given by the \htmlref{Ncolumn}{Ncolumn} attribute of the Table. This function
      could then be called in a loop, with the index value going from
      zero to one less than Ncolumn.

      Note, the index associated with a column decreases monotonically with
      the age of the column: the oldest Column in the Table will have index
      one, and the Column added most recently to the Table will have the
      largest index.
   }
   \sstsynopsis{
      const char $*$astColumnName( AstTable $*$this, int index )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         index
      }{
         The index into the list of columns. The first column has index
         one, and the last has index \texttt{"} Ncolumn\texttt{"} .
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astColumnName()
      }{
         A pointer to a null-terminated string containing the
         upper case column name.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned pointer is guaranteed to remain valid and the
         string to which it points will not be over-written for a total
         of 50 successive invocations of this function. After this, the
         memory containing the string may be re-used, so a copy of the
         string should be made if it is needed for longer than this.

         \sstitem
         A NULL pointer will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astColumnNull
}{
   Get or set the null value for an integer column of a FITS table
}{
   \sstdescription{
      This function allows a null value to be stored with a named
      integer-valued column in a \htmlref{FitsTable}{FitsTable}. The supplied null value is
      assigned to the TNULLn keyword in the FITS header associated with
      the FitsTable. A value in the named column is then considered to be
      null if 1) it equals the null value supplied to this function, or
      2) no value has yet been stored in the cell.

      As well as setting a new null value, this function also returns the
      previous null value. If no null value has been set previously, a
      default value will be returned. This default will be an integer
      value that does not currently occur anywhere within the named column.
      If no such value can be found, what happens depends on whether the
      column contains any cells in which no values have yet been stored.
      If so, an error will be reported. Otherwise (i.e. if there are no
      null values in the column), an arbitrary value of zero will be
      returned as the function value, and no TNULLn keyword will be
      stored in the FITS header.

      A flag is returned indicating if the returned null value was set
      explicitly by a previous call to this function, or is a default
      value.

      A second flag is returned indicating if the named column contains
      any null values (i.e. values equal to the supplied null value, or
      cells to which no value has yet been assigned).
   }
   \sstsynopsis{
      int astColumnNull( AstFitsTable $*$this, const char $*$column, int set,
                         int newval, int $*$wasset, int $*$hasnull )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Table}{Table}.
      }
      \sstsubsection{
         column
      }{
         The character string holding the name of the column. Trailing
         spaces are ignored.
      }
      \sstsubsection{
         set
      }{
         If non-zero, the value supplied for parameter \texttt{"} newval\texttt{"}
         will be stored as the current null value, replacing any value
         set by a previous call to this function.
         If zero, the value supplied for parameter \texttt{"} newval\texttt{"}
         is ignored and the current null value is left unchanged.
      }
      \sstsubsection{
         newval
      }{
         The new null value to use. Ignored if
         \texttt{"} set\texttt{"}  is zero.
         An error will be reported if the supplied value is outside the
         range of values that can be stored in the integer data type
         associated with the column.
      }
      \sstsubsection{
         wasset
      }{
         Pointer to an int that will be returned non-zero
         if the returned null value was set previously via an
         earlier invocation of this function.
         Zero
         is returned otherwise. If the named column does not exist, or an
         error occurs, a value of
         zero is returned.
      }
      \sstsubsection{
         hasnull
      }{
         Pointer to an int that will be returned non-zero
         if and only if the named column currently contains any values
         equal to the null value on exit (i.e.
         \texttt{"} newval\texttt{"}  if \texttt{"} set\texttt{"}  is non-zero,
         or the returned function value otherwise), or contains any empty
         cells. If the named column does not exist, or an error occurs, a
         value of
         zero is returned.
         If a NULL pointer is supplied for \texttt{"} hasnull\texttt{"} , no check on the
         presence of null values will be performed.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astColumnNull()
      }{
         The null value that was in use on entry to this function. If a
         null value has been set by a previous invocation of this
         function, it will be returned. Otherwise, if
         \texttt{"} set\texttt{"}  is non-zero, the supplied \texttt{"} newval\texttt{"}
         value is returned. Otherwise, a default value is chosen (if
         possible) that does not currently occur in the named column. If
         all available values are in use in the column, an error is
         reported if and only if the column contains any empty cells.
         Otherwise, a value of zero is returned. A value of zero is also
         returned if the named column does not exist, or an error occurs.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The FITS binary table definition allows only integer-valued
         columns to have an associated null value. This routine will return
         without action if the column is not integer-valued.
      }
   }
}
\sstroutine{
   astColumnShape
}{
   Returns the shape of the values in a named column
}{
   \sstdescription{
      This function
      returns the number of dimensions spaned by each value in a named
      column of a \htmlref{Table}{Table}, together with the length of each dimension.
      These are the values supplied when the column was created using
      \htmlref{astAddColumn}{astAddColumn}.
   }
   \sstsynopsis{
      void astColumnShape( AstTable $*$this, const char $*$column, int mxdim,
                           int $*$ndim, int $*$dims )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         column
      }{
         The character string holding the upper case name of the column. Trailing
         spaces are ignored.
      }
      \sstsubsection{
         mxdim
      }{
         The length of the
         \texttt{"} dims\texttt{"}  array.
      }
      \sstsubsection{
         ndim
      }{
         Pointer to an int in which to return the
         number of dimensions spanned by values in the named column.
         This will be zero if the column contains scalar values.
      }
      \sstsubsection{
         dims
      }{
         Pointer to an
         array in which to return the length of each dimension. Any
         excess trailing elements will be filled with the value 1.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No error is reported if the requested column cannot be found in the
         given Table. A value of zero is returned for
         \texttt{"} ndim\texttt{"}  and the supplied values in \texttt{"} dims\texttt{"}
         are left unchanged.

         \sstitem
         A value of zero is returned for
         \texttt{"} ndim\texttt{"}
         if an error occurs.
      }
   }
}
\sstroutine{
   astColumnSize
}{
   Get the number of bytes needed to hold a full column of data
}{
   \sstdescription{
      This function returns the number of bytes of memory that must be
      allocated prior to retrieving the data from a column using
      \htmlref{astGetColumnData}{astGetColumnData}.
   }
   \sstsynopsis{
      size\_t astColumnSize( AstFitsTable $*$this, const char $*$column,
                            int $*$hasnull )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Table}{Table}.
      }
      \sstsubsection{
         column
      }{
         The character string holding the name of the column. Trailing
         spaces are ignored.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         \htmlref{astColumnNull}{astColumnNull}()
      }{
         The number of bytes required to store the column data.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error will be reported if the named column does not exist in
         the \htmlref{FitsTable}{FitsTable}.

         \sstitem
         Zero will be returned as the function value in an error occurs.
      }
   }
}
\sstroutine{
   astConvert
}{
   Determine how to convert between two coordinate systems
}{
   \sstdescription{
      This function compares two Frames and determines whether it is
      possible to convert between the coordinate systems which they
      represent. If conversion is possible, it returns a \htmlref{FrameSet}{FrameSet}
      which describes the conversion and which may be used (as a
      \htmlref{Mapping}{Mapping}) to transform coordinate values in either direction.

      The same function may also be used to determine how to convert
      between two FrameSets (or between a \htmlref{Frame}{Frame} and a FrameSet, or
      vice versa). This mode is intended for use when (for example)
      two images have been calibrated by attaching a FrameSet to each.
      astConvert might then be used to search for a
      celestial coordinate system that both images have in common, and
      the result could then be used to convert between the pixel
      coordinates of both images -- having effectively used their
      celestial coordinate systems to align them.

      When using FrameSets, there may be more than one possible
      intermediate coordinate system in which to perform the
      conversion (for instance, two FrameSets might both have
      celestial coordinates, detector coordinates, pixel coordinates,
      etc.). A comma-separated list of coordinate system domains may
      therefore be given which defines a priority order to use when
      selecting the intermediate coordinate system.  The path used for
      conversion must go via an intermediate coordinate system whose
      \htmlref{Domain}{Domain} attribute matches one of the domains given. If conversion
      cannot be achieved using the first domain, the next one is
      considered, and so on, until success is achieved.
   }
   \sstsynopsis{
      AstFrameSet $*$astConvert( AstFrame $*$from, AstFrame $*$to,
                               const char $*$domainlist )
   }
   \sstparameters{
      \sstsubsection{
         from
      }{
         Pointer to a Frame which represents the \texttt{"} source\texttt{"}  coordinate
         system.  This is the coordinate system in which you already
         have coordinates available.

         If a FrameSet is given, its current Frame (as determined by
         its \htmlref{Current}{Current} attribute) is taken to describe the source
         coordinate system. Note that the \htmlref{Base}{Base} attribute of this
         FrameSet may be modified by this function to indicate which
         intermediate coordinate system was used (see under
         \texttt{"} FrameSets\texttt{"}  in the \texttt{"} Applicability\texttt{"}  section for details).
      }
      \sstsubsection{
         to
      }{
         Pointer to a Frame which represents the \texttt{"} destination\texttt{"}
         coordinate system. This is the coordinate system into which
         you wish to convert your coordinates.

         If a FrameSet is given, its current Frame (as determined by
         its Current attribute) is taken to describe the destination
         coordinate system. Note that the Base attribute of this
         FrameSet may be modified by this function to indicate which
         intermediate coordinate system was used (see under
         \texttt{"} FrameSets\texttt{"}  in the \texttt{"} Applicability\texttt{"}  section for details).
      }
      \sstsubsection{
         domainlist
      }{
         Pointer to a null-terminated character string containing a
         comma-separated list of Frame domains. This may be used to
         define a priority order for the different intermediate
         coordinate systems that might be used to perform the
         conversion.

         The function will first try to obtain a conversion by making
         use only of an intermediate coordinate system whose Domain
         attribute matches the first domain in this list. If this
         fails, the second domain in the list will be used, and so on,
         until conversion is achieved. A blank domain (e.g. two
         consecutive commas) indicates that all coordinate systems
         should be considered, regardless of their domains.

         This list is case-insensitive and all white space is ignored.
         If you do not wish to restrict the domain in this way,
         you should supply an empty string. This is normally
         appropriate if either of the source or destination coordinate
         systems are described by Frames (rather than FrameSets),
         since there is then usually only one possible choice of
         intermediate coordinate system.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{DSBSpecFrame}{DSBSpecFrame}
      }{
         If the \htmlref{AlignSideBand}{AlignSideBand} attribute is non-zero, alignment occurs in the
         upper sideband expressed within the spectral system and standard of
         rest given by attributes \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}. If
         AlignSideBand is zero, the two DSBSpecFrames are aligned as if
         they were simple SpecFrames (i.e. the \htmlref{SideBand}{SideBand} is ignored).
      }
      \sstsubsection{
         Frame
      }{
         This function applies to all Frames. Alignment occurs within the
         coordinate system given by attribute AlignSystem.
      }
      \sstsubsection{
         FrameSet
      }{
         If either of the \texttt{"} from\texttt{"}  or \texttt{"} to\texttt{"}  parameters is a pointer to a
         FrameSet, then astConvert will attempt to convert from the
         coordinate system described by the current Frame of the \texttt{"} from\texttt{"}
         FrameSet to that described by the current Frame of the \texttt{"} to\texttt{"}
         FrameSet.

         To achieve this, it will consider all of the Frames within
         each FrameSet as a possible way of reaching an intermediate
         coordinate system that can be used for the conversion. There
         is then the possibility that more than one conversion path
         may exist and, unless the choice is sufficiently restricted
         by the \texttt{"} domainlist\texttt{"}  string, the sequence in which the Frames
         are considered can be important. In this case, the search
         for a conversion path proceeds as follows:
         \sstitemlist{

            \sstitem
            Each field in the \texttt{"} domainlist\texttt{"}  string is considered in turn.

            \sstitem
            The Frames within each FrameSet are considered in a
            specific order: (1) the base Frame is always considered
            first, (2) after this come all the other Frames in
            Frame-index order (but omitting the base and current Frames),
            (3) the current Frame is always considered last.  However, if
            either FrameSet\texttt{'} s \htmlref{Invert}{Invert} attribute is set to a non-zero value
            (so that the FrameSet is inverted), then its Frames are
            considered in reverse order. (Note that this still means that
            the base Frame is considered first and the current Frame
            last, because the Invert value will also cause these Frames
            to swap places.)

            \sstitem
            All source Frames are first considered (in the appropriate
            order) for conversion to the first destination Frame. If no
            suitable intermediate coordinate system emerges, they are
            then considered again for conversion to the second
            destination Frame (in the appropriate order), and so on.

            \sstitem
            Generally, the first suitable intermediate coordinate
            system found is used. However, the overall Mapping between
            the source and destination coordinate systems is also
            examined.  Preference is given to cases where both the
            forward and inverse transformations are defined (as indicated
            by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one
            transformation is defined, the forward one is preferred.

            \sstitem
            If the domain of the intermediate coordinate system matches
            the current \texttt{"} domainlist\texttt{"}  field, the conversion path is
            accepted. Otherwise, the next \texttt{"} domainlist\texttt{"}  field is considered
            and the process repeated.

         }
         If conversion is possible, the Base attributes of the two
         FrameSets will be modified on exit to identify the Frames
         used to access the intermediate coordinate system which was
         finally accepted.

         Note that it is possible to force a particular Frame within a
         FrameSet to be used as the basis for the intermediate
         coordinate system, if it is suitable, by (a) focussing
         attention on
         it by specifying its domain in the \texttt{"} domainlist\texttt{"}  string, or (b)
         making it the base Frame, since this is always considered
         first.
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         Alignment occurs within the spectral system and standard of rest
         given by attributes AlignSystem and AlignStdOfRest.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         Alignment occurs within the time system and time scale given by
         attributes AlignSystem and \htmlref{AlignTimeScale}{AlignTimeScale}.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astConvert()
      }{
         If the requested coordinate conversion is possible, the
         function returns a pointer to a FrameSet which describes the
         conversion. Otherwise, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is
         returned without error.

         If a FrameSet is returned, it will contain two Frames. Frame
         number 1 (its base Frame) will describe the source coordinate
         system, corresponding to the \texttt{"} from\texttt{"}  parameter. Frame number 2
         (its current Frame) will describe the destination coordinate
         system, corresponding to the \texttt{"} to\texttt{"}  parameter. The Mapping
         which inter-relates these two Frames will perform the
         required conversion between their respective coordinate
         systems.

         Note that a FrameSet may be used both as a Mapping and as a
         Frame.  If the result is used as a Mapping (e.g. with
         \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates
         from the source to the destination coordinate system (or
         vice versa if its inverse transformation is selected). If it
         is used as a Frame, its attributes will describe the
         destination coordinate system.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         cvt = astConvert( a, b, \texttt{"} \texttt{"}  );
      }{
         Attempts to convert between the coordinate systems represented
         by \texttt{"} a\texttt{"}  and \texttt{"} b\texttt{"}  (assumed to be Frames). If successful, a FrameSet
         is returned via the \texttt{"} cvt\texttt{"}  pointer which may be used to apply the
         conversion to sets of coordinates (e.g. using astTran2).
      }
      \sstexamplesubsection{
         cvt = astConvert( \htmlref{astSkyFrame}{astSkyFrame}(\texttt{"} \texttt{"} ), astSkyFrame(\texttt{"} \htmlref{Equinox}{Equinox}=2005\texttt{"} ), \texttt{"} \texttt{"}  );
      }{
         Creates a FrameSet which describes precession in the default
         FK5 celestial coordinate system between equinoxes J2000 (also
         the default) and J2005. The returned \texttt{"} cvt\texttt{"}  pointer may then
         be passed to astTran2 to apply this precession correction to
         any number of coordinate values given in radians.

         Note that the returned FrameSet also contains information
         about how to format coordinate values. This means that
         setting its \htmlref{Report}{Report} attribute to 1 is a simple way to obtain
         printed output (formatted in sexagesimal notation) to show
         the coordinate values before and after conversion.
      }
      \sstexamplesubsection{
         cvt = astConvert( a, b, \texttt{"} sky,detector,\texttt{"}  );
      }{
         Attempts to convert between the coordinate systems
         represented by the current Frames of \texttt{"} a\texttt{"}  and \texttt{"} b\texttt{"}
         (now assumed to be FrameSets), via the intermediate \texttt{"} SKY\texttt{"}
         coordinate system.  This, by default, is the Domain
         associated with a celestial coordinate system represented by
         a \htmlref{SkyFrame}{SkyFrame}.

         If this fails (for example, because either FrameSet lacks
         celestial coordinate information), then the user-defined
         \texttt{"} DETECTOR\texttt{"}  coordinate system is used instead. If this also
         fails, then all other possible ways of achieving conversion
         are considered before giving up.

         The returned pointer \texttt{"} cvt\texttt{"}  indicates whether conversion was
         possible and will have the value AST\_\_NULL if it was not. If
         conversion was possible, \texttt{"} cvt\texttt{"}  will point at a new FrameSet
         describing the conversion.

         The Base attributes of the two FrameSets
         will be set by astConvert to indicate which of their Frames was
         used for the intermediate coordinate system. This means that
         you can subsequently determine which coordinate system was
         used by enquiring the Domain attribute of either base Frame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Mapping represented by the returned FrameSet results in
         alignment taking place in the coordinate system specified by the
         AlignSystem attribute of the \texttt{"} to\texttt{"}  Frame. See the description of the
         AlignSystem attribute for further details.

         \sstitem
         When aligning (say) two images, which have been calibrated by
         attaching FrameSets to them, it is usually necessary to convert
         between the base Frames (representing \texttt{"} native\texttt{"}  pixel
         coordinates) of both FrameSets. This may be achieved by
         inverting the FrameSets (e.g. using \htmlref{astInvert}{astInvert}) so as to
         interchange their base and current Frames before using
         astConvert.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astConvex$<$X$>$
}{
   Create a new Polygon representing the convex hull of a 2D data grid
}{
   \sstdescription{
      This is a set of functions that create the shortest \htmlref{Polygon}{Polygon} that
      encloses all pixels with a specified value within a gridded
      2-dimensional data array (e.g. an image).

      A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate
      system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to
      \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the
      Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other
      attributes are left unset. The nature of the pixel coordinate system
      is determined by parameter
      \texttt{"} starpix\texttt{"} .

      You should use a function which matches the numerical type of the
      data you are processing by replacing $<$X$>$ in the generic function
      name
      astConvex$<$X$>$
      by an appropriate 1- or 2-character type code. For example, if you
      are procesing data with type
      \texttt{"} float\texttt{"} , you should use the function astConvexF
      (see the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
      other numerical types).
   }
   \sstsynopsis{
      AstPolygon $*$astConvex$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[],
                                 const int lbnd[2], const int ubnd[2], int starpix )
   }
   \sstparameters{
      \sstsubsection{
         value
      }{
         A data value that specifies the pixels to be included within the
         convex hull.
      }
      \sstsubsection{
         oper
      }{
         Indicates how the
         \texttt{"} value\texttt{"}
         parameter is used to select the required pixels. It can
         have any of the following values:
         \sstitemlist{

            \sstitem
            AST\_\_LT: include pixels with value less than \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_LE: include pixels with value less than or equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_EQ: include pixels with value equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_NE: include pixels with value not equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_GE: include pixels with value greater than or equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_GT: include pixels with value greater than \texttt{"} value\texttt{"} .
         }
      }
      \sstsubsection{
         array
      }{
         Pointer to a
         2-dimensional array containing the data to be processed.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astConvexF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the second dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of two integers
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of two integers
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre or upper corner, as selected by parameter
         \texttt{"} starpix\texttt{"} .
      }
      \sstsubsection{
         starpix
      }{
         A flag indicating the nature of the pixel coordinate system used
         to describe the vertex positions in the returned Polygon. If
         non-zero,
         the standard Starlink definition of pixel coordinate is used in
         which a pixel with integer index I spans a range of pixel coordinate
         from (I-1) to I (i.e. pixel corners have integral pixel coordinates).
         If zero,
         the definition of pixel coordinate used by other AST functions
         such as astResample, astMask,
         etc., is used. In this definition, a pixel with integer index I
         spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e.
         pixel centres have integral pixel coordinates).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astConvex$<$X$>$()
      }{
         A pointer to the required Polygon.
         NULL
         is returned without error if the array contains no pixels that
         satisfy the criterion specified by
         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         NULL
         will be returned if this function is invoked with the global
         error status set, or if it should fail for any reason.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate masking function, you should
      replace $<$X$>$ in the generic function name astConvex$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         L: long int

         \sstitem
         UL: unsigned long int

         \sstitem
         I: int

         \sstitem
         UI: unsigned int

         \sstitem
         S: short int

         \sstitem
         US: unsigned short int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astConvexD would be used to process \texttt{"} double\texttt{"}
      data, while astConvexS would be used to process \texttt{"} short int\texttt{"}
      data, etc.
   }
}
\sstroutine{
   astCopy
}{
   Copy an Object
}{
   \sstdescription{
      This function creates a copy of an \htmlref{Object}{Object} and returns a pointer
      to the resulting new Object. It makes a \texttt{"} deep\texttt{"}  copy, which
      contains no references to any other Object (i.e. if the original
      Object contains references to other Objects, then the actual
      data are copied, not simply the references). This means that
      modifications may safely be made to the copy without indirectly
      affecting any other Object.
   }
   \sstsynopsis{
      AstObject $*$astCopy( const AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be copied.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCopy()
      }{
         Pointer to the new Object.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astCurrentTime
}{
   Return the current system time
}{
   \sstdescription{
      This function
      returns the current system time, represented in the form specified
      by the supplied \htmlref{TimeFrame}{TimeFrame}. That is, the returned floating point
      value should be interpreted using the attribute values of the
      TimeFrame. This includes \htmlref{System}{System}, \htmlref{TimeOrigin}{TimeOrigin}, \htmlref{LTOffset}{LTOffset}, \htmlref{TimeScale}{TimeScale},
      and Unit.
   }
   \sstsynopsis{
      double astCurrentTime( AstTimeFrame $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the TimeFrame.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCurrentTime()
      }{
         A TimeFrame axis value representing the current system time.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Values of AST\_\_BAD will be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.

         \sstitem
         It is assumes that the system time (returned by the C time()
         function) follows the POSIX standard, representing a continuous
         monotonic increasing count of SI seconds since the epoch 00:00:00
         UTC 1 January 1970 AD (equivalent to TAI with a constant offset).
         Resolution is one second.

         \sstitem
         An error will be reported if the TimeFrame has a TimeScale value
         which cannot be converted to TAI (e.g. \texttt{"} angular\texttt{"}  systems such as
         UT1, GMST, LMST and LAST).

         \sstitem
         Any inaccuracy in the system clock will be reflected in the value
         returned by this function.
      }
   }
}
\sstroutine{
   astCurve
}{
   Draw a geodesic curve
}{
   \sstdescription{
      This function draws a geodesic curve between two points in the
      physical coordinate system of a \htmlref{Plot}{Plot}.  The curve drawn is the
      path of shortest distance joining the two points (as defined by
      the \htmlref{astDistance}{astDistance} function for the current \htmlref{Frame}{Frame} of the Plot).
      For example, if the current Frame is a basic Frame, then the
      curve joining the two points will be a straight line in physical
      coordinate space.  If the current Frame is more specialised and
      describes, for instance, a sky coordinate system, then the
      geodesic curve would be a great circle in physical coordinate
      space passing through the two sky positions given.

      Note that the geodesic curve is transformed into graphical
      coordinate space for plotting, so that a straight line in
      physical coordinates may result in a curved line being drawn if
      the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the
      Mapping between physical and graphical coordinates are
      catered for, as is any clipping established using \htmlref{astClip}{astClip}.

      If you need to draw many geodesic curves end-to-end, then the
      \htmlref{astPolyCurve}{astPolyCurve} function is equivalent to repeatedly using
      astCurve, but will usually be more efficient.

      If you need to draw curves which are not geodesics, see \htmlref{astGenCurve}{astGenCurve}
      or \htmlref{astGridLine}{astGridLine}.
   }
   \sstsynopsis{
      void astCurve( AstPlot $*$this, const double start[],
                                    const double finish[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         start
      }{
         An array, with one element for each axis of the Plot, giving
         the physical coordinates of the first point on the geodesic
         curve.
      }
      \sstsubsection{
         finish
      }{
         An array, with one element for each axis of the Plot, giving
         the physical coordinates of the second point on the geodesic
         curve.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No curve is drawn if either of the \texttt{"} start\texttt{"}  or \texttt{"} finish\texttt{"}  arrays
         contains any coordinates with the value AST\_\_BAD.

         \sstitem
         An error results if the base Frame of the Plot is not 2-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astDSBSpecFrame
}{
   Create a DSBSpecFrame
}{
   \sstdescription{
      This function creates a new \htmlref{DSBSpecFrame}{DSBSpecFrame} and optionally initialises its
      attributes.

      A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents
      positions in a spectrum obtained using a dual sideband instrument.
      Such an instrument produces a spectrum in which each point contains
      contributions from two distinctly different frequencies, one from
      the \texttt{"} lower side band\texttt{"}  (LSB) and one from the \texttt{"} upper side band\texttt{"}  (USB).
      Corresponding LSB and USB frequencies are connected by the fact
      that they are an equal distance on either side of a fixed central
      frequency known as the \texttt{"} Local Oscillator\texttt{"}  (LO) frequency.

      When quoting a position within such a spectrum, it is necessary to
      indicate whether the quoted position is the USB position or the
      corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this
      indication. Another option that the SideBand attribute provides is
      to represent a spectral position by its topocentric offset from the
      LO frequency.

      In practice, the LO frequency is specified by giving the distance
      from the LO frequency to some \texttt{"} central\texttt{"}  spectral position. Typically
      this central position is that of some interesting spectral feature.
      The distance from this central position to the LO frequency is known
      as the \texttt{"} intermediate frequency\texttt{"}  (\htmlref{IF}{IF}). The value supplied for IF can
      be a signed value in order to indicate whether the LO frequency is
      above or below the central position.
   }
   \sstsynopsis{
      AstDSBSpecFrame $*$astDSBSpecFrame( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new DSBSpecFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astDSBSpecFrame()
      }{
         A pointer to the new DSBSpecFrame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astDecompose
}{
   Decompose a Mapping into two component Mappings
}{
   \sstdescription{
      This function returns pointers to two Mappings which, when applied
      either in series or parallel, are equivalent to the supplied \htmlref{Mapping}{Mapping}.

      Since the \htmlref{Frame}{Frame} class inherits from the Mapping class, Frames can
      be considered as special types of Mappings and so this method can
      be used to decompose either CmpMaps or CmpFrames.
   }
   \sstsynopsis{
      void astDecompose( AstMapping $*$this, AstMapping $*$$*$map1,
                         AstMapping $*$$*$map2, int $*$series, int $*$invert1,
                         int $*$invert2  )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping.
      }
      \sstsubsection{
         map1
      }{
         Address of a location to receive a pointer to first component
         Mapping.
      }
      \sstsubsection{
         map2
      }{
         Address of a location to receive a pointer to second component
         Mapping.
      }
      \sstsubsection{
         series
      }{
         Address of a location to receive a value indicating if the
         component Mappings are applied in series or parallel. A non-zero
         value means that the supplied Mapping is equivalent to applying map1
         followed by map2 in series. A zero value means that the supplied
         Mapping is equivalent to applying map1 to the lower numbered axes
         and map2 to the higher numbered axes, in parallel.
      }
      \sstsubsection{
         invert1
      }{
         The value of the \htmlref{Invert}{Invert} attribute to be used with map1.
      }
      \sstsubsection{
         invert2
      }{
         The value of the Invert attribute to be used with map2.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         If the supplied Mapping is a CmpMap, then map1 and map2 will be
         returned holding pointers to the component Mappings used to
         create the CmpMap, either in series or parallel. Note, changing
         the Invert attribute of either of the component Mappings using
         the returned pointers will have no effect on the supplied CmpMap.
         This is because the CmpMap remembers and uses the original settings
         of the Invert attributes (that is, the values of the Invert
         attributes when the CmpMap was first created). These are the
         Invert values which are returned in invert1 and invert2.
      }
      \sstsubsection{
         \htmlref{TranMap}{TranMap}
      }{
         If the supplied Mapping is a TranMap, then map1 and map2 will be
         returned holding pointers to the forward and inverse Mappings
         represented by the TranMap (zero will be returned for
         series).
         Note, changing the Invert attribute of
         either of the component Mappings using the returned pointers will
         have no effect on the supplied TranMap. This is because the TranMap
         remembers and uses the original settings of the Invert attributes
         (that is, the values of the Invert attributes when the TranMap was
         first created). These are the
         Invert values which are returned in invert1 and invert2.
      }
      \sstsubsection{
         Mapping
      }{
         For any class of Mapping other than a CmpMap, map1 will be
         returned holding a clone of the supplied Mapping pointer, and map2
         will be returned holding a NULL pointer. Invert1 will be returned
         holding the current value of the Invert attribute for the supplied
         Mapping, and invert2 will be returned holding zero.
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         If the supplied Mapping is a CmpFrame, then map1 and map2 will be
         returned holding pointers to the component Frames used to
         create the CmpFrame. The component Frames are considered to be in
         applied in parallel.
      }
      \sstsubsection{
         Frame
      }{
         For any class of Frame other than a CmpFrame, map1 will be
         returned holding a clone of the supplied Frame pointer, and map2
         will be returned holding a NULL pointer.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned Invert values should be used in preference to the
         current values of the Invert attribute in map1 and map2. This is
         because the attributes may have changed value since the Mappings
         were combined.

         \sstitem
         Any changes made to the component Mappings using the returned
         pointers will be reflected in the supplied Mapping.
      }
   }
}
\sstroutine{
   astDelFits
}{
   Delete the current FITS card in a FitsChan
}{
   \sstdescription{
      This function deletes the current FITS card from a \htmlref{FitsChan}{FitsChan}. The
      current card may be selected using the \htmlref{Card}{Card} attribute (if its index
      is known) or by using \htmlref{astFindFits}{astFindFits} (if only the FITS keyword is
      known).

      After deletion, the following card becomes the current card.
   }
   \sstsynopsis{
      void astDelFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function returns without action if the FitsChan is
         initially positioned at the \texttt{"} end-of-file\texttt{"}  (i.e. if the Card
         attribute exceeds the number of cards in the FitsChan).

         \sstitem
         If there are no subsequent cards in the FitsChan, then the
         Card attribute is left pointing at the \texttt{"} end-of-file\texttt{"}  after
         deletion (i.e. is set to one more than the number of cards in
         the FitsChan).
      }
   }
}
\sstroutine{
   astDelete
}{
   Delete an Object
}{
   \sstdescription{
      This function deletes an \htmlref{Object}{Object}, freeing all resources
      associated with it and rendering any remaining pointers to the
      Object invalid.

      Note that deletion is unconditional, regardless of whether other
      pointers to the Object are still in use (possibly within other
      Objects). A safer approach is to defer deletion, until all
      references to an Object have expired, by using \htmlref{astBegin}{astBegin}/\htmlref{astEnd}{astEnd}
      (together with \htmlref{astClone}{astClone} and \htmlref{astAnnul}{astAnnul} if necessary).
   }
   \sstsynopsis{
      AstObject $*$astDelete( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be deleted.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astDelete()
      }{
         A null Object pointer (AST\_\_NULL) is always returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to execute even if the AST error status
         is set
         on entry, although no further error report will be
         made if it subsequently fails under these circumstances.
      }
   }
}
\sstroutine{
   astDistance
}{
   Calculate the distance between two points in a Frame
}{
   \sstdescription{
      This function finds the distance between two points whose \htmlref{Frame}{Frame}
      coordinates are given. The distance calculated is that along
      the geodesic curve that joins the two points.

      For example, in a basic Frame, the distance calculated will be
      the Cartesian distance along the straight line joining the two
      points. For a more specialised Frame describing a sky coordinate
      system, however, it would be the distance along the great circle
      passing through two sky positions.
   }
   \sstsynopsis{
      double astDistance( AstFrame $*$this,
                          const double point1[], const double point2[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         point1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
      }
      \sstsubsection{
         point2
      }{
         An array of double, with one element for each Frame axis
         containing the coordinates of the second point.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astDistance
      }{
         The distance between the two points.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
         any of the input coordinates has this value.

         \sstitem
         A \texttt{"} bad\texttt{"}  value will also be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astDownsize
}{
   Reduce the number of vertices in a Polygon
}{
   \sstdescription{
      This function returns a pointer to a new \htmlref{Polygon}{Polygon} that contains a
      subset of the vertices in the supplied Polygon. The subset is
      chosen so that the returned Polygon is a good approximation to
      the supplied Polygon, within the limits specified by the supplied
      parameter values. That is, the density of points in the returned
      Polygon is greater at points where the curvature of the boundary of
      the supplied Polygon is greater.
   }
   \sstsynopsis{
      AstPolygon $*$astDownsize( AstPolygon $*$this, double maxerr, int maxvert )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Polygon.
      }
      \sstsubsection{
         maxerr
      }{
         The maximum allowed discrepancy between the supplied and
         returned Polygons, expressed as a geodesic distance within the
         Polygon\texttt{'} s coordinate frame. If this is zero or less, the
         returned Polygon will have the number of vertices specified by
         maxvert.
      }
      \sstsubsection{
         maxvert
      }{
         The maximum allowed number of vertices in the returned Polygon.
         If this is less than 3, the number of vertices in the returned
         Polygon will be the minimum needed to achieve the maximum
         discrepancy specified by
         maxerr.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astDownsize()
      }{
         Pointer to the new Polygon.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astEBuf
}{
   End the current graphical buffering context
}{
   \sstdescription{
      This function
      ends the current graphics buffering context. It should match a
      corresponding call to the
      \htmlref{astBBuf}{astBBuf} function.
   }
   \sstsynopsis{
      void astEBuf( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Plot}{Plot}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The nature of the buffering is determined by the underlying
         graphics system (as defined by the current grf module). Each call
         to this function
         simply invokes the astGEBuf function in the grf module.
      }
   }
}
\sstroutine{
   astEllipse
}{
   Create a Ellipse
}{
   \sstdescription{
      This function creates a new \htmlref{Ellipse}{Ellipse} and optionally initialises its
      attributes.

      A Ellipse is a \htmlref{Region}{Region} which represents a elliptical area within the
      supplied 2-dimensional \htmlref{Frame}{Frame}.
   }
   \sstsynopsis{
      AstEllipse $*$astEllipse( AstFrame $*$frame, int form, const double centre[2],
                              const double point1[2], const double point2[2],
                              AstRegion $*$unc, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. It must
         have exactly 2 axes. A deep copy is taken of the supplied Frame.
         This means that any subsequent changes made to the Frame using the
         supplied pointer will have no effect the Region.
      }
      \sstsubsection{
         form
      }{
         Indicates how the ellipse is described by the remaining parameters.
         A value of zero indicates that the ellipse is specified by a
         centre position and two positions on the circumference. A value of
         one indicates that the ellipse is specified by its centre position,
         the half-lengths of its two axes, and the orientation of its first
         axis.
      }
      \sstsubsection{
         centre
      }{
         An array of 2 doubles,
         containing the coordinates at the centre of
         the ellipse.
      }
      \sstsubsection{
         point1
      }{
         An array of 2 doubles. If \texttt{"} form\texttt{"}
         is zero, this array should contain the coordinates of one of the four
         points where an axis of the ellipse crosses the circumference of the
         ellipse.
         If \texttt{"} form\texttt{"}
         is one, it should contain the lengths of semi-major and
         semi-minor axes of the ellipse, given as geodesic distances
         within the Frame.
      }
      \sstsubsection{
         point2
      }{
         An array of 2 doubles. If \texttt{"} form\texttt{"}
         is zero, this array should containing the coordinates at some other
         point on the circumference of the ellipse, distinct from
         \texttt{"} point1\texttt{"} . If \texttt{"} form\texttt{"}
         is one, the first element of this array should hold the angle
         between the second axis of the Frame and the first ellipse axis
         (i.e. the ellipse axis which is specified first in the
         \texttt{"} point1\texttt{"}
         array), and the second element will be ignored. The angle should be
         given in radians, measured positive in the same sense as rotation
         from the positive direction of the second Frame axis to the positive
         direction of the first Frame axis.
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with the boundary of the Ellipse being created.
         The uncertainty in any point on the boundary of the Ellipse is found by
         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
         the boundary point being considered. The area covered by the
         shifted uncertainty Region then represents the uncertainty in the
         boundary position. The uncertainty is assumed to be the same for
         all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, Ellipse, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Ellipse. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the Ellipse being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Ellipse. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astEllipse()
      }{
         A pointer to the new Ellipse.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astEllipsePars
}{
   Returns the geometric parameters of an Ellipse
}{
   \sstdescription{
      This function
      returns the geometric parameters describing the supplied ellipse.
   }
   \sstsynopsis{
      void astEllipsePars( AstEllipse $*$this, double centre[2], double $*$a,
                           double $*$b, double $*$angle, double p1[2], double p2[2] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Region}{Region}.
      }
      \sstsubsection{
         centre
      }{
         The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays.
      }
      \sstsubsection{
         a
      }{
         Returned holding the half-length of the first axis of the
         ellipse.
      }
      \sstsubsection{
         b
      }{
         Returned holding the half-length of the second axis of the
         ellipse.
      }
      \sstsubsection{
         angle
      }{
         If the coordinate system in which the Ellipse is defined has
         axes (X,Y), then
         \texttt{"} $*$angle\texttt{"}
         is returned holding the angle from the positive direction of
         the Y axis to the first axis of the ellipse, in radians.
         Positive rotation is in the same sense as rotation from the
         positive direction of Y to the positive direction of X.
      }
      \sstsubsection{
         p1
      }{
         An array in which to return the coordinates at one of the two ends
         of the first axis  of the ellipse.
         A NULL pointer can be supplied if these coordinates are not needed.
      }
      \sstsubsection{
         p2
      }{
         An array in which to return the coordinates at one of the two ends
         of the second axis  of the ellipse.
         A NULL pointer can be supplied if these coordinates are not needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the coordinate system represented by the Ellipse has been
         changed since it was first created, the returned parameters refer
         to the new (changed) coordinate system, rather than the original
         coordinate system. Note however that if the transformation from
         original to new coordinate system is non-linear, the shape
         represented by the supplied Ellipse object may not be an accurate
         ellipse.

         \sstitem
         Values of AST\_\_BAD are returned for the parameters without error
         if the ellipse is degenerate or undefined.
      }
   }
}
\sstroutine{
   astEmptyFits
}{
   Delete all cards in a FitsChan
}{
   \sstdescription{
      This function
      deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}.
   }
   \sstsynopsis{
      void astEmptyFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This method simply deletes the cards currently in the FitsChan.
         Unlike \htmlref{astWriteFits}{astWriteFits},
         they are not first written out to the sink function or sink file.

         \sstitem
         Any Tables or warnings stored in the FitsChan are also deleted.

         \sstitem
         This method attempt to execute even if an error has occurred
         previously.
      }
   }
}
\sstroutine{
   astEnd
}{
   End an AST context
}{
   \sstdescription{
      This macro invokes a function to end an AST context which was
      begun with a matching invocation of \htmlref{astBegin}{astBegin}. Any \htmlref{Object}{Object}
      pointers created within this context will be annulled (just as
      if \htmlref{astAnnul}{astAnnul} had been invoked) and will cease to be valid
      afterwards, unless they have previously been exported using
      \htmlref{astExport}{astExport} or rendered exempt using \htmlref{astExempt}{astExempt}.
      If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
      fall to zero (which happens when the last pointer to it is
      annulled), then the Object will be deleted.
   }
   \sstsynopsis{
      void astEnd
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This macro applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         astEnd attempts to execute even if the AST error status is set.

         \sstitem
         Contexts delimited by astBegin and astEnd may be nested to any
         depth.
      }
   }
}
\sstroutine{
   astEscapes
}{
   Control whether graphical escape sequences are included in strings
}{
   \sstdescription{
      The \htmlref{Plot}{Plot} class defines a set of escape sequences which can be
      included within a text string in order to control the appearance of
      sub-strings within the text. See the \htmlref{Escape}{Escape} attribute for a
      description of these escape sequences. It is usually inappropriate
      for AST to return strings containing such escape sequences when
      called by application code. For instance, an application which
      displays the value of the \htmlref{Title}{Title} attribute of a \htmlref{Frame}{Frame} usually does
      not want the displayed string to include potentially long escape
      sequences which a human read would have difficuly interpreting.
      Therefore the default behaviour is for AST to strip out such escape
      sequences when called by application code. This default behaviour
      can be changed using this function.
   }
   \sstsynopsis{
      int astEscapes( int new\_value )
   }
   \sstparameters{
      \sstsubsection{
         new\_value
      }{
         A flag which indicates if escapes sequences should be included
         in returned strings. If zero is supplied, escape sequences will
         be stripped out of all strings returned by any AST function. If
         a positive value is supplied, then any escape sequences will be
         retained in the value returned to the caller. If a negative
         value is supplied, the current value of the flag will be left
         unchanged.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Object}{Object}
      }{
         This macro applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astEscapes
      }{
         The value of the flag on entry to this function.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function also controls whether the
         \htmlref{astStripEscapes}{astStripEscapes}
         function removes escape sequences from the supplied string, or
         returns the supplied string without change.

         \sstitem
         This function attempts to execute even if an error has already
         occurred.
      }
   }
}
\sstroutine{
   astExempt
}{
   Exempt an Object pointer from AST context handling
}{
   \sstdescription{
      This function exempts an \htmlref{Object}{Object} pointer from AST context
      handling, as implemented by \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}. This means that
      the pointer will not be affected when astEnd is invoked and will
      remain active until the end of the program, or until explicitly
      annulled using \htmlref{astAnnul}{astAnnul}.

      If possible, you should avoid using this function when writing
      applications. It is provided mainly for developers of other
      libraries, who may wish to retain references to AST Objects in
      internal data structures, and who therefore need to avoid the
      effects of astBegin and astEnd.
   }
   \sstsynopsis{
      void astExempt( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Object pointer to be exempted from context handling.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
}
\sstroutine{
   astExport
}{
   Export an Object pointer to an outer context
}{
   \sstdescription{
      This function exports an \htmlref{Object}{Object} pointer from the current AST context
      into the context that encloses the current one. This means that
      the pointer will no longer be annulled when the current context
      is ended (with \htmlref{astEnd}{astEnd}), but only when the next outer context (if
      any) ends.
   }
   \sstsynopsis{
      void astExport( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Object pointer to be exported.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         It is only sensible to apply this function to pointers that
         have been created within (or exported to) the current context
         and have not been rendered exempt using \htmlref{astExempt}{astExempt}.
         Applying it to an unsuitable Object pointer has no effect.
      }
   }
}
\sstroutine{
   astFindFits
}{
   Find a FITS card in a FitsChan by keyword
}{
   \sstdescription{
      This function searches for a card in a \htmlref{FitsChan}{FitsChan} by keyword. The
      search commences at the current card (identified by the \htmlref{Card}{Card}
      attribute) and ends when a card is found whose FITS keyword
      matches the template supplied, or when the last card in the
      FitsChan has been searched.

      If the search is successful (i.e. a card is found which matches
      the template), the contents of the card are (optionally)
      returned and the Card attribute is adjusted to identify the card
      found or, if required, the one following it. If the search is
      not successful, the function returns zero and the Card attribute
      is set to the \texttt{"} end-of-file\texttt{"} .
   }
   \sstsynopsis{
      int astFindFits( AstFitsChan $*$this, const char $*$name, char card[ 81 ],
                       int inc )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated character string containing a
         template for the keyword to be found. In the simplest case,
         this should simply be the keyword name (the search is case
         insensitive and trailing spaces are ignored). However, this
         template may also contain \texttt{"} field specifiers\texttt{"}  which are
         capable of matching a range of characters (see the \texttt{"} Keyword
         Templates\texttt{"}  section for details). In this case, the first card
         with a keyword which matches the template will be found. To
         find the next FITS card regardless of its keyword, you should
         use the template \texttt{"} \%f\texttt{"} .
      }
      \sstsubsection{
         card
      }{
         An array of at least 81 characters (to allow room for a
         terminating null)
         in which the FITS card which is found will be returned.  If
         the search is not successful (or a NULL pointer is given), a
         card will not be returned.
      }
      \sstsubsection{
         inc
      }{
         If this value is zero (and the search is successful), the
         FitsChan\texttt{'} s Card attribute will be set to the index of the card
         that was found. If it is non-zero, however, the Card
         attribute will be incremented to identify the card which
         follows the one found.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFindFits()
      }{
         One if the search was successful, otherwise zero.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         result = astFindFits( fitschan, \texttt{"} \%f\texttt{"} , card, 1 );
      }{
         Returns the current card in a FitsChan and advances the Card
         attribute to identify the card that follows (the \texttt{"} \%f\texttt{"}
         template matches any keyword).
      }
      \sstexamplesubsection{
         result = astFindFits( fitschan, \texttt{"} BITPIX\texttt{"} , card, 1 );
      }{
         Searches a FitsChan for a FITS card with the \texttt{"} BITPIX\texttt{"}  keyword
         and returns that card. The Card attribute is then incremented
         to identify the card that follows it.
      }
      \sstexamplesubsection{
         result = astFindFits( fitschan, \texttt{"} COMMENT\texttt{"} , NULL, 0 );
      }{
         Sets the Card attribute of a FitsChan to identify the next
         COMMENT card (if any). The card itself is not returned.
      }
      \sstexamplesubsection{
         result = astFindFits( fitschan, \texttt{"} CRVAL\%1d\texttt{"} , card, 1 );
      }{
         Searches a FitsChan for the next card with a keyword of the
         form \texttt{"} CRVALi\texttt{"}  (for example, any of the keywords \texttt{"} CRVAL1\texttt{"} ,
         \texttt{"} CRVAL2\texttt{"}  or \texttt{"} CRVAL3\texttt{"}  would be matched). The card found (if
         any) is returned, and the Card attribute is then incremented
         to identify the following card (ready to search for another
         keyword with the same form, perhaps).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The search always starts with the current card, as identified
         by the Card attribute. To ensure you search the entire contents
         of a FitsChan, you should first clear the Card attribute (using
         \htmlref{astClear}{astClear}). This effectively \texttt{"} rewinds\texttt{"}  the FitsChan.

         \sstitem
         If a search is unsuccessful, the Card attribute is set to the
         \texttt{"} end-of-file\texttt{"}  (i.e. to one more than the number of cards in the
         FitsChan). No error occurs.

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.
      }
   }
   \sstdiytopic{
      Keyword Templates
   }{
      The templates used to match FITS keywords are normally composed
      of literal characters, which must match the keyword exactly
      (apart from case). However, a template may also contain \texttt{"} field
      specifiers\texttt{"}  which can match a range of possible characters. This
      allows you to search for keywords that contain (for example)
      numbers, where the digits comprising the number are not known in
      advance.

      A field specifier starts with a \texttt{"} \%\texttt{"}  character. This is followed
      by an optional single digit (0 to 9) specifying a field
      width. Finally, there is a single character which specifies the

      type of character to be matched, as follows:

      \sstitemlist{

         \sstitem
         \texttt{"} c\texttt{"} : matches all upper case letters,

         \sstitem
         \texttt{"} d\texttt{"} : matches all decimal digits,

         \sstitem
         \texttt{"} f\texttt{"} : matches all characters which are permitted within a FITS
         keyword (upper case letters, digits, underscores and hyphens).

      }
      If the field width is omitted, the field specifier matches one
      or more characters. If the field width is zero, it matches zero
      or more characters. Otherwise, it matches exactly the number of

      characters specified. In addition to this:

      \sstitemlist{

         \sstitem
         The template \texttt{"} \%f\texttt{"}  will match a blank FITS keyword consisting
         of 8 spaces (as well as matching all other keywords).

         \sstitem
         A template consisting of 8 spaces will match a blank keyword
         (only).

      }
      For example:

      \sstitemlist{

         \sstitem
         The template \texttt{"} BitPix\texttt{"}  will match the keyword \texttt{"} BITPIX\texttt{"}  only.

         \sstitem
         The template \texttt{"} crpix\%1d\texttt{"}  will match keywords consisting of
         \texttt{"} CRPIX\texttt{"}  followed by one decimal digit.

         \sstitem
         The template \texttt{"} P\%c\texttt{"}  will match any keyword starting with \texttt{"} P\texttt{"}
         and followed by one or more letters.

         \sstitem
         The template \texttt{"} E\%0f\texttt{"}  will match any keyword beginning with \texttt{"} E\texttt{"} .

         \sstitem
         The template \texttt{"} \%f\texttt{"}  will match any keyword at all (including a
         blank one).
      }
   }
}
\sstroutine{
   astFindFrame
}{
   Find a coordinate system with specified characteristics
}{
   \sstdescription{
      This function uses a \texttt{"} template\texttt{"}  \htmlref{Frame}{Frame} to search another Frame
      (or \htmlref{FrameSet}{FrameSet}) to identify a coordinate system which has a
      specified set of characteristics. If a suitable coordinate
      system can be found, the function returns a pointer to a
      FrameSet which describes the required coordinate system and how
      to convert coordinates to and from it.

      This function is provided to help answer general questions about
      coordinate systems, such as typically arise when coordinate
      information is imported into a program as part of an initially
      unknown dataset. For example:
      \sstitemlist{

         \sstitem
         Is there a wavelength scale?

         \sstitem
         Is there a 2-dimensional coordinate system?

         \sstitem
         Is there a celestial coordinate system?

         \sstitem
         Can I plot the data in ecliptic coordinates?

      }
      You can also use this function as a means of reconciling a
      user\texttt{'} s preference for a particular coordinate system (for
      example, what type of axes to draw) with what is actually
      possible given the coordinate information available.

      To perform a search, you supply a \texttt{"} target\texttt{"}  Frame (or FrameSet)
      which represents the set of coordinate systems to be searched.
      If a basic Frame is given as the target, this set of coordinate
      systems consists of the one described by this Frame, plus all
      other \texttt{"} virtual\texttt{"}  coordinate systems which can potentially be
      reached from it by applying built-in conversions (for example,
      any of the celestial coordinate conversions known to the AST
      library would constitute a \texttt{"} built-in\texttt{"}  conversion). If a FrameSet
      is given as the target, the set of coordinate systems to be
      searched consists of the union of those represented by all the
      individual Frames within it.

      To select from this large set of possible coordinate systems,
      you supply a \texttt{"} template\texttt{"}  Frame which is an instance of the type
      of Frame you are looking for. Effectively, you then ask the
      function to \texttt{"} find a coordinate system that looks like this\texttt{"} .

      You can make your request more or less specific by setting
      attribute values for the template Frame. If a particular
      attribute is set in the template, then the function will only
      find coordinate systems which have exactly the same value for
      that attribute.  If you leave a template attribute un-set,
      however, then the function has discretion about the value the
      attribute should have in any coordinate system it finds. The
      attribute will then take its value from one of the actual
      (rather than virtual) coordinate systems in the target. If the
      target is a FrameSet, its \htmlref{Current}{Current} attribute will be modified to
      indicate which of its Frames was used for this purpose.

      The result of this process is a coordinate system represented by
      a hybrid Frame which acquires some attributes from the template
      (but only if they were set) and the remainder from the
      target. This represents the \texttt{"} best compromise\texttt{"}  between what you
      asked for and what was available. A \htmlref{Mapping}{Mapping} is then generated
      which converts from the target coordinate system to this hybrid
      one, and the returned FrameSet encapsulates all of this
      information.
   }
   \sstsynopsis{
      AstFrameSet $*$astFindFrame( AstFrame $*$target, AstFrame $*$template,
                                 const char $*$domainlist )
   }
   \sstparameters{
      \sstsubsection{
         target
      }{
         Pointer to the target Frame (or FrameSet).

         Note that if a FrameSet is supplied (and a suitable
         coordinate system is found), then its Current attribute will
         be modified to indicate which Frame was used to obtain
         attribute values which were not specified by the template.
         This Frame will, in some sense, represent the \texttt{"} closest\texttt{"}
         non-virtual coordinate system to the one you requested.
      }
      \sstsubsection{
         template
      }{
         Pointer to the template Frame, which should be an instance of
         the type of Frame you wish to find. If you wanted to find a
         Frame describing a celestial coordinate system, for example,
         then you might use a \htmlref{SkyFrame}{SkyFrame} here. See the \texttt{"} Examples\texttt{"}
         section for more ideas.
      }
      \sstsubsection{
         domainlist
      }{
         Pointer to a null-terminated character string containing a
         comma-separated list of Frame domains. This may be used to
         establish a priority order for the different types of
         coordinate system that might be found.

         The function will first try to find a suitable coordinate
         system whose \htmlref{Domain}{Domain} attribute equals the first domain in this
         list. If this fails, the second domain in the list will be
         used, and so on, until a result is obtained. A blank domain
         (e.g. two consecutive commas) indicates that any coordinate
         system is acceptable (subject to the template) regardless of
         its domain.

         This list is case-insensitive and all white space is ignored.
         If you do not wish to restrict the domain in this way,
         you should supply an empty string.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         This function applies to all Frames.
      }
      \sstsubsection{
         FrameSet
      }{
         If the target is a FrameSet, the possibility exists that
         several of the Frames within it might be matched by the
         template.  Unless the choice is sufficiently restricted by
         the \texttt{"} domainlist\texttt{"}  string, the sequence in which Frames are
         searched can then become important. In this case, the search
         proceeds as follows:
         \sstitemlist{

            \sstitem
            Each field in the \texttt{"} domainlist\texttt{"}  string is considered in turn.

            \sstitem
            An attempt is made to match the template to each of the
            target\texttt{'} s Frames in the order: (1) the current Frame, (2) the
            base Frame, (3) each remaining Frame in the order of being
            added to the target FrameSet.

            \sstitem
            Generally, the first match found is used. However, the
            Mapping between the target coordinate system and the
            resulting Frame is also examined. Preference is given to
            cases where both the forward and inverse transformations are
            defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}
            attributes). If only one transformation is defined, the
            forward one is preferred.

            \sstitem
            If a match is found and the domain of the resulting Frame also
            matches the current \texttt{"} domainlist\texttt{"}  field, it is
            accepted. Otherwise, the next \texttt{"} domainlist\texttt{"}  field is considered
            and the process repeated.

         }
         If a suitable coordinate system is found, the Current
         attribute of the target FrameSet will be modified on exit to
         identify the Frame whose match with the target was eventually
         accepted.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFindFrame()
      }{
         If the search is successful, the function returns a pointer
         to a FrameSet which contains the Frame found and a
         description of how to convert to (and from) the coordinate
         system it represents. Otherwise, a null \htmlref{Object}{Object} pointer
         (AST\_\_NULL) is returned without error.

         If a FrameSet is returned, it will contain two Frames. Frame
         number 1 (its base Frame) represents the target coordinate
         system and will be the same as the (base Frame of the)
         target. Frame number 2 (its current Frame) will be a Frame
         representing the coordinate system which the function
         found. The Mapping which inter-relates these two Frames will
         describe how to convert between their respective coordinate
         systems.

         Note that a FrameSet may be used both as a Mapping and as a
         Frame. If the result is used as a Mapping (e.g. with
         \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates
         from the target coordinate system into the new coordinate
         system that was found (and vice versa if its inverse
         transformation is selected). If it is used as a Frame, its
         attributes will describe the new coordinate system.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         result = astFindFrame( target, \htmlref{astFrame}{astFrame}( 3, \texttt{"} \texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         Searches for a 3-dimensional coordinate system in the target
         Frame (or FrameSet). No attributes have been set in the
         template Frame (created by astFrame), so no restriction has
         been placed on the required coordinate system, other than
         that it should have 3 dimensions. The first suitable Frame
         found will be returned as part of the \texttt{"} result\texttt{"}  FrameSet.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, \htmlref{astSkyFrame}{astSkyFrame}( \texttt{"} \texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         Searches for a celestial coordinate system in the target
         Frame (or FrameSet). The type of celestial coordinate system
         is unspecified, so astFindFrame will return the first one
         found as part of the \texttt{"} result\texttt{"}  FrameSet. If the target is
         a FrameSet, then its Current attribute will be updated to
         identify the Frame that was used.

         If no celestial coordinate system can be found, a value of
         AST\_\_NULL will be returned without error.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{MaxAxes}{MaxAxes}=100\texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         This is like the last example, except that in the event of the
         target being a \htmlref{CmpFrame}{CmpFrame}, the component Frames encapsulated by the
         CmpFrame will be searched for a SkyFrame. If found, the returned
         Mapping will included a \htmlref{PermMap}{PermMap} which selects the required axes
         from the target CmpFrame.

         This is acomplished by setting the MaxAxes attribute of the
         template SkyFrame to a large number (larger than or equal to the
         number of axes in the target CmpFrame). This allows the SkyFrame
         to be used as a match for Frames containing from 2 to 100 axes.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{System}{System}=FK5\texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         Searches for an equatorial (FK5) coordinate system in the
         target. The \htmlref{Equinox}{Equinox} value for the coordinate system has not
         been specified, so will be obtained from the target. If the
         target is a FrameSet, its Current attribute will be updated
         to indicate which SkyFrame was used to obtain this value.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astFrame( 2, \texttt{"} \texttt{"}  ), \texttt{"} sky,pixel,\texttt{"}  );
      }{
         Searches for a 2-dimensional coordinate system in the
         target. Initially, a search is made for a suitable coordinate
         system whose Domain attribute has the value \texttt{"} SKY\texttt{"} . If this
         search fails, a search is then made for one with the domain
         \texttt{"} PIXEL\texttt{"} . If this also fails, then any 2-dimensional
         coordinate system is returned as part of the \texttt{"} result\texttt{"}
         FrameSet.

         Only if no 2-dimensional coordinate systems can be reached by
         applying built-in conversions to any of the Frames in the
         target will a value of AST\_\_NULL be returned.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astFrame( 1, \texttt{"} Domain=WAVELENGTH\texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         Searches for any 1-dimensional coordinate system in the
         target which has the domain \texttt{"} WAVELENGTH\texttt{"} .
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astFrame( 1, \texttt{"} \texttt{"}  ), \texttt{"} wavelength\texttt{"}  );
      }{
         This example has exactly the same effect as that above. It
         illustrates the equivalence of the template\texttt{'} s Domain attribute
         and the fields in the \texttt{"} domainlist\texttt{"}  string.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astFrame( 1, \texttt{"} MaxAxes=3\texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         This is a more advanced example which will search for any
         coordinate system in the target having 1, 2 or 3
         dimensions. The Frame returned (as part of the \texttt{"} result\texttt{"}
         FrameSet) will always be 1-dimensional, but will be related
         to the coordinate system that was found by a suitable Mapping
         (e.g. a PermMap) which simply extracts the first axis.

         If we had wanted a Frame representing the actual (1, 2 or
         3-dimensional) coordinate system found, we could set the
         \htmlref{PreserveAxes}{PreserveAxes} attribute to a non-zero value in the template.
      }
      \sstexamplesubsection{
         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{Permute}{Permute}=0\texttt{"}  ), \texttt{"} \texttt{"}  );
      }{
         Searches for any celestial coordinate system in the target,
         but only finds one if its axes are in the conventional
         (longitude,latitude) order and have not been permuted
         (e.g. with \htmlref{astPermAxes}{astPermAxes}).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Mapping represented by the returned FrameSet results in
         alignment taking place in the coordinate system specified by the
         \htmlref{AlignSystem}{AlignSystem} attribute of the \texttt{"} template\texttt{"}  Frame. See the description
         of the AlignSystem attribute for further details.

         \sstitem
         Beware of setting the Domain attribute of the template and then
         using a \texttt{"} domainlist\texttt{"}  string which does not include the template\texttt{'} s domain
         (or a blank field). If you do so, no coordinate system will be
         found.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      More on Using Templates
   }{
      A Frame (describing a coordinate system) will be found by this
      function if (a) it is \texttt{"} matched\texttt{"}  by the template you supply, and
      (b) the value of its Domain attribute appears in the \texttt{"} domainlist\texttt{"}
      string (except that a blank field in this string permits any
      domain). A successful match by the template depends on a number
      of criteria, as outlined below:
      \sstitemlist{

         \sstitem
         In general, a template will only match another Frame which
         belongs to the same class as the template, or to a derived (more
         specialised) class. For example, a SkyFrame template will match
         any other SkyFrame, but will not match a basic
         Frame. Conversely, a basic Frame template will match any class
         of Frame.

         \sstitem
         The exception to this is that a Frame of any class can be used to
         match a CmpFrame, if that CmpFrame contains a Frame of the same
         class as the template. Note however, the MaxAxes and \htmlref{MinAxes}{MinAxes}
         attributes of the template must be set to suitable values to allow
         it to match the CmpFrame. That is, the MinAxes attribute must be
         less than or equal to the number of axes in the target, and the MaxAxes
         attribute must be greater than or equal to the number of axes in
         the target.

         \sstitem
         If using a CmpFrame as a template frame, the MinAxes and MaxAxes
         for the template are determined by the MinAxes and MaxAxes values of
         the component Frames within the template. So if you want a template
         CmpFrame to be able to match Frames with different numbers of axes,
         then you must set the MaxAxes and/or MinAxes attributes in the component
         template Frames, before combining them together into the template
         CmpFrame.

         \sstitem
         If a template has a value set for any of its main attributes, then
         it will only match Frames which have an identical value for that
         attribute (or which can be transformed, using a built-in
         conversion, so that they have the required value for that
         attribute). If any attribute in the template is un-set, however,
         then Frames are matched regardless of the value they may have
         for that attribute. You may therefore make a template more or
         less specific by choosing the attributes for which you set
         values. This requirement does not apply to \texttt{'} descriptive\texttt{'}  attributes
         such as titles, labels, symbols, etc.

         \sstitem
         An important application of this principle involves the Domain
         attribute. Setting the Domain attribute of the template has the
         effect of restricting the search to a particular type of Frame
         (with the domain you specify).  Conversely, if the Domain
         attribute is not set in the template, then the domain of the
         Frame found is not relevant, so all Frames are searched.  Note
         that the
         \texttt{"} domainlist\texttt{"}  string provides an alternative way of restricting the
         search in the same manner, but is a more convenient interface if
         you wish to search automatically for another domain if the first
         search fails.

         \sstitem
         Normally, a template will only match a Frame which has the
         same number of axes as itself. However, for some classes of
         template, this default behaviour may be changed by means of the
         MinAxes, MaxAxes and \htmlref{MatchEnd}{MatchEnd} attributes. In addition, the
         behaviour of a template may be influenced by its Permute and
         PreserveAxes attributes, which control whether it matches Frames
         whose axes have been permuted, and whether this permutation is
         retained in the Frame which is returned (as opposed to returning
         the axes in the order specified in the template, which is the
         default behaviour). You should consult the descriptions of these
         attributes for details of this more advanced use of templates.
      }
   }
}
\sstroutine{
   astFitsChan
}{
   Create a FitsChan
}{
   \sstdescription{
      This function creates a new \htmlref{FitsChan}{FitsChan} and optionally initialises
      its attributes.

      A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O
      operations involving the use of FITS (Flexible Image Transport
      \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a
      description of that Object composed of FITS header cards, and
      reading from a FitsChan will create a new Object from its FITS
      header card description.

      While a FitsChan is active, it represents a buffer which may
      contain zero or more 80-character \texttt{"} header cards\texttt{"}  conforming to
      FITS conventions. Any sequence of FITS-conforming header cards
      may be stored, apart from the \texttt{"} END\texttt{"}  card whose existence is
      merely implied.  The cards may be accessed in any order by using
      the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"}
      card, to which subsequent operations apply. Searches
      based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new
      cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and
      existing ones may be deleted (\htmlref{astDelFits}{astDelFits}) or changed (astSetFits$<$X$>$).

      When you create a FitsChan, you have the option of specifying
      \texttt{"} source\texttt{"}  and \texttt{"} sink\texttt{"}  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 \htmlref{SourceFile}{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 \htmlref{SinkFile}{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 \htmlref{astRead}{astRead}).

      Coordinate system information may be described using FITS header
      cards using several different conventions, termed
      \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a
      FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{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 headers).

      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 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
      \htmlref{astRetainFits}{astRetainFits} function).

      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.
   }
   \sstsynopsis{
      AstFitsChan $*$astFitsChan( const char $*$($*$ source)( void ),
                                void ($*$ sink)( const char $*$ ),
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         source
      }{
         Pointer to a source function which takes no arguments and
         returns a pointer to a null-terminated string. This function
         will be used by the FitsChan to obtain input FITS header
         cards. On each invocation, it should read the next input card
         from some external source (such as a FITS file), and return a
         pointer to the (null-terminated) contents of the card. It
         should return a NULL pointer when there are no more cards to
         be read.

         If \texttt{"} source\texttt{"}  is NULL, the FitsChan will remain empty until
         cards are explicitly stored in it (e.g. using astPutCards,
         astPutFits or via the SourceFile attribute).
      }
      \sstsubsection{
         sink
      }{
         Pointer to a sink function that takes a pointer to a
         null-terminated string as an argument and returns void.  If
         no value has been set for the SinkFile attribute, this
         function will be used by the FitsChan to deliver any FITS
         header cards it contains when it is finally deleted. On
         each invocation, it should deliver the contents of the character
         string passed to it as a FITS header card to some external
         data store (such as a FITS file).

         If \texttt{"} sink\texttt{"}  is NULL,
         and no value has been set for the SinkFile attribute, the
         contents of the FitsChan will be lost when it is deleted.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new FitsChan. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).

         Note, the FITSCHAN\_OPTIONS environment variable may be used
         to specify default options for all newly created FitsChans.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFitsChan()
      }{
         A pointer to the new FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No FITS \texttt{"} END\texttt{"}  card will be written via the sink function. You
         should add this card yourself after the FitsChan has been
         deleted.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astFitsTable
}{
   Create a FitsTable
}{
   \sstdescription{
      This function creates a new \htmlref{FitsTable}{FitsTable} and optionally initialises
      its attributes.

      The FitsTable class is a representation of a FITS binary table. It
      inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the
      binary data of the main table, and a \htmlref{FitsChan}{FitsChan} is used to hold the FITS
      header. Note, there is no provision for binary data following the main
      table (such data is referred to as a \texttt{"} heap\texttt{"}  in the FITS standard).

      Note - it is not recommended to use the FitsTable class to store
      very large tables.
   }
   \sstsynopsis{
      AstFitsTable $*$astFitsTable( AstFitsChan $*$header, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         header
      }{
         Pointer to an optional FitsChan containing headers to be stored
         in the FitsTable.
         NULL
         may be supplied if the new FitsTable is to be left empty. If
         supplied, and if the headers describe columns of a FITS binary
         table, then equivalent (empty) columns are added to the FitsTable.
         Each column has the same index in the FitsTable that it has in
         the supplied header.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new FitsTable. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFitsTable()
      }{
         A pointer to the new FitsTable.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list described above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astFluxFrame
}{
   Create a FluxFrame
}{
   \sstdescription{
      This function creates a new \htmlref{FluxFrame}{FluxFrame} and optionally initialises
      its attributes.

      A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various systems used to represent the signal level in an
      observation. The particular coordinate system to be used is specified
      by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by
      other attributes such as the units, etc (see the description of the
      System attribute for details).

      All flux values are assumed to be measured at the same frequency or
      wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is
      more appropriate for use with images rather than spectra.
   }
   \sstsynopsis{
      AstFluxFrame $*$astFluxFrame( double specval, AstSpecFrame $*$specfrm,
                                  const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         specval
      }{
         The spectral value to which the flux values refer, given in the
         spectral coordinate system specified by
         \texttt{"} specfrm\texttt{"} . The value supplied for the \texttt{"} specval\texttt{"}
         parameter becomes the default value for the SpecVal attribute.
         A value of AST\_\_BAD may be supplied if the spectral position is
         unknown, but this may result in it not being possible for the
         \htmlref{astConvert}{astConvert}
         function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and
         some other FluxFrame.
      }
      \sstsubsection{
         specfrm
      }{
         A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system
         in which the
         \texttt{"} specval\texttt{"}
         parameter is given. A deep copy of this object is taken, so any
         subsequent changes to the SpecFrame using the supplied pointer will
         have no effect on the new FluxFrame.
         A NULL pointer can be supplied if AST\_\_BAD is supplied for \texttt{"} specval\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new FluxFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFluxFrame()
      }{
         A pointer to the new FluxFrame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When conversion between two FluxFrames is requested (as when
         supplying FluxFrames to astConvert),
         account will be taken of the nature of the flux coordinate systems
         they represent, together with any qualifying attribute values, including
         the \htmlref{AlignSystem}{AlignSystem} attribute. The results will therefore fully reflect the
         relationship between positions measured in the two systems. In addition,
         any difference in the Unit attributes of the two systems will also be
         taken into account.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astFormat
}{
   Format a coordinate value for a Frame axis
}{
   \sstdescription{
      This function returns a pointer to a string containing the
      formatted (character) version of a coordinate value for a \htmlref{Frame}{Frame}
      axis. The formatting applied is determined by the Frame\texttt{'} s
      attributes and, in particular, by any Format attribute string
      that has been set for the axis. A suitable default format (based
      on the Digits attribute value) will be applied if necessary.
   }
   \sstsynopsis{
      const char $*$astFormat( AstFrame $*$this, int axis, double value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         axis
      }{
         The number of the Frame axis for which formatting is to be
         performed (axis numbering starts at 1 for the first axis).
      }
      \sstsubsection{
         value
      }{
         The coordinate value to be formatted.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFormat()
      }{
         A pointer to a null-terminated string containing the formatted
         value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned pointer is guaranteed to remain valid and the
         string to which it points will not be over-written for a total
         of 50 successive invocations of this function. After this, the
         memory containing the string may be re-used, so a copy of the
         string should be made if it is needed for longer than this.

         \sstitem
         A formatted value may be converted back into a numerical (double)
         value using \htmlref{astUnformat}{astUnformat}.

         \sstitem
         A NULL pointer will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astFrame
}{
   Create a Frame
}{
   \sstdescription{
      This function creates a new \htmlref{Frame}{Frame} and optionally initialises its
      attributes.

      A Frame is used to represent a coordinate system. It does this
      in rather the same way that a frame around a graph describes the
      coordinate space in which data are plotted. Consequently, a
      Frame has a \htmlref{Title}{Title} (string) attribute, which describes the
      coordinate space, and contains axes which in turn hold
      information such as Label and Units strings which are used for
      labelling (e.g.) graphical output. In general, however, the
      number of axes is not restricted to two.

      Functions are available for converting Frame coordinate values
      into a form suitable for display, and also for calculating
      distances and offsets between positions within the Frame.

      Frames may also contain knowledge of how to transform to and
      from related coordinate systems.
   }
   \sstsynopsis{
      AstFrame $*$astFrame( int naxes, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         naxes
      }{
         The number of Frame axes (i.e. the number of dimensions of
         the coordinate space which the Frame describes).
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Frame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFrame()
      }{
         A pointer to the new Frame.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         frame = astFrame( 2, \texttt{"} Title=Energy Spectrum: \htmlref{Plot}{Plot} \%d\texttt{"} , n );
      }{
         Creates a new 2-dimensional Frame and initialises its Title
         attribute to the string \texttt{"} Energy Spectrum: Plot $<$n$>$\texttt{"} , where
         $<$n$>$ takes the value of the int variable \texttt{"} n\texttt{"} .
      }
      \sstexamplesubsection{
         frame = astFrame( 2, \texttt{"} Label(1)=Energy, Label(2)=Response\texttt{"}  );
      }{
         Creates a new 2-dimensional Frame and initialises its axis
         Label attributes to suitable string values.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astFrameSet
}{
   Create a FrameSet
}{
   \sstdescription{
      This function creates a new \htmlref{FrameSet}{FrameSet} and optionally initialises
      its attributes.

      A FrameSet consists of a set of one or more Frames (which
      describe coordinate systems), connected together by Mappings
      (which describe how the coordinate systems are inter-related). A
      FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair
      of these Frames (i.e. to convert between any of the coordinate
      systems which it describes).  The individual Frames are
      identified within the FrameSet by an integer index, with Frames
      being numbered consecutively from one as they are added to the
      FrameSet.

      Every FrameSet has a \texttt{"} base\texttt{"}  \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"}  Frame (which
      are allowed to be the same). Any of the Frames may be nominated
      to hold these positions, and the choice is determined by the
      values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold
      the indices of the relevant Frames.  By default, the first Frame
      added to a FrameSet is its base Frame, and the last one added is
      its current Frame.

      The base Frame describes the \texttt{"} native\texttt{"}  coordinate system of
      whatever the FrameSet is used to calibrate (e.g. the pixel
      coordinates of an image) and the current Frame describes the
      \texttt{"} apparent\texttt{"}  coordinate system in which it should be viewed
      (e.g. displayed, etc.). Any further Frames represent a library
      of alternative coordinate systems, which may be selected by
      making them current.

      When a FrameSet is used in a context that requires a Frame,
      (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current
      Frame is used. A FrameSet may therefore be used in place of its
      current Frame in most situations.

      When a FrameSet is used in a context that requires a Mapping,
      the Mapping used is the one between its base Frame and its
      current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"}
      coordinates into \texttt{"} apparent\texttt{"}  ones, and vice versa. Like any
      Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which
      has the effect of interchanging its base and current Frames and
      hence of reversing the Mapping between them.

      Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of
      Frame), either explicitly or as components within CmpFrames. In this
      case the Mapping between a pair of Frames within a FrameSet will
      include the effects of the clipping produced by any Regions included
      in the path between the Frames.
   }
   \sstsynopsis{
      AstFrameSet $*$astFrameSet( AstFrame $*$frame, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         Pointer to the first Frame to be inserted into the
         FrameSet. This initially becomes both the base and the
         current Frame. (Further Frames may be added using the
         \htmlref{astAddFrame}{astAddFrame} function.)
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new FrameSet. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFrameSet()
      }{
         A pointer to the new FrameSet.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If a pointer to an existing FrameSet is given for the \texttt{"} frame\texttt{"}
         parameter, then the new FrameSet will (as a special case) be
         initialised to contain the same Frames and Mappings, and to have
         the same attribute values, as the one supplied. This process is
         similar to making a copy of a FrameSet (see \htmlref{astCopy}{astCopy}), except
         that the Frames and Mappings contained in the original are not
         themselves copied, but are shared by both FrameSets.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astFromString
}{
   Re-create an Object from an in-memory serialisation
}{
   \sstdescription{
      This function returns a pointer to a new \htmlref{Object}{Object} created from the
      supplied text string, which should have been created by \htmlref{astToString}{astToString}.
   }
   \sstsynopsis{
      AstObject $*$astFromString( const char $*$string )
   }
   \sstparameters{
      \sstsubsection{
         string
      }{
         Pointer to a text string holding an Object serialisation created
         previously by astToString.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFromString()
      }{
         Pointer to a new Object created from the supplied serialisation,
         or NULL if the serialisation was invalid, or an error occurred.
      }
   }
}
\sstroutine{
   astGenCurve
}{
   Draw a generalized curve
}{
   \sstdescription{
      This function draws a general user-defined curve defined by the
      supplied \htmlref{Mapping}{Mapping}. Note that the curve is transformed into graphical
      coordinate space for plotting, so that a straight line in
      physical coordinates may result in a curved line being drawn if
      the Mapping involved is non-linear. Any discontinuities in the
      Mapping between physical and graphical coordinates are
      catered for, as is any clipping established using \htmlref{astClip}{astClip}.

      If you need to draw simple straight lines (geodesics), \htmlref{astCurve}{astCurve}
      or \htmlref{astPolyCurve}{astPolyCurve} will usually be easier to use and faster.
   }
   \sstsynopsis{
      void astGenCurve( AstPlot $*$this, astMapping $*$map )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Plot}{Plot}.
      }
      \sstsubsection{
         map
      }{
         Pointer to a Mapping. This Mapping should have 1 input
         coordinate representing offset along the required curve,
         normalized so that the start of the curve is at offset 0.0,
         and the end of the curve is at offset 1.0. Note, this offset
         does not need to be linearly related to distance along the curve.
         The number of output coordinates should equal the number of axes
         in the current \htmlref{Frame}{Frame} of the Plot. The Mapping should map a
         specified offset along the curve, into the corresponding
         coordinates in the current Frame of the Plot. The inverse
         transformation need not be defined.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error results if the base Frame of the Plot is not 2-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astGet$<$X$>$
}{
   Get an attribute value for an Object
}{
   \sstdescription{
      This is a family of functions which return a specified attribute
      value for an \htmlref{Object}{Object} using one of several different data
      types. The type is selected by replacing $<$X$>$ in the function name
      by C, D, F, I or L, to obtain a result in const char$*$ (i.e. string),
      double, float, int, or long format, respectively.

      If possible, the attribute value is converted to the type you
      request. If conversion is not possible, an error will result.
   }
   \sstsynopsis{
      $<$X$>$type astGet$<$X$>$( AstObject $*$this, const char $*$attrib )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         attrib
      }{
         Pointer to a null-terminated string containing the name of
         the attribute whose value is required.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         These functions apply to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGet$<$X$>$()
      }{
         The attribute value, in the data type corresponding to $<$X$>$ (or,
         in the case of astGetC, a pointer to a constant null-terminated
         character string containing this value).
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         printf( \texttt{"} \htmlref{RefCount}{RefCount} = \%d$\backslash$n\texttt{"} , astGetI( z, \texttt{"} RefCount\texttt{"}  ) );
      }{
         Prints the RefCount attribute value for Object \texttt{"} z\texttt{"}  as an int.
      }
      \sstexamplesubsection{
         title = astGetC( axis, \texttt{"} \htmlref{Title}{Title}\texttt{"}  );
      }{
         Obtains a pointer to a null-terminated character string containing
         the Title attribute of Object \texttt{"} axis\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         An appropriate \texttt{"} null\texttt{"}  value will be returned if this function
         is invoked with the AST error status set, or if it should
         fail for any reason. This null value is zero for numeric
         values and NULL for pointer values.

         \sstitem
         The pointer returned by astGetC is guaranteed to remain valid
         and the string to which it points will not be over-written for a
         total of 50 successive invocations of this function. After this,
         the memory containing the string may be re-used, so a copy of
         the string should be made if it is needed for longer than this.
      }
   }
}
\sstroutine{
   astGetActiveUnit
}{
   Determines how the Unit attribute will be used
}{
   \sstdescription{
      This function
      returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See
      the description of the \htmlref{astSetActiveUnit}{astSetActiveUnit} function
      for a description of the ActiveUnit flag.
   }
   \sstsynopsis{
      int astGetActiveUnit( AstFrame $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetActiveUnit
      }{
         The current value of the ActiveUnit flag.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A zero value will be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astGetColumnData
}{
   Retrieve all the data values stored in a column
}{
   \sstdescription{
      This function
      copies all data values from a named column into a supplied buffer
   }
   \sstsynopsis{
      void astGetColumnData( AstFitsTable $*$this, const char $*$column,
                             float fnull, double dnull, size\_t mxsize,
                             void $*$coldata, int $*$nelem )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{FitsTable}{FitsTable}.
      }
      \sstsubsection{
         column
      }{
         The character string holding the name of the column. Trailing
         spaces are ignored.
      }
      \sstsubsection{
         fnull
      }{
         The value to return in
         \texttt{"} coldata\texttt{"}
         for any cells for which no value has been stored in the
         FitsTable. Ignored if the column\texttt{'} s data type is not
         AST\_\_FLOATTYPE. Supplying
         AST\_\_NANF
         will cause a single precision IEEE NaN value to be used.
      }
      \sstsubsection{
         dnull
      }{
         The value to return in
         \texttt{"} coldata\texttt{"}
         for any cells for which no value has been stored in the
         FitsTable. Ignored if the column\texttt{'} s data type is not
         AST\_\_DOUBLETYPE. Supplying AST\_\_NAN will cause a double precision
         IEEE NaN value to be used.
      }
      \sstsubsection{
         mxsize
      }{
         The size of the
         \texttt{"} coldata\texttt{"}
         array, in bytes. The amount of memory needed to hold the data
         from a column may be determined using
         \htmlref{astColumnSize}{astColumnSize}.
         If the supplied array is too small to hold all the column data,
         trailing column values will be omitted from the returned array,
         but no error will be reported.
      }
      \sstsubsection{
         coldata
      }{
         A pointer to an
         area of memory in which to return the data
         values currently stored in the column. The values are stored in
         row order. If the column holds non-scalar values, the elements
         of each value are stored in \texttt{"} Fortran\texttt{"}  order. No data type
         conversion is performed - the data type of each returned value
         is the data type associated with the column when the column was
         added to the table. If the column holds strings, the returned
         strings will be null terminated. Any excess room at the end of
         the array will be left unchanged.
      }
      \sstsubsection{
         nelem
      }{
         The number of elements returned in the
         \texttt{"} coldata\texttt{"}
         array. This is the product of the number of rows returned and
         the number of elements in each column value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The \texttt{"} fnull\texttt{"}  and \texttt{"} dnull\texttt{"}  parameters
         specify the value to be returned for any empty cells within columns
         holding floating point values. For columns holding integer values,
         the value returned for empty cells is the value returned by the
         astColumNull function.
         For columns holding string values, the ASCII NULL character is returned
         for empty cells.
      }
   }
}
\sstroutine{
   astGetFits$<$X$>$
}{
   Get a named keyword value from a FitsChan
}{
   \sstdescription{
      This is a family of functions which gets a value for a named keyword,
      or the value of the current card, from a \htmlref{FitsChan}{FitsChan} using one of several
      different data types. The data type of the returned value is selected
      by replacing $<$X$>$ in the function name by one of the following strings
      representing the recognised FITS data types:

      \sstitemlist{

         \sstitem
         CF - Complex floating point values.

         \sstitem
         CI - Complex integer values.

         \sstitem
         F  - Floating point values.

         \sstitem
         I  - Integer values.

         \sstitem
         L  - Logical (i.e. boolean) values.

         \sstitem
         S  - String values.

         \sstitem
         CN - A \texttt{"} CONTINUE\texttt{"}  value, these are treated like string values, but
                are encoded without an equals sign.

      }
      The data type of the \texttt{"} value\texttt{"}
      parameter

      depends on $<$X$>$ as follows:

      \sstitemlist{

         \sstitem
         CF - \texttt{"} double $*$\texttt{"}  (a pointer to a 2 element array to hold the real and
                imaginary parts of the complex value).

         \sstitem
         CI - \texttt{"} int $*$\texttt{"}  (a pointer to a 2 element array to hold the real and
                imaginary parts of the complex value).

         \sstitem
         F  - \texttt{"} double $*$\texttt{"} .

         \sstitem
         I  - \texttt{"} int $*$\texttt{"} .

         \sstitem
         L  - \texttt{"} int $*$\texttt{"} .

         \sstitem
         S  - \texttt{"} char $*$$*$\texttt{"}  (a pointer to a static \texttt{"} char\texttt{"}  array is returned at the
                location given by the \texttt{"} value\texttt{"}  parameter, Note, the stored string
                may change on subsequent invocations of astGetFitsS so a
                permanent copy should be taken of the string if necessary).

         \sstitem
         CN - Like\texttt{"} S\texttt{"} .
      }
   }
   \sstsynopsis{
      int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated character string
         containing the FITS keyword name. This may be a complete FITS
         header card, in which case the keyword to use is extracted from
         it. No more than 80 characters are read from this string. If
         NULL
         is supplied, the value of the current card is returned.
      }
      \sstsubsection{
         value
      }{
         A pointer to a
         buffer to receive the keyword value. The data type depends on $<$X$>$
         as described above. The conents of the buffer on entry are left
         unchanged if the keyword is not found.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetFits$<$X$>$$<$X$>$()
      }{
         A value of zero
         is returned if the keyword was not found in the FitsChan (no error
         is reported). Otherwise, a value of
         one
         is returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If a name is supplied, the card following the current card is
         checked first. If this is not the required card, then the rest of the
         FitsChan is searched, starting with the first card added to the
         FitsChan. Therefore cards should be accessed in the order they are
         stored in the FitsChan (if possible) as this will minimise the time
         spent searching for cards.

         \sstitem
         If the requested card is found, it becomes the current card,
         otherwise the current card is left pointing at the \texttt{"} end-of-file\texttt{"} .

         \sstitem
         If the stored keyword value is not of the requested type, it is
         converted into the requested type.

         \sstitem
         If the keyword is found in the FitsChan, but has no associated
         value, an error is reported. If necessary, the
         \htmlref{astTestFits}{astTestFits}
         function can be used to determine if the keyword has a defined
         value in the FitsChan prior to calling this function.

         \sstitem
         An error will be reported if the keyword name does not conform
         to FITS requirements.

         \sstitem
         Zero

         \sstitem
         .FALSE.
         is returned as the function value if an error has already occurred,
         or if this function should fail for any reason.

         \sstitem
         The FITS standard says that string keyword values should be
         padded with trailing spaces if they are shorter than 8 characters.
         For this reason, trailing spaces are removed from the string
         returned by
         astGetFitsS
         if the original string (including any trailing spaces) contains 8
         or fewer characters. Trailing spaces are not removed from longer
         strings.
      }
   }
}
\sstroutine{
   astGetFrame
}{
   Obtain a pointer to a specified Frame in a FrameSet
}{
   \sstdescription{
      This function returns a pointer to a specified \htmlref{Frame}{Frame} in a
      \htmlref{FrameSet}{FrameSet}.
   }
   \sstsynopsis{
      AstFrame $*$astGetFrame( AstFrameSet $*$this, int iframe )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe
      }{
         The index of the required Frame within the FrameSet.  This
         value should lie in the range from 1 to the number of Frames
         in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetFrame()
      }{
         A pointer to the requested Frame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
         Frame respectively.

         \sstitem
         This function increments the \htmlref{RefCount}{RefCount} attribute of the
         selected Frame by one.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetGrfContext
}{
   Return the KeyMap that describes a Plot\texttt{'} s graphics context
}{
   \sstdescription{
      This function
      returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing
      functions registered using \htmlref{astGrfSet}{astGrfSet}.
      This KeyMap can be used by an application to pass information to
      the drawing functions
      about the context in which they are being called. The contents of
      the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself.
   }
   \sstsynopsis{
      AstKeyMap $*$astGetGrfContext( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetGrfContext()
      }{
         A pointer to the graphics context KeyMap. The returned pointer
         should be annulled when it is no longer needed.
      }
   }
}
\sstroutine{
   astGetMapping
}{
   Obtain a Mapping that converts between two Frames in a FrameSet
}{
   \sstdescription{
      This function returns a pointer to a \htmlref{Mapping}{Mapping} that will convert
      coordinates between the coordinate systems represented by two
      Frames in a \htmlref{FrameSet}{FrameSet}.
   }
   \sstsynopsis{
      AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe1
      }{
         The index of the first \htmlref{Frame}{Frame} in the FrameSet. This Frame describes
         the coordinate system for the \texttt{"} input\texttt{"}  end of the Mapping.
      }
      \sstsubsection{
         iframe2
      }{
         The index of the second Frame in the FrameSet. This Frame
         describes the coordinate system for the \texttt{"} output\texttt{"}  end of the
         Mapping.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetMapping()
      }{
         Pointer to a Mapping whose forward transformation converts
         coordinates from the first coordinate system to the second
         one, and whose inverse transformation converts coordinates in
         the opposite direction.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned Mapping will include the clipping effect of any
         Regions which occur on the path between the two supplied Frames
         (this includes the two supplied Frames themselves).

         \sstitem
         The values given for the \texttt{"} iframe1\texttt{"}  and \texttt{"} iframe2\texttt{"}  parameters
         should lie in the range from 1 to the number of Frames in the
         FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). A value of
         AST\_\_BASE or AST\_\_CURRENT may also be given to identify the
         FrameSet\texttt{'} s base Frame or current Frame respectively.  It is
         permissible for both these parameters to have the same value, in
         which case a unit Mapping (\htmlref{UnitMap}{UnitMap}) is returned.

         \sstitem
         It should always be possible to generate the Mapping
         requested, but this does necessarily guarantee that it will be
         able to perform the required coordinate conversion. If
         necessary, the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes of the
         returned Mapping should be inspected to determine if the
         required transformation is available.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetRefPos
}{
   Return the reference position in a specified celestial coordinate system
}{
   \sstdescription{
      This function
      returns the reference position (specified by attributes \htmlref{RefRA}{RefRA} and
      \htmlref{RefDec}{RefDec}) converted to the celestial coordinate system represented by
      a supplied \htmlref{SkyFrame}{SkyFrame}. The celestial longitude and latitude values
      are returned in radians.
   }
   \sstsynopsis{
      void astGetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double $*$lon,
                         double $*$lat )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{SpecFrame}{SpecFrame}.
      }
      \sstsubsection{
         frm
      }{
         Pointer to the SkyFrame which defines the required celestial
         coordinate system.
         If NULL
         is supplied, then the longitude and latitude values are returned
         as FK5 J2000 RA and Dec values.
      }
      \sstsubsection{
         lon
      }{
         A pointer to a double in which to store the
         longitude of the reference point, in the coordinate system
         represented by the supplied SkyFrame (radians).
      }
      \sstsubsection{
         lat
      }{
         A pointer to a double in which to store the
         latitude of the reference point, in the coordinate system
         represented by the supplied SkyFrame (radians).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Values of AST\_\_BAD will be returned if this function is
         invoked with the AST error status set, or if it should fail for
         any reason.
      }
   }
}
\sstroutine{
   astGetRegionBounds
}{
   Returns the bounding box of Region
}{
   \sstdescription{
      This function
      returns the upper and lower limits of a box which just encompasses
      the supplied \htmlref{Region}{Region}. The limits are returned as axis values within
      the \htmlref{Frame}{Frame} represented by the Region. The value of the \htmlref{Negated}{Negated}
      attribute is ignored (i.e. it is assumed that the Region has not
      been negated).
   }
   \sstsynopsis{
      void astGetRegionBounds( AstRegion $*$this, double $*$lbnd, double $*$ubnd )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an
         array in which to return the lower axis bounds covered by the Region.
         It should have at least as many elements as there are axes in the
         Region. If an axis has no lower limit, the returned value will
         be the largest possible negative value.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an
         array in which to return the upper axis bounds covered by the Region.
         It should have at least as many elements as there are axes in the
         Region. If an axis has no upper limit, the returned value will
         be the largest possible positive value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The value of the Negated attribute is ignored (i.e. it is assumed that
         the Region has not been negated).

         \sstitem
         If an axis has no extent on an axis then the lower limit will be
         returned larger than the upper limit. Note, this is different to an
         axis which has a constant value (in which case both lower and upper
         limit will be returned set to the constant value).

         \sstitem
         If the bounds on an axis cannot be determined, AST\_\_BAD is returned for
         both upper and lower bounds
      }
   }
}
\sstroutine{
   astGetRegionFrame
}{
   Obtain a pointer to the encapsulated Frame within a Region
}{
   \sstdescription{
      This function returns a pointer to the \htmlref{Frame}{Frame} represented by a
      \htmlref{Region}{Region}.
   }
   \sstsynopsis{
      AstFrame $*$astGetRegionFrame( AstRegion $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetRegionFrame()
      }{
         A pointer to a deep copy of the Frame represented by the Region.
         Using this pointer to modify the Frame will have no effect on
         the Region. To modify the Region, use the Region pointer directly.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetRegionFrameSet
}{
   Obtain a pointer to the encapsulated FrameSet within a Region
}{
   \sstdescription{
      This function returns a pointer to the \htmlref{FrameSet}{FrameSet} encapsulated by a
      \htmlref{Region}{Region}. The base \htmlref{Frame}{Frame} is the Frame in which the box was originally
      defined, and the current Frame is the Frame into which the Region
      is currently mapped (i.e. it will be the same as the Frame returned
      by \htmlref{astGetRegionFrame}{astGetRegionFrame}).
   }
   \sstsynopsis{
      AstFrame $*$astGetRegionFrameSet( AstRegion $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetRegionFrameSet()
      }{
         A pointer to a deep copy of the FrameSet represented by the Region.
         Using this pointer to modify the FrameSet will have no effect on
         the Region.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetRegionMesh
}{
   Return a mesh of points covering the surface or volume of a Region
}{
   \sstdescription{
      This function
      returns the axis values at a mesh of points either covering the
      surface (i.e. boundary) of the supplied \htmlref{Region}{Region}, or filling the
      interior (i.e. volume) of the Region. The number of points in
      the mesh is approximately equal to the \htmlref{MeshSize}{MeshSize} attribute.
   }
   \sstsynopsis{
      void astGetRegionMesh( AstRegion $*$this, int surface, int maxpoint,
                             int maxcoord, int $*$npoint, double $*$points )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         surface
      }{
         If non-zero,
         the returned points will cover the surface or the Region.
         Otherwise, they will fill the interior of the Region.
      }
      \sstsubsection{
         maxpoint
      }{
         If zero, the number of points in the mesh is returned in
         \texttt{"} $*$npoint\texttt{"} ,
         but no axis values are returned and all other parameters are ignored.
         If not zero, the supplied value should be the length of the
         second dimension of the \texttt{"} points\texttt{"}
         array. An error is reported if the number of points in the mesh
         exceeds this number.
      }
      \sstsubsection{
         maxcoord
      }{
         The length of the
         first dimension of the \texttt{"} points\texttt{"}  array.
         An error is reported if the number of axes in the supplied Region
         exceeds this number.
      }
      \sstsubsection{
         npoint
      }{
         A pointer to an integer in which to return the
         number of points in the returned mesh.
      }
      \sstsubsection{
         points
      }{
         The address of the first element in a 2-dimensional array of
         shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return the coordinate
         values at the mesh positions. These are stored such that the
         value of coordinate number \texttt{"} coord\texttt{"}  for point number \texttt{"} point\texttt{"}  is
         found in element \texttt{"} points[coord][point]\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error is reported if the Region is unbounded.

         \sstitem
         If the coordinate system represented by the Region has been
         changed since it was first created, the returned axis values refer
         to the new (changed) coordinate system, rather than the original
         coordinate system. Note however that if the transformation from
         original to new coordinate system is non-linear, the shape within
         the new coordinate system may be distorted, and so may not match
         that implied by the name of the Region subclass (\htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc).
      }
   }
}
\sstroutine{
   astGetRegionPoints
}{
   Returns the positions that define the given Region
}{
   \sstdescription{
      This function
      returns the axis values at the points that define the supplied
      \htmlref{Region}{Region}. The particular meaning of these points will depend on the
      type of class supplied, as listed below under \texttt{"} Applicability:\texttt{"} .
   }
   \sstsynopsis{
      void astGetRegionPoints( AstRegion $*$this, int maxpoint, int maxcoord,
                               int $*$npoint, double $*$points )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         maxpoint
      }{
         If zero, the number of points needed to define the Region is
         returned in
         \texttt{"} $*$npoint\texttt{"} ,
         but no axis values are returned and all other parameters are ignored.
         If not zero, the supplied value should be the length of the
         second dimension of the \texttt{"} points\texttt{"}
         array. An error is reported if the number of points needed to define
         the Region exceeds this number.
      }
      \sstsubsection{
         maxcoord
      }{
         The length of the
         first dimension of the \texttt{"} points\texttt{"}  array.
         An error is reported if the number of axes in the supplied Region
         exceeds this number.
      }
      \sstsubsection{
         npoint
      }{
         A pointer to an integer in which to return the
         number of points defining the Region.
      }
      \sstsubsection{
         points
      }{
         The address of the first element in a 2-dimensional array of
         shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return
         the coordinate values at the positions that define the Region.
         These are stored such that the value of coordinate number
         \texttt{"} coord\texttt{"}  for point number \texttt{"} point\texttt{"}  is found in element
         \texttt{"} points[coord][point]\texttt{"} .
      }
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
      \sstsubsection{
         \htmlref{Box}{Box}
      }{
         The first returned position is the Box centre, and the second is
         a Box corner.
      }
      \sstsubsection{
         \htmlref{Circle}{Circle}
      }{
         The first returned position is the Circle centre, and the second is
         a point on the circumference.
      }
      \sstsubsection{
         \htmlref{CmpRegion}{CmpRegion}
      }{
         Returns a value of zero for
         \texttt{"} $*$npoint\texttt{"}
         and leaves the supplied array contents unchanged. To find the
         points defining a CmpRegion, use this method on the component
         Regions, which can be accessed by invoking
         \htmlref{astDecompose}{astDecompose}
         on the CmpRegion.
      }
      \sstsubsection{
         \htmlref{Ellipse}{Ellipse}
      }{
         The first returned position is the Ellipse centre. The second is
         the end of one of the axes of the ellipse. The third is some
         other point on the circumference of the ellipse, distinct from
         the second point.
      }
      \sstsubsection{
         \htmlref{Interval}{Interval}
      }{
         The first point corresponds to the lower bounds position, and
         the second point corresponds to the upper bounds position. These
         are reversed to indicate an extcluded interval rather than an
         included interval. See the Interval constructor for more
         information.
      }
      \sstsubsection{
         \htmlref{NullRegion}{NullRegion}
      }{
         Returns a value of zero for
         \texttt{"} $*$npoint\texttt{"}
         and leaves the supplied array contents unchanged.
      }
      \sstsubsection{
         \htmlref{PointList}{PointList}
      }{
         The positions returned are those that were supplied when the
         PointList was constructed.
      }
      \sstsubsection{
         \htmlref{Polygon}{Polygon}
      }{
         The positions returned are the vertex positions that were supplied
         when the Polygon was constructed.
      }
      \sstsubsection{
         \htmlref{Prism}{Prism}
      }{
         Returns a value of zero for
         \texttt{"} $*$npoint\texttt{"}
         and leaves the supplied array contents unchanged. To find the
         points defining a Prism, use this method on the component
         Regions, which can be accessed by invoking
         astDecompose
         on the CmpRegion.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the coordinate system represented by the Region has been
         changed since it was first created, the returned axis values refer
         to the new (changed) coordinate system, rather than the original
         coordinate system. Note however that if the transformation from
         original to new coordinate system is non-linear, the shape within
         the new coordinate system may be distorted, and so may not match
         that implied by the name of the Region subclass (Circle, Box, etc).
      }
   }
}
\sstroutine{
   astGetStcCoord
}{
   Return information about an AstroCoords element stored in an Stc
}{
   \sstdescription{
      When any sub-class of \htmlref{Stc}{Stc} is created, the constructor function
      allows one or more AstroCoords elements to be stored within the Stc.
      This function allows any one of these AstroCoords elements to be
      retrieved. The format of the returned information is the same as
      that used to pass the original information to the Stc constructor.
      That is, the information is returned in a \htmlref{KeyMap}{KeyMap} structure
      containing elements with one or more of the keys given by symbolic
      constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES,
      AST\_\_STCSIZE and AST\_\_STCPIXSZ.

      If the coordinate system represented by the Stc has been changed
      since it was created (for instance, by changing its \htmlref{System}{System}
      attribute), then the sizes and positions in the returned KeyMap
      will reflect the change in coordinate system.
   }
   \sstsynopsis{
      AstKeyMap $*$astGetStcCoord( AstStc $*$this, int icoord )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Stc.
      }
      \sstsubsection{
         icoord
      }{
         The index of the AstroCoords element required. The first has index
         one. The number of AstroCoords elements in the Stc can be found using
         function astGetStcNcoord.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetStcCoord()
      }{
         A pointer to a new KeyMap containing the required information.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetStcNCoord
}{
   Return the number of AstroCoords elements stored in an Stc
}{
   \sstdescription{
      This function returns the number of AstroCoords elements stored in
      an \htmlref{Stc}{Stc}.
   }
   \sstsynopsis{
      int astGetStcNCoord( AstStc $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Stc.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetStcNCoord()
      }{
         The number of  AstroCoords elements stored in the Stc.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Zero will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetStcRegion
}{
   Obtain a copy of the encapsulated Region within a Stc
}{
   \sstdescription{
      This function returns a pointer to a deep copy of the \htmlref{Region}{Region}
      supplied when the \htmlref{Stc}{Stc} was created.
   }
   \sstsynopsis{
      AstRegion $*$astGetStcRegion( AstStc $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Stc.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetStcRegion()
      }{
         A pointer to a deep copy of the Region encapsulated within the
         supplied Stc.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetTableHeader
}{
   Get the FITS headers from a FitsTable
}{
   \sstdescription{
      This function returns a pointer to a \htmlref{FitsChan}{FitsChan} holding copies of
      the FITS headers associated with a \htmlref{FitsTable}{FitsTable}.
   }
   \sstsynopsis{
      AstFitsChan $*$astGetTableHeader( AstFitsTable $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsTable.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetTableHeader()
      }{
         A pointer to a deep copy of the FitsChan stored within the
         FitsTable.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned pointer should be annulled using
         \htmlref{astAnnul}{astAnnul}
         when it is no longer needed.

         \sstitem
         Changing the contents of the returned FitsChan will have no effect
         on the FitsTable. To modify the FitsTable, the modified FitsChan must
         be stored in the FitsTable using
         \htmlref{astPutTableHeader}{astPutTableHeader}.
      }
   }
}
\sstroutine{
   astGetTables
}{
   Retrieve any FitsTables currently in a FitsChan
}{
   \sstdescription{
      If the supplied \htmlref{FitsChan}{FitsChan} currently contains any tables, then this
      function returns a pointer to a \htmlref{KeyMap}{KeyMap}. Each entry in the KeyMap
      is a pointer to a \htmlref{FitsTable}{FitsTable} holding the data for a FITS binary
      table. The key used to access each entry is the FITS extension
      name in which the table should be stored.

      Tables can be present in a FitsChan as a result either of using the
      \htmlref{astPutTable}{astPutTable} (or \htmlref{astPutTables}{astPutTables})
      method to store existing tables in the FitsChan, or of using the
      \htmlref{astWrite}{astWrite}
      method to write a \htmlref{FrameSet}{FrameSet} to the FitsChan. For the later case, if
      the FitsChan \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"}  attribute is positive and the FrameSet requires
      a look-up table to describe one or more axes, then the \texttt{"} -TAB\texttt{"}
      algorithm code described in FITS-WCS paper III is used and the table
      values are stored in the FitsChan in the form of a FitsTable object
      (see the documentation for the \texttt{"} TabOK\texttt{"}  attribute).
   }
   \sstsynopsis{
      AstKeyMap $*$astGetTables( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetTables()
      }{
         A pointer to a deep copy of the KeyMap holding the tables currently
         in the FitsChan, or
         NULL
         if the FitsChan does not contain any tables. The returned
         pointer should be annulled using
         \htmlref{astAnnul}{astAnnul}
         when no longer needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGetUnc
}{
   Obtain uncertainty information from a Region
}{
   \sstdescription{
      This function returns a \htmlref{Region}{Region} which represents the uncertainty
      associated with positions within the supplied Region. See
      \htmlref{astSetUnc}{astSetUnc}
      for more information about Region uncertainties and their use.
   }
   \sstsynopsis{
      AstRegion $*$astGetUnc( AstRegion $*$this, int def )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         def
      }{
         Controls what is returned if no uncertainty information has been
         associated explicitly with the supplied Region. If
         a non-zero value
         is supplied, then the default uncertainty Region used internally
         within AST is returned (see \texttt{"} Applicability\texttt{"}  below). If
         zero is supplied, then NULL
         will be returned (without error).
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{CmpRegion}{CmpRegion}
      }{
         The default uncertainty for a CmpRegion is taken from one of the
         two component Regions. If the first component Region has a
         non-default uncertainty, then it is used as the default uncertainty
         for the parent CmpRegion. Otherwise, if the second component Region
         has a non-default uncertainty, then it is used as the default
         uncertainty for the parent CmpRegion. If neither of the
         component Regions has non-default uncertainty, then the default
         uncertainty for the CmpRegion is 1.0E-6 of the bounding box of
         the CmpRegion.
      }
      \sstsubsection{
         \htmlref{Prism}{Prism}
      }{
         The default uncertainty for a Prism is formed by combining the
         uncertainties from the two component Regions. If a component
         Region does not have a non-default uncertainty, then its default
         uncertainty will be used to form the default uncertainty of the
         parent Prism.
      }
      \sstsubsection{
         Region
      }{
         For other classes of Region, the default uncertainty is 1.0E-6
         of the bounding box of the Region. If the bounding box has zero
         width on any axis, then the uncertainty will be 1.0E-6 of the
         axis value.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGetUnc()
      }{
         A pointer to a Region describing the uncertainty in the supplied
         Region.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If uncertainty information is associated with a Region, and the
         coordinate system described by the Region is subsequently changed
         (e.g. by changing the value of its \htmlref{System}{System} attribute, or using the
         \htmlref{astMapRegion}{astMapRegion}
         function), then the uncertainty information returned by this function
         will be modified so that it refers to the coordinate system currently
         described by the supplied Region.

         \sstitem
         A null \htmlref{Object}{Object} pointer (NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astGrfPop
}{
   Restore previously saved graphics functions used by a Plot
}{
   \sstdescription{
      This function restores a snapshot of the graphics functions
      stored previously by calling \htmlref{astGrfPush}{astGrfPush}. The restored graphics
      functions become the current graphics functions used by the \htmlref{Plot}{Plot}.

      The astGrfPush and astGrfPop functions are intended for situations
      where it is necessary to make temporary changes to the graphics
      functions used by the Plot. The current functions should first be
      saved by calling astGrfPush. New functions should then be registered
      using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced.
      Finally, astGrfPop should be called to restore the original graphics
      functions.
   }
   \sstsynopsis{
      void astGrfPop( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function returns without action if there are no snapshots to
         restore. No error is reported in this case.
      }
   }
}
\sstroutine{
   astGrfPush
}{
   Save the current graphics functions used by a Plot
}{
   \sstdescription{
      This function takes a snapshot of the graphics functions which are
      currently registered with the supplied \htmlref{Plot}{Plot}, and saves the snapshot
      on a first-in-last-out stack within the Plot. The snapshot can be
      restored later using function
      \htmlref{astGrfPop}{astGrfPop}.

      The astGrfPush and astGrfPop functions are intended for situations
      where it is necessary to make temporary changes to the graphics
      functions used by the Plot. The current functions should first be
      saved by calling astGrfPush. New functions should then be registered
      using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced.
      Finally, astGrfPop should be called to restore the original graphics
      functions.
   }
   \sstsynopsis{
      void astGrfPush( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
   }
}
\sstroutine{
   astGrfSet
}{
   Register a graphics function for use by a Plot
}{
   \sstdescription{
      This function can be used to select the underlying graphics
      functions to be used when the supplied \htmlref{Plot}{Plot} produces graphical output.
      If this function is not called prior to producing graphical
      output, then the underlying graphics functions selected at
      link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use
      alternative graphics functions, call this function before
      the graphical output is created, specifying the graphics
      functions to be used. This will register the function for future
      use, but the function will not actually be used until the \htmlref{Grf}{Grf}
      attribute is given a non-zero value.
   }
   \sstsynopsis{
      void astGrfSet( AstPlot $*$this, const char $*$name, AstGrfFun fun )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         name
      }{
         A name indicating the graphics function to be replaced.
         Various graphics functions are used by the
         Plot class, and any combination of them may be supplied by calling
         this function once for each function to be replaced. If any of the
         graphics functions are not replaced in this way, the
         corresponding functions in the graphics interface selected at
         link-time (using the ast\_link command) are used. The allowed
         names are:

         \sstitemlist{

            \sstitem
            Attr -  Enquire or set a graphics attribute value

            \sstitem
            BBuf - Start a new graphics buffering context

            \sstitem
            Cap -  Inquire a capability

            \sstitem
            EBuf - End the current graphics buffering context

            \sstitem
            Flush - Flush all pending graphics to the output device

            \sstitem
            Line - Draw a polyline (i.e. a set of connected lines)

            \sstitem
            Mark -  Draw a set of markers

            \sstitem
            Qch -  Return the character height in world coordinates

            \sstitem
            Scales -  Get the axis scales

            \sstitem
            Text - Draw a character string

            \sstitem
            TxExt -  Get the extent of a character string

         }
         The string is case insensitive. For details of the interface
         required for each, see the sections below.
      }
      \sstsubsection{
         fun
      }{
         A Pointer to the function to be used to provide the
         functionality indicated by parameter name. The interface for
         each function is described below, but the function pointer should
         be cast to a type of AstGrfFun when calling astGrfSet.

         Once a function has been provided, a null pointer can be supplied
         in a subsequent call to astGrfSet to reset the function to the
         corresponding function in the graphics interface selected at
         link-time.
      }
   }
   \sstdiytopic{
      Function Interfaces
   }{
      All the functions listed below (except for \texttt{"} Cap\texttt{"} ) should return an
      integer value of 0 if an error occurs, and 1 otherwise. All x and y
      values refer
      to \texttt{"} graphics cordinates\texttt{"}  as defined by the graphbox parameter of
      the \htmlref{astPlot}{astPlot} call which created the Plot.

      The first parameter (\texttt{"} grfcon\texttt{"} )
      for each function is an AST \htmlref{KeyMap}{KeyMap} pointer that can be used by the
      called function to establish the context in which it is being called.
      The contents of the KeyMap are determined by the calling
      application, which should obtain a pointer to the KeyMap using the
      \htmlref{astGetGrfContext}{astGetGrfContext} function,
      and then store any necessary information in the KeyMap using the
      methods of the KeyMap class. Note, the functions listed below
      should never annul or delete the supplied KeyMap pointer.
   }
   \sstdiytopic{
      Attr
   }{
      The \texttt{"} Attr\texttt{"}  function returns the current value of a specified graphics
      attribute, and optionally establishes a new value. The supplied
      value is converted to an integer value if necessary before use.
      It requires the following interface:

      int Attr( AstObject $*$grfcon, int attr, double value, double $*$old\_value, int prim )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         attr - An integer value identifying the required attribute.
           The following symbolic values are defined in grf.h:
           GRF\_\_STYLE (Line style),
           GRF\_\_WIDTH (Line width),
           GRF\_\_SIZE (Character and marker size scale factor),
           GRF\_\_FONT (Character font),
           GRF\_\_COLOUR (Colour index).

         \sstitem
         value -
           A new value to store for the attribute. If this is AST\_\_BAD
           no value is stored.

         \sstitem
         old\_value - A pointer to a double in which to return
           the attribute value.
           If this is NULL, no value is returned.

         \sstitem
         prim -
           The sort of graphics primitive to be drawn with the new attribute.
           Identified by the following values defined in grf.h:
           GRF\_\_LINE,
           GRF\_\_MARK,
           GRF\_\_TEXT.
      }
   }
   \sstdiytopic{
      BBuf
   }{
      The \texttt{"} BBuf\texttt{"}  function should start a new graphics buffering context.
      A matching call to the function \texttt{"} EBuf\texttt{"}  should be used to end the
      context. The nature of the buffering is determined by the underlying
      graphics system.

      int BBuf( AstObject $*$grfcon )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.
      }
   }
   \sstdiytopic{
      Cap
   }{
      The \texttt{"} Cap\texttt{"}  function is called to determine if the grf module has a
      given capability, as indicated by the \texttt{"} cap\texttt{"}  argument:

      int Cap( AstObject $*$grfcon, int cap, int value )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         cap -
            The capability being inquired about. This will be one of the
            following constants defined in grf.h:

      }
         GRF\_\_SCALES: This function should return a non-zero value if the
         \texttt{"} Scales\texttt{"}  function is implemented, and zero otherwise. The supplied
         \texttt{"} value\texttt{"}  argument should be ignored.

         GRF\_\_MJUST: This function should return a non-zero value if
         the \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}  functions recognise \texttt{"} M\texttt{"}  as a
         character in the justification string. If the first character of
         a justification string is \texttt{"} M\texttt{"} , then the text should be justified
         with the given reference point at the bottom of the bounding box.
         This is different to \texttt{"} B\texttt{"}  justification, which requests that the
         reference point be put on the baseline of the text, since some
         characters hang down below the baseline. If the \texttt{"} Text\texttt{"}  or
         \texttt{"} TxExt\texttt{"}  function cannot differentiate between \texttt{"} M\texttt{"}  and \texttt{"} B\texttt{"} ,
         then this function should return zero, in which case \texttt{"} M\texttt{"}
         justification will never be requested by Plot. The supplied
         \texttt{"} value\texttt{"}  argument should be ignored.

         GRF\_\_ESC: This function should return a non-zero value if the
         \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}  functions can recognise and interpret
         graphics escape sequences within the supplied string (see
         attribute \htmlref{Escape}{Escape}). Zero should be returned if escape sequences
         cannot be interpreted (in which case the Plot class will interpret
         them itself if needed). The supplied \texttt{"} value\texttt{"}  argument should be
         ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"}  and
         \texttt{"} TxExt\texttt{"} . Otherwise, \texttt{"} value\texttt{"}  indicates whether \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}
         should interpret escape sequences in subsequent calls. If \texttt{"} value\texttt{"}  is
         non-zero then escape sequences should be interpreted by \texttt{"} Text\texttt{"}  and
         \texttt{"} TxExt\texttt{"} . Otherwise, they should be drawn as literal text.

      \sstitemlist{

         \sstitem
         value -
            The use of this parameter depends on the value of \texttt{"} cap\texttt{"}  as
            described above.

         \sstitem
         Returned Function Value:
            The value returned by the function depends on the value of \texttt{"} cap\texttt{"}
            as described above. Zero should be returned if the supplied
            capability is not recognised.
      }
   }
   \sstdiytopic{
      EBuf
   }{
      The \texttt{"} EBuf\texttt{"}  function should end the current graphics buffering
      context. See the description of \texttt{"} BBuf\texttt{"}  above for further details.
      It requires the following interface:

      int EBuf( AstObject $*$grfcon )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.
      }
   }
   \sstdiytopic{
      Flush
   }{
      The \texttt{"} Flush\texttt{"}  function ensures that the display device is up-to-date,
      by flushing any pending graphics to the output device. It
      requires the following interface:

      int Flush( AstObject $*$grfcon )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.
      }
   }
   \sstdiytopic{
      Line
   }{
      The \texttt{"} Line\texttt{"}  function displays lines joining the given positions and
      requires the following interface:

      int Line( AstObject $*$grfcon, int n, const float $*$x, const float $*$y )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         n - The number of positions to be joined together.

         \sstitem
         x - A pointer to an array holding the \texttt{"} n\texttt{"}  x values.

         \sstitem
         y - A pointer to an array holding the \texttt{"} n\texttt{"}  y values.
      }
   }
   \sstdiytopic{
      Mark
   }{
      The \texttt{"} Mark\texttt{"}  function displays markers at the given positions. It
      requires the following interface:

      int Mark( AstObject $*$grfcon, int n, const float $*$x, const float $*$y, int type )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         n - The number of positions to be marked.

         \sstitem
         x - A pointer to an array holding the \texttt{"} n\texttt{"}  x values.

         \sstitem
         y - A pointer to an array holding the \texttt{"} n\texttt{"}  y values.

         \sstitem
         type - An integer which can be used to indicate the type of marker
           symbol required.
      }
   }
   \sstdiytopic{
      Qch
   }{
      The \texttt{"} Qch\texttt{"}  function returns the heights of characters drawn vertically
      and horizontally in graphics coordinates. It requires the following
      interface:

      int Qch( AstObject $*$grfcon, float $*$chv, float $*$chh )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         chv - A pointer to the float which is to receive the height of
         characters drawn with a vertical baseline. This will be an
         increment in the X axis.

         \sstitem
         chh - A pointer to the float which is to receive the height of
         characters drawn with a horizontal baseline. This will be an
         increment in the Y axis.
      }
   }
   \sstdiytopic{
      Scales
   }{
      The \texttt{"} Scales\texttt{"}  function returns two values (one for each axis) which
      scale increments on the corresponding axis into a \texttt{"} normal\texttt{"}  coordinate
      system in which: 1) the axes have equal scale in terms of (for instance)
      millimetres per unit distance, 2) X values increase from left to
      right, and 3) Y values increase from bottom to top. It requires the
      following interface:

      int Scales( AstObject $*$grfcon, float $*$alpha, float $*$beta )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         alpha - A pointer to the float which is to receive the
         scale for the X axis (i.e. Xnorm = alpha$*$Xworld).

         \sstitem
         beta - A pointer to the float which is to receive the
         scale for the Y axis (i.e. Ynorm = beta$*$Yworld).
      }
   }
   \sstdiytopic{
      Text
   }{
      The \texttt{"} Text\texttt{"}  function displays a character string at a given
      position using a specified justification and up-vector. It
      requires the following interface:

      int Text( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just,
                float upx, float upy )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         text - Pointer to a null-terminated character string to be displayed.

         \sstitem
         x - The reference x coordinate.

         \sstitem
         y - The reference y coordinate.

         \sstitem
         just - A character string which specifies the location within the
            text string which is to be placed at the reference position
            given by x and y. The first character may be \texttt{'} T\texttt{'}  for \texttt{"} top\texttt{"} ,
            \texttt{'} C\texttt{'}  for \texttt{"} centre\texttt{"} , or \texttt{'} B\texttt{'}  for \texttt{"} bottom\texttt{"} , and specifies the
            vertical location of the reference position. Note, \texttt{"} bottom\texttt{"}
            corresponds to the base-line of normal text. Some characters
            (eg \texttt{"} y\texttt{"} , \texttt{"} g\texttt{"} , \texttt{"} p\texttt{"} , etc) descend below the base-line. The second
            character may be \texttt{'} L\texttt{'}  for \texttt{"} left\texttt{"} , \texttt{'} C\texttt{'}  for \texttt{"} centre\texttt{"} , or \texttt{'} R\texttt{'}
            for \texttt{"} right\texttt{"} , and specifies the horizontal location of the
            reference position. If the string has less than 2 characters
            then \texttt{'} C\texttt{'}  is used for the missing characters.

         \sstitem
         upx - The x component of the up-vector for the text.
            If necessary the supplied value should be negated
            to ensure that positive values always refer to displacements from
            left to right on the screen.

         \sstitem
         upy - The y component of the up-vector for the text.
            If necessary the supplied value should be negated
            to ensure that positive values always refer to displacements from
            bottom to top on the screen.
      }
   }
   \sstdiytopic{
      TxExt
   }{
      The \texttt{"} TxExt\texttt{"}  function returns the corners of a box which would enclose
      the supplied character string if it were displayed using the
      Text function described above. The returned box includes any leading
      or trailing spaces. It requires the following interface:

      int TxExt( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just,
                 float upx, float upy, float $*$xb, float $*$yb )

      \sstitemlist{

         \sstitem
         grfcon -
           A KeyMap containing information passed from the calling application.

         \sstitem
         text - Pointer to a null-terminated character string to be displayed.

         \sstitem
         x - The reference x coordinate.

         \sstitem
         y - The reference y coordinate.

         \sstitem
         just - A character string which specifies the location within the
            text string which is to be placed at the reference position
            given by x and y. See \texttt{"} Text\texttt{"}  above.

         \sstitem
         upx - The x component of the up-vector for the text.
            See \texttt{"} Text\texttt{"}  above.

         \sstitem
         upy - The y component of the up-vector for the text.
            See \texttt{"} Text\texttt{"}  above.

         \sstitem
         xb - An array of 4 elements in which to return the x coordinate of
            each corner of the bounding box.

         \sstitem
         yb - An array of 4 elements in which to return the y coordinate of
            each corner of the bounding box.
      }
   }
}
\sstroutine{
   astGrid
}{
   Draw a set of labelled coordinate axes
}{
   \sstdescription{
      This function draws a complete annotated set of
      coordinate axes for a \htmlref{Plot}{Plot} with (optionally) a coordinate grid
      superimposed. Details of the axes and grid can be controlled by
      setting values for the various attributes defined by the Plot
      class (q.v.).
   }
   \sstsynopsis{
      void astGrid( AstPlot $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the supplied Plot is a \htmlref{Plot3D}{Plot3D}, the axes will be annotated
         using three 2-dimensional Plots, one for each 2D plane in the 3D
         current coordinate system. The plots will be \texttt{"} pasted\texttt{"}  onto 3 faces
         of the cuboid graphics volume specified when the Plot3D was
         constructed. The faces to be used can be controlled by the \texttt{"} \htmlref{RootCorner}{RootCorner}\texttt{"}
         attribute.

         \sstitem
         An error results if either the current \htmlref{Frame}{Frame} or the base Frame
         of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.

         \sstitem
         An error also results if the transformation between the base
         and current Frames of the Plot is not defined in either
         direction (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} or \htmlref{TranInverse}{TranInverse} attribute
         is zero).
      }
   }
}
\sstroutine{
   astGridLine
}{
   Draw a grid line (or axis) for a Plot
}{
   \sstdescription{
      This function draws a curve in the physical coordinate system of
      a \htmlref{Plot}{Plot} by varying only one of the coordinates along the length
      of the curve. It is intended for drawing coordinate axes,
      coordinate grids, and tick marks on axes (but note that these
      are also available via the more comprehensive \htmlref{astGrid}{astGrid} function).

      The curve is transformed into graphical coordinate space for
      plotting, so that a straight line in physical coordinates may
      result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is
      non-linear. Any discontinuities in the Mapping between physical
      and graphical coordinates are catered for, as is any
      clipping established using \htmlref{astClip}{astClip}.
   }
   \sstsynopsis{
      void astGridLine( AstPlot $*$this, int axis, const double start[],
                        double length )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         axis
      }{
         The index of the Plot axis whose physical coordinate value is
         to be varied along the length of the curve (all other
         coordinates will remain fixed). This value should lie in the
         range from 1 to the number of Plot axes (\htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         start
      }{
         An array, with one element for each axis of the Plot, giving
         the physical coordinates of the start of the curve.
      }
      \sstsubsection{
         length
      }{
         The length of curve to be drawn, given as an increment along
         the selected physical axis. This may be positive or negative.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No curve is drawn if the \texttt{"} start\texttt{"}  array contains any
         coordinates with the value AST\_\_BAD, nor if \texttt{"} length\texttt{"}  has this value.

         \sstitem
         An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astGrismMap
}{
   Create a GrismMap
}{
   \sstdescription{
      This function creates a new \htmlref{GrismMap}{GrismMap} and optionally initialises
      its attributes.

      A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
      1-dimensional coordinates using the spectral dispersion equation
      described in FITS-WCS paper III \texttt{"} Representation of spectral
      coordinates in FITS\texttt{"} . This describes the dispersion produced by
      gratings, prisms and grisms.

      When initially created, the forward transformation of a GrismMap
      transforms input \texttt{"} grism parameter\texttt{"}  values into output wavelength
      values. The \texttt{"} grism parameter\texttt{"}  is a dimensionless value which is
      linearly related to position on the detector. It is defined in FITS-WCS
      paper III as \texttt{"} the offset on the detector from the point of intersection
      of the camera axis, measured in units of the effective local length\texttt{"} .
      The units in which wavelength values are expected or returned is
      determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and
      \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will
      also be used for the wavelength values.
   }
   \sstsynopsis{
      AstGrismMap $*$astGrismMap( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new GrismMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGrismMap()
      }{
         A pointer to the new GrismMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astHasAttribute
}{
   Test if an Object has a named attribute
}{
   \sstdescription{
      This function returns a boolean result (0 or 1) to indicate
      whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name.
   }
   \sstsynopsis{
      int astHasAttribute( AstObject $*$this, const char $*$attrib )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the first Object.
      }
      \sstsubsection{
         attrib
      }{
         Pointer to a string holding the
         name of the attribute to be tested.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astHasAttribute()
      }{
         One if the Object has the named attribute, otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astHasColumn
}{
   Returns a flag indicating if a column is present in a Table
}{
   \sstdescription{
      This function
      returns a flag indicating if a named column exists in a \htmlref{Table}{Table}, for
      instance, by having been added to to the Table using
      \htmlref{astAddColumn}{astAddColumn}.
   }
   \sstsynopsis{
      int astHasColumn( AstTable $*$this, const char $*$column )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         column
      }{
         The character string holding the upper case name of the column. Trailing
         spaces are ignored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of
         zero
         is returned for if an error occurs.
      }
   }
}
\sstroutine{
   astHasParameter
}{
   Returns a flag indicating if a named global parameter is present in a Table
}{
   \sstdescription{
      This function
      returns a flag indicating if a named parameter exists in a \htmlref{Table}{Table}, for
      instance, by having been added to to the Table using
      \htmlref{astAddParameter}{astAddParameter}.
   }
   \sstsynopsis{
      int astHasParameter( AstTable $*$this, const char $*$parameter )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         parameter
      }{
         The character string holding the upper case name of the parameter. Trailing
         spaces are ignored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of
         zero
         is returned for if an error occurs.
      }
   }
}
\sstroutine{
   astImport
}{
   Import an Object pointer to the current context
}{
   \sstdescription{
      This function
      imports an \htmlref{Object}{Object} pointer that was created in a higher or lower
      level context, into the current AST context.
      This means that the pointer will be annulled when the current context
      is ended (with \htmlref{astEnd}{astEnd}).
   }
   \sstsynopsis{
      void astImport( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Object pointer to be imported.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
}
\sstroutine{
   astIntersect
}{
   Find the point of intersection between two geodesic curves
}{
   \sstdescription{
      This function
      finds the coordinate values at the point of intersection between
      two geodesic curves. Each curve is specified by two points on
      the curve.  It can only be used with 2-dimensional Frames.

      For example, in a basic \htmlref{Frame}{Frame}, it will find the point of
      intersection between two straight lines. But for a \htmlref{SkyFrame}{SkyFrame} it
      will find an intersection of two great circles.
   }
   \sstsynopsis{
      void astIntersect( AstFrame $*$this, const double a1[2],
                         const double a2[2], const double b1[2],
                         const double b2[2], double cross[2] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         a1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
         first point on the first geodesic curve.
      }
      \sstsubsection{
         a2
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute). This should contain the coordinates of a
         second point on the first geodesic curve. It should not be
         co-incident with the first point.
      }
      \sstsubsection{
         b1
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute). This should contain the coordinates of the
         first point on the second geodesic curve.
      }
      \sstsubsection{
         b2
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute). This should contain the coordinates of a
         second point on the second geodesic curve. It should not be
         co-incident with the first point.
      }
      \sstsubsection{
         cross
      }{
         An array of double, with one element for each Frame axis
         in which the coordinates of the required intersection will
         be returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For SkyFrames each curve will be a great circle, and in general
         each pair of curves will intersect at two diametrically opposite
         points on the sky. The returned position is the one which is
         closest to point
         \texttt{"} a1\texttt{"} .

         \sstitem
         This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
         if any of the input coordinates has this value, or if the two
         points defining either geodesic are co-incident, or if the two
         curves do not intersect.

         \sstitem
         The geodesic curve used by this function is the path of
         shortest distance between two points, as defined by the
         \htmlref{astDistance}{astDistance} function.

         \sstitem
         An error will be reported if the Frame is not 2-dimensional.
      }
   }
}
\sstroutine{
   astInterval
}{
   Create a Interval
}{
   \sstdescription{
      This function creates a new \htmlref{Interval}{Interval} and optionally initialises its
      attributes.

      A Interval is a \htmlref{Region}{Region} which represents upper and/or lower limits on
      one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region
      represented by the Interval, the point must satisfy all the
      restrictions placed on all the axes. The point is outside the region
      if it fails to satisfy any one of the restrictions. Each axis may have
      either an upper limit, a lower limit, both or neither. If both limits
      are supplied but are in reverse order (so that the lower limit is
      greater than the upper limit), then the interval is an excluded
      interval, rather than an included interval.

      At least one axis limit must be supplied.

      Note, The Interval class makes no allowances for cyclic nature of
      some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box}
      should usually be used in these cases since this requires the user
      to think about suitable upper and lower limits,
   }
   \sstsynopsis{
      AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[],
                                const double ubnd[], AstRegion $*$unc,
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. A deep
         copy is taken of the supplied Frame. This means that any
         subsequent changes made to the Frame using the supplied pointer
         will have no effect the Region.
      }
      \sstsubsection{
         lbnd
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute) containing the lower limits on each axis.
         Set a value to AST\_\_BAD to indicate that the axis has no lower
         limit.
      }
      \sstsubsection{
         ubnd
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute) containing the upper limits on each axis.
         Set a value to AST\_\_BAD to indicate that the axis has no upper
         limit.
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with the boundary of the Interval being created.
         The uncertainty in any point on the boundary of the Interval is found by
         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
         the boundary point being considered. The area covered by the
         shifted uncertainty Region then represents the uncertainty in the
         boundary position. The uncertainty is assumed to be the same for
         all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Interval. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the Interval being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Interval. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astInterval()
      }{
         A pointer to the new Interval.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astIntraMap
}{
   Create an IntraMap
}{
   \sstdescription{
      This function creates a new \htmlref{IntraMap}{IntraMap} and optionally initialises
      its attributes.

      An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates
      a privately-defined coordinate transformation function
      (e.g. written in C) so that it may be used like any other AST
      Mapping. This allows you to create Mappings that perform any
      conceivable coordinate transformation.

      However, an IntraMap is intended for use within a single program
      or a private suite of software, where all programs have access
      to the same coordinate transformation functions (i.e. can be
      linked against them). IntraMaps should not normally be stored in
      datasets which may be exported for processing by other software,
      since that software will not have the necessary transformation
      functions available, resulting in an error.

      You must register any coordinate transformation functions to be
      used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap.
   }
   \sstsynopsis{
      AstIntraMap $*$astIntraMap( const char $*$name, int nin, int nout,
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated string containing the name of
         the transformation function to use (which should previously
         have been registered using astIntraReg). This name is case
         sensitive. All white space will be removed before use.
      }
      \sstsubsection{
         nin
      }{
         The number of input coordinates. This must be compatible with
         the number of input coordinates accepted by the
         transformation function (as specified when this function was
         registered using astIntraReg).
      }
      \sstsubsection{
         nout
      }{
         The number of output coordinates. This must be compatible
         with the number of output coordinates produced by the
         transformation function (as specified when this function was
         registered using astIntraReg).
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new IntraMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astIntraMap()
      }{
         A pointer to the new IntraMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astIntraReg
}{
   Register a transformation function for use by an IntraMap
}{
   \sstdescription{
      This function registers a privately-defined coordinate
      transformation function written in C so that it may be used to
      create an \htmlref{IntraMap}{IntraMap}. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping}
      which encapsulates the C function so that it may be used like
      any other AST Mapping. This allows you to create Mappings that
      perform any conceivable coordinate transformation.

      Registration of relevant transformation functions is required
      before using the \htmlref{astIntraMap}{astIntraMap} constructor function to create an
      IntraMap or reading an external representation of an IntraMap
      from a \htmlref{Channel}{Channel}.
   }
   \sstsynopsis{
      astIntraReg( const char $*$name, int nin, int nout,
                   void ($*$ tran)( AstMapping $*$, int, int, const double $*$[],
                                  int, int, double $*$[] ),
                   unsigned int flags, const char $*$purpose, const char $*$author,
                   const char $*$contact )
   }
   \sstparameters{
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated string containing a unique name
         to be associated with the transformation function in order to
         identify it. This name is case sensitive. All white space
         will be removed before use.
      }
      \sstsubsection{
         nin
      }{
         The number of input coordinates accepted by the
         transformation function (i.e. the number of dimensions of the
         space in which the input points reside). A value of AST\_\_ANY
         may be given if the function is able to accommodate a
         variable number of input coordinates.
      }
      \sstsubsection{
         nout
      }{
         The number of output coordinates produced by the
         transformation function (i.e. the number of dimensions of the
         space in which the output points reside). A value of AST\_\_ANY
         may be given if the function is able to produce a variable
         number of output coordinates.
      }
      \sstsubsection{
         tran
      }{
         Pointer to the transformation function to be registered.
         This function should perform whatever coordinate
         transformations are required and should have an interface
         like \htmlref{astTranP}{astTranP} (q.v.).
      }
      \sstsubsection{
         flags
      }{
         This value may be used to supply a set of flags which
         describe the transformation function and which may affect the
         behaviour of any IntraMap which uses it.  Often, a value of
         zero will be given here, but you may also supply the bitwise
         OR of a set of flags as described in the \texttt{"} Transformation
         Flags\texttt{"}  section (below).
      }
      \sstsubsection{
         purpose
      }{
         Pointer to a null-terminated string containing a short (one
         line) textual comment to describe the purpose of the
         transformation function.
      }
      \sstsubsection{
         author
      }{
         Pointer to a null-terminated string containing the name of
         the author of the transformation function.
      }
      \sstsubsection{
         contact
      }{
         Pointer to a null-terminated string containing contact
         details for the author of the transformation function
         (e.g. an e-mail or WWW address). If any IntraMap which uses
         this transformation function is exported as part of a dataset
         to an external user who does not have access to the function,
         then these contact details should allow them to obtain the
         necessary code.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Beware that an external representation of an IntraMap (created
         by writing it to a Channel) will not include the coordinate
         transformation function which it uses, so will only refer to the
         function by its name (as assigned using astIntraReg).
         Consequently, the external representation cannot be utilised by
         another program unless that program has also registered the same
         transformation function with the same name using an identical
         invocation of astIntraReg. If no such registration has been
         performed, then attempting to read the external representation
         will result in an error.

         \sstitem
         You may use astIntraReg to register a transformation function
         with the same name more than once, but only if the arguments
         supplied are identical on each occasion (i.e there is no way of
         changing things once a function has been successfully registered
         under a given name, and attempting to do so will result in an
         error). This feature simply allows registration to be performed
         independently, but consistently, at several places within your
         program, without having to check whether it has already been
         done.

         \sstitem
         If an error occurs in the transformation function, this may be
         indicated by setting the AST error status to an error value
         (using \htmlref{astSetStatus}{astSetStatus}) before it returns.  This will immediately
         terminate the current AST operation.  The error value AST\_\_ITFER
         is available for this purpose, but other values may also be used
         (e.g. if you wish to distinguish different types of error).
      }
   }
   \sstdiytopic{
      Transformation Flags
   }{
      The following flags are defined in the ``ast.h\texttt{'} \texttt{'}  header file and
      allow you to provide further information about the nature of the
      transformation function. Having selected the set of flags which
      apply, you should supply the bitwise OR of their values as the
      ``flags\texttt{'} \texttt{'}  argument to astIntraReg.

      \sstitemlist{

         \sstitem
         AST\_\_NOFWD: If this flag is set, it indicates that the
         transformation function does not implement a forward coordinate
         transformation. In this case, any IntraMap which uses it will
         have a \htmlref{TranForward}{TranForward} attribute value of zero and the
         transformation function itself will not be invoked with its
         ``forward\texttt{'} \texttt{'}  argument set to a non-zero value.  By default, it is
         assumed that a forward transformation is provided.

         \sstitem
         AST\_\_NOINV: If this flag is set, it indicates that the
         transformation function does not implement an inverse coordinate
         transformation. In this case, any IntraMap which uses it will
         have a \htmlref{TranInverse}{TranInverse} attribute value of zero and the
         transformation function itself will not be invoked with its
         ``forward\texttt{'} \texttt{'}  argument set to zero.  By default, it is assumed
         that an inverse transformation is provided.

         \sstitem
         AST\_\_SIMPFI: You may set this flag if applying the
         transformation function\texttt{'} s forward coordinate transformation,
         followed immediately by the matching inverse transformation,
         should always restore the original set of coordinates. It
         indicates that AST may replace such a sequence of operations by
         an identity Mapping (a \htmlref{UnitMap}{UnitMap}) if it is encountered while
         simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).  It is
         not necessary that both transformations have actually been
         implemented.

         \sstitem
         AST\_\_SIMPIF: You may set this flag if applying the
         transformation function\texttt{'} s inverse coordinate transformation,
         followed immediately by the matching forward transformation,
         should always restore the original set of coordinates. It
         indicates that AST may replace such a sequence of operations by
         an identity Mapping (a UnitMap) if it is encountered while
         simplifying a compound Mapping (e.g. using astSimplify).  It is
         not necessary that both transformations have actually been
         implemented.
      }
   }
}
\sstroutine{
   astInvert
}{
   Invert a Mapping
}{
   \sstdescription{
      This function inverts a \htmlref{Mapping}{Mapping} by reversing the boolean sense
      of its \htmlref{Invert}{Invert} attribute. If this attribute is zero (the
      default), the Mapping will transform coordinates in the way
      specified when it was created. If it is non-zero, the input and
      output coordinates will be inter-changed so that the direction
      of the Mapping is reversed. This will cause it to display the
      inverse of its original behaviour.
   }
   \sstsynopsis{
      void astInvert( AstMapping $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping.
      }
   }
}
\sstroutine{
   astIsA$<$Class$>$
}{
   Test membership of a class by an Object
}{
   \sstdescription{
      This is a family of functions which test whether an \htmlref{Object}{Object} is a
      member of the class called $<$\htmlref{Class}{Class}$>$, or of any class derived from
      it.
   }
   \sstsynopsis{
      int astIsA$<$Class$>$( const Ast$<$Class$>$ $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         These functions apply to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astIsA$<$Class$>$()
      }{
         One if the Object belongs to the class called $<$Class$>$ (or to a
         class derived from it), otherwise zero.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         member = astIsAFrame( obj );
      }{
         Tests whether Object \texttt{"} obj\texttt{"}  is a member of the \htmlref{Frame}{Frame} class, or
         of any class derived from a Frame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Every AST class provides a function (astIsA$<$Class$>$) of this
         form, where $<$Class$>$ should be replaced by the class name.

         \sstitem
         This function attempts to execute even if the AST error status
         is set
         on entry, although no further error report will be made
         if it subsequently fails under these circumstances.

         \sstitem
         A value of zero will be returned if this function should fail
         for any reason. In particular, it will fail if the pointer
         supplied does not identify an Object of any sort.
      }
   }
}
\sstroutine{
   astKeyMap
}{
   Create a KeyMap
}{
   \sstdescription{
      This function creates a new empty \htmlref{KeyMap}{KeyMap} and optionally initialises its
      attributes. Entries can then be added to the KeyMap using the
      \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$} and \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$} functions.

      The KeyMap class is used to store a set of values with associated keys
      which identify the values. The keys are strings. These may be case
      sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and
      trailing spaces are ignored. The value associated with a key can be
      integer (signed 4 and 2 byte, or unsigned 1 byte), floating point
      (single or double precision),
      void pointer,
      character string or AST \htmlref{Object}{Object} pointer. Each
      value can be a scalar or a one-dimensional vector. A KeyMap is
      conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an
      input into an output - the input is the key, and the output is the
      value associated with the key. However, this is only a conceptual
      similarity, and it should be noted that the KeyMap class inherits from
      the Object class rather than the Mapping class. The methods of the
      Mapping class cannot be used with a KeyMap.
   }
   \sstsynopsis{
      AstKeyMap $*$astKeyMap( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new KeyMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astKeyMap()
      }{
         A pointer to the new KeyMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astLinearApprox
}{
   Obtain a linear approximation to a Mapping, if appropriate
}{
   \sstdescription{
      This function tests the forward coordinate transformation
      implemented by a \htmlref{Mapping}{Mapping} over a given range of input coordinates. If
      the transformation is found to be linear to a specified level of
      accuracy, then an array of fit coefficients is returned. These
      may be used to implement a linear approximation to the Mapping\texttt{'} s
      forward transformation within the specified range of output coordinates.
      If the transformation is not sufficiently linear, no coefficients
      are returned.
   }
   \sstsynopsis{
      int astLinearApprox( AstMapping $*$this, const double $*$lbnd,
                           const double $*$ubnd, double tol, double $*$fit )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of doubles
         containing the lower bounds of a box defined within the input
         coordinate system of the Mapping. The number of elements in this
         array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This
         box should specify the region over which linearity is required.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of doubles
         containing the upper bounds of the box specifying the region over
         which linearity is required.
      }
      \sstsubsection{
         tol
      }{
         The maximum permitted deviation from linearity, expressed as
         a positive Cartesian displacement in the output coordinate
         space of the Mapping. If a linear fit to the forward
         transformation of the Mapping deviates from the true transformation
         by more than this amount at any point which is tested, then no fit
         coefficients will be returned.
      }
      \sstsubsection{
         fit
      }{
         Pointer to an array of doubles
         in which to return the co-efficients of the linear
         approximation to the specified transformation. This array should
         have at least \texttt{"} ( Nin $+$ 1 ) $*$ \htmlref{Nout}{Nout}\texttt{"} , elements. The first Nout elements
         hold the constant offsets for the transformation outputs. The
         remaining elements hold the gradients. So if the Mapping has 2 inputs
         and 3 outputs the linear approximation to the forward transformation
         is:

            X\_out = fit[0] $+$ fit[3]$*$X\_in $+$ fit[4]$*$Y\_in

            Y\_out = fit[1] $+$ fit[5]$*$X\_in $+$ fit[6]$*$Y\_in

            Z\_out = fit[2] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astLinearApprox()
      }{
         If the forward transformation is sufficiently linear,
         a non-zero value is returned. Otherwise zero is returned
         and the fit co-efficients are set to AST\_\_BAD.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function fits the Mapping\texttt{'} s forward transformation. To fit
         the inverse transformation, the Mapping should be inverted using
         \htmlref{astInvert}{astInvert}
         before invoking this function.

         \sstitem
         A value of zero
         will be returned if this function is invoked
         with the global error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astLock
}{
   Lock an Object for exclusive use by the calling thread
}{
   \sstdescription{
      The thread-safe public interface to AST is designed so that an
      error is reported if any thread attempts to use an \htmlref{Object}{Object} that it
      has not previously locked for its own exclusive use using this
      function. When an Object is created, it is initially locked by the
      thread that creates it, so newly created objects do not need to be
      explicitly locked. However, if an Object pointer is passed to
      another thread, the original thread must first unlock it (using
      \htmlref{astUnlock}{astUnlock}) and the new thread must then lock it (using astLock)
      before the new thread can use the Object.

      The \texttt{"} wait\texttt{"}  parameter determines what happens if the supplied Object
      is curently locked by another thread when this function is invoked.
   }
   \sstsynopsis{
      void astLock( AstObject $*$this, int wait )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be locked.
      }
      \sstsubsection{
         wait
      }{
         If the Object is curently locked by another thread then this
         function will either report an error or block. If a non-zero value
         is supplied for \texttt{"} wait\texttt{"} , the calling thread waits until the object
         is available for it to use. Otherwise, an error is reported and
         the function returns immediately without locking the Object.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The \htmlref{astAnnul}{astAnnul} function is exceptional in that it can be used on
         pointers for Objects that are not currently locked by the calling
         thread. All other AST functions will report an error.

         \sstitem
         The Locked object will belong to the current AST context.

         \sstitem
         This function returns without action if the Object is already
         locked by the calling thread.

         \sstitem
         If simultaneous use of the same object is required by two or more
         threads, \htmlref{astCopy}{astCopy} should be used to to produce a deep copy of
         the Object for each thread. Each copy should then be unlocked by
         the parent thread (i.e. the thread that created the copy), and then
         locked by the child thread (i.e. the thread that wants to use the
         copy).

         \sstitem
         This function is only available in the C interface.

         \sstitem
         This function returns without action if the AST library has
         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
         option was not specified when running the \texttt{"} configure\texttt{"}  script).
      }
   }
}
\sstroutine{
   astLutMap
}{
   Create a LutMap
}{
   \sstdescription{
      This function creates a new \htmlref{LutMap}{LutMap} and optionally initialises
      its attributes.

      A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
      1-dimensional coordinates by using linear interpolation in a
      lookup table.  Each input coordinate value is first scaled to
      give the index of an entry in the table by subtracting a
      starting value (the input coordinate corresponding to the first
      table entry) and dividing by an increment (the difference in
      input coordinate value between adjacent table entries).

      The resulting index will usually contain a fractional part, so
      the output coordinate value is then generated by interpolating
      linearly between the appropriate entries in the table. If the
      index lies outside the range of the table, linear extrapolation
      is used based on the two nearest entries (i.e. the two entries
      at the start or end of the table, as appropriate).

      If the lookup table entries increase or decrease monotonically,
      then the inverse transformation may also be performed.
   }
   \sstsynopsis{
      AstLutMap $*$astLutMap( int nlut, const double lut[],
                            double start, double inc,
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nlut
      }{
         The number of entries in the lookup table. This value must be
         at least 2.
      }
      \sstsubsection{
         lut
      }{
         An array containing the \texttt{"} nlut\texttt{"}
         lookup table entries.
      }
      \sstsubsection{
         start
      }{
         The input coordinate value which corresponds to the first lookup
         table entry.
      }
      \sstsubsection{
         inc
      }{
         The lookup table spacing (the increment in input coordinate
         value between successive lookup table entries). This value
         may be positive or negative, but must not be zero.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new LutMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astLutMap()
      }{
         A pointer to the new LutMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the entries in the lookup table either increase or decrease
         monotonically, then the new LutMap\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute will
         have a value of one, indicating that the inverse transformation
         can be performed. Otherwise, it will have a value of zero, so
         that any attempt to use the inverse transformation will result
         in an error.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astMapBox
}{
   Find a bounding box for a Mapping
}{
   \sstdescription{
      This function allows you to find the \texttt{"} bounding box\texttt{"}  which just
      encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping}
      (using either its forward or inverse transformation). A typical
      use might be to calculate the size of an image after being
      transformed by a Mapping.

      The function works on one dimension at a time. When supplied
      with the lower and upper bounds of a rectangular region (box) of
      input coordinate space, it finds the lowest and highest values
      taken by a nominated output coordinate within that
      region. Optionally, it also returns the input coordinates where
      these bounding values are attained. It should be used repeatedly
      to obtain the extent of the bounding box in more than one
      dimension.
   }
   \sstsynopsis{
      void astMapBox( AstMapping $*$this,
                      const double lbnd\_in[], const double ubnd\_in[],
                      int forward, int coord\_out,
                      double $*$lbnd\_out, double $*$ubnd\_out,
                      double xl[], double xu[] );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping.
      }
      \sstsubsection{
         lbnd\_in
      }{
         Pointer to an array of double, with one element for each
         Mapping input coordinate. This should contain the lower bound
         of the input box in each input dimension.
      }
      \sstsubsection{
         ubnd\_in
      }{
         Pointer to an array of double, with one element for each
         Mapping input coordinate. This should contain the upper bound
         of the input box in each input dimension.

         Note that it is permissible for the upper bound to be less
         than the corresponding lower bound, as the values will simply
         be swapped before use.
      }
      \sstsubsection{
         forward
      }{
         If this value is non-zero, then the Mapping\texttt{'} s forward
         transformation will be used to transform the input
         box. Otherwise, its inverse transformation will be used.

         (If the inverse transformation is selected, then references
         to \texttt{"} input\texttt{"}  and \texttt{"} output\texttt{"}  coordinates in this description
         should be transposed. For example, the size of the \texttt{"} lbnd\_in\texttt{"}
         and \texttt{"} ubnd\_in\texttt{"}  arrays should match the number of output
         coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout}
         attribute. Similarly, the \texttt{"} coord\_out\texttt{"}  parameter, below,
         should nominate one of the Mapping\texttt{'} s input coordinates.)
      }
      \sstsubsection{
         coord\_out
      }{
         The index of the output coordinate for which the lower and
         upper bounds are required. This value should be at least one,
         and no larger than the number of Mapping output coordinates.
      }
      \sstsubsection{
         lbnd\_out
      }{
         Pointer to a double in which to return the lowest value taken
         by the nominated output coordinate within the specified
         region of input coordinate space.
      }
      \sstsubsection{
         ubnd\_out
      }{
         Pointer to a double in which to return the highest value
         taken by the nominated output coordinate within the specified
         region of input coordinate space.
      }
      \sstsubsection{
         xl
      }{
         An optional pointer to an array of double, with one element
         for each Mapping input coordinate. If given, this array will
         be filled with the coordinates of an input point (although
         not necessarily a unique one) for which the nominated output
         coordinate attains the lower bound value returned in
         \texttt{"} $*$lbnd\_out\texttt{"} .

         If these coordinates are not required, a NULL pointer may be
         supplied.
      }
      \sstsubsection{
         xu
      }{
         An optional pointer to an array of double, with one element
         for each Mapping input coordinate. If given, this array will
         be filled with the coordinates of an input point (although
         not necessarily a unique one) for which the nominated output
         coordinate attains the upper bound value returned in
         \texttt{"} $*$ubnd\_out\texttt{"} .

         If these coordinates are not required, a NULL pointer may be
         supplied.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Any input points which are transformed by the Mapping to give
         output coordinates containing the value AST\_\_BAD are regarded as
         invalid and are ignored. They will make no contribution to
         determining the output bounds, even although the nominated
         output coordinate might still have a valid value at such points.

         \sstitem
         An error will occur if the required output bounds cannot be
         found. Typically, this might happen if all the input points
         which the function considers turn out to be invalid (see
         above). The number of points considered before generating such
         an error is quite large, so this is unlikely to occur by
         accident unless valid points are restricted to a very small
         subset of the input coordinate space.

         \sstitem
         The values returned via \texttt{"} lbnd\_out\texttt{"} , \texttt{"} ubnd\_out\texttt{"} , \texttt{"} xl\texttt{"}  and \texttt{"} xu\texttt{"}
         will be set to the value AST\_\_BAD if this function should fail
         for any reason. Their initial values on entry will not be
         altered if the function is invoked with the AST error status
         set.
      }
   }
}
\sstroutine{
   astMapCopy
}{
   Copy entries from one KeyMap into another
}{
   \sstdescription{
      This function
      copies all entries from one \htmlref{KeyMap}{KeyMap} into another.
   }
   \sstsynopsis{
      void astMapCopy( AstKeyMap $*$this, AstKeyMap $*$that )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the destination KeyMap.
      }
      \sstsubsection{
         that
      }{
         Pointer to the source KeyMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Entries from the source KeyMap will replace any existing entries in
         the destination KeyMap that have the same key.

         \sstitem
         The one exception to the above rule is that if a source entry
         contains a scalar KeyMap entry, and the destination contains a
         scalar KeyMap entry with the same key, then the source KeyMap entry
         will be copied into the destination KeyMap entry using this function,
         rather than simply replacing the destination KeyMap entry.

         \sstitem
         If the destination entry has a non-zero value for its \htmlref{MapLocked}{MapLocked}
         attribute, then an error will be reported if the source KeyMap
         contains any keys that do not already exist within the destination
         KeyMap.
      }
   }
}
\sstroutine{
   astMapDefined
}{
   Check if a KeyMap contains a defined value for a key
}{
   \sstdescription{
      This function checks to see if a \htmlref{KeyMap}{KeyMap} contains a defined value for
      a given key. If the key is present in the KeyMap but has an
      undefined value it returns
      zero (unlike \htmlref{astMapHasKey}{astMapHasKey} which would return non-zero).
   }
   \sstsynopsis{
      int astMapDefined( AstKeyMap $*$this, const char $*$key );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored. The supplied string is converted to upper
         case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapDefined()
      }{
         A non-zero value
         is returned if the requested key name is present in the KeyMap
         and has a defined value.
      }
   }
}
\sstroutine{
   astMapGet0$<$X$>$
}{
   Get a scalar value from a KeyMap
}{
   \sstdescription{
      This is a set of functions for retrieving a scalar value from a \htmlref{KeyMap}{KeyMap}.
      You should replace $<$X$>$ in the generic function name
      astMapGet0$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
      The stored value is converted to the data type indiced by $<$X$>$
      before being returned (an error is reported if it is not possible to
      convert the stored value to the requested data type).
   }
   \sstsynopsis{
      int astMapGet0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type $*$value );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored. The supplied string is converted to upper
         case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         value
      }{
         A pointer to a buffer in which to return the requested value.
         If the requested key is not found, or if it is found but has an
         undefined value (see
         \htmlref{astMapPutU}{astMapPutU}),
         then the contents of the
         buffer on entry to this function will be unchanged on exit.
         For pointer types (\texttt{"} A\texttt{"}  and \texttt{"} C\texttt{"} ), the buffer should be a suitable
         pointer, and the address of this pointer should be supplied as the
         \texttt{"} value\texttt{"}  parameter.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapGet0$<$X$>$()
      }{
         A non-zero value
         is returned if the requested key name was found, and does not have
         an undefined value (see
         astMapPutU). Zero
         is returned otherwise.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No error is reported if the requested key cannot be found in the
         given KeyMap, but a
         zero
         value will be returned as the function value. The supplied buffer
         will be returned unchanged.

         \sstitem
         If the stored value is a vector value, then the first value in
         the vector will be returned.

         \sstitem
         A string pointer returned by astMapGet0C is guaranteed to remain valid
         and the string to which it points will not be over-written for a
         total of 50 successive invocations of this function. After this,
         the memory containing the string may be re-used, so a copy of
         the string should be made if it is needed for longer than this. The
         calling code should never attempt to free the returned pointer
         (for instance, using \htmlref{astFree}{astFree}).

         \sstitem
         If the returned value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference
         count is incremented by this call. Any subsequent changes made to
         the Object using the returned pointer will be reflected in any
         any other active pointers for the Object. The returned pointer
         should be annulled using
         \htmlref{astAnnul}{astAnnul}
         when it is no longer needed.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         F: float

         \sstitem
         D: double

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: Unsigned byte (i.e. word)

      }
      For example, astMapGet0D would be used to get a \texttt{"} double\texttt{"}  value,
      while astMapGet0I would be used to get an \texttt{"} int\texttt{"} , etc.
   }
}
\sstroutine{
   astMapGet1$<$X$>$
}{
   Get a vector value from a KeyMap
}{
   \sstdescription{
      This is a set of functions for retrieving a vector value from a \htmlref{KeyMap}{KeyMap}.
      You should replace $<$X$>$ in the generic function name
      astMapGet1$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
      The stored value is converted to the data type indiced by $<$X$>$
      before being returned (an error is reported if it is not possible to
      convert the stored value to the requested data type).
      Note, the astMapGet1C function has an extra parameter \texttt{"} l\texttt{"}  which
      specifies the maximum length of each string to be stored in the
      \texttt{"} value\texttt{"}  buffer (see the \texttt{"} astMapGet1C\texttt{"}  section below).
   }
   \sstsynopsis{
      int astMapGet1$<$X$>$( AstKeyMap $*$this, const char $*$key, int mxval,
                         int $*$nval, $<$X$>$type $*$value )
      int astMapGet1C( AstKeyMap $*$this, const char $*$key, int l, int mxval,
                       int $*$nval, const char $*$value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         mxval
      }{
         The number of elements in the
         \texttt{"} value\texttt{"}  array.
      }
      \sstsubsection{
         nval
      }{
         The address of an integer in which to put the
         number of elements stored in the
         \texttt{"} value\texttt{"}  array.
         Any unused elements of the array are left unchanged.
      }
      \sstsubsection{
         value
      }{
         A pointer to an array in which to return the requested values.
         If the requested key is not found, or if it is found but has an
         undefined value (see
         \htmlref{astMapPutU}{astMapPutU}),
         then the contents of the
         buffer on entry to this function will be unchanged on exit.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapGet1$<$X$>$()
      }{
         A non-zero value
         is returned if the requested key name was found, and does not have
         an undefined value (see
         astMapPutU). Zero
         is returned otherwise.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No error is reported if the requested key cannot be found in the
         given KeyMap, but a
         zero
         value will be returned as the function value. The supplied array
         will be returned unchanged.

         \sstitem
         If the stored value is a scalar value, then the value will be
         returned in the first element of the supplied array, and
         \texttt{"} nval\texttt{"}
         will be returned set to 1.
      }
   }
   \sstdiytopic{
      astMapGet1C
   }{
      The \texttt{"} value\texttt{"}  buffer supplied to the astMapGet1C function should be a
      pointer to a character array with \texttt{"} mxval$*$l\texttt{"}  elements, where \texttt{"} l\texttt{"}  is
      the maximum length of a string to be returned. The value of \texttt{"} l\texttt{"}
      should be supplied as an extra parameter following \texttt{"} key\texttt{"}  when
      invoking astMapGet1C, and should include space for a terminating
      null character.
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: Unsigned byte (i.e. char)

      }
      For example, astMapGet1D would be used to get \texttt{"} double\texttt{"}  values, while
      astMapGet1I would be used to get \texttt{"} int\texttt{"}  values, etc. For D or I, the
      supplied \texttt{"} value\texttt{"}  parameter should be a pointer to an array of doubles
      or ints, with \texttt{"} mxval\texttt{"}  elements. For C, the supplied \texttt{"} value\texttt{"}  parameter
      should be a pointer to a character string with \texttt{"} mxval$*$l\texttt{"}  elements.
      For A, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to an
      array of AstObject pointers.
   }
}
\sstroutine{
   astMapGetElem$<$X$>$
}{
   Get a single element of a vector value from a KeyMap
}{
   \sstdescription{
      This is a set of functions for retrieving a single element of a vector
      value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name
      astMapGetElem$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
      The stored value is converted to the data type indiced by $<$X$>$
      before being returned (an error is reported if it is not possible to
      convert the stored value to the requested data type).
      Note, the astMapGetElemC function has an extra parameter \texttt{"} l\texttt{"}  which
      specifies the maximum length of the string to be stored in the
      \texttt{"} value\texttt{"}  buffer (see the \texttt{"} astMapGetElemC\texttt{"}  section below).
   }
   \sstsynopsis{
      int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem,
                            $<$X$>$type $*$value )
      int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem,
                          char $*$value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         elem
      }{
         The index of the required vector element, starting at
         zero.
         An error will be reported if the value is outside the range of
         the vector.
      }
      \sstsubsection{
         value
      }{
         A pointer to a buffer in which to return the requested value.
         If the requested key is not found, or if it is found but has an
         undefined value (see
         \htmlref{astMapPutU}{astMapPutU}),
         then the contents of the
         buffer on entry to this function will be unchanged on exit.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapGetElem$<$X$>$()
      }{
         A non-zero value
         is returned if the requested key name was found, and does not have
         an undefined value (see
         astMapPutU). Zero
         is returned otherwise.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No error is reported if the requested key cannot be found in the
         given KeyMap, or if it has an undefined value, but a
         zero
         value will be returned as the function value.
      }
   }
   \sstdiytopic{
      astMapGetElemC
   }{
      The \texttt{"} value\texttt{"}  buffer supplied to the astMapGetElemC function should be a
      pointer to a character array with \texttt{"} l\texttt{"}  elements, where \texttt{"} l\texttt{"}  is the
      maximum length of the string to be returned. The value of \texttt{"} l\texttt{"}
      should be supplied as an extra parameter following \texttt{"} key\texttt{"}  when
      invoking astMapGetElemC, and should include space for a terminating
      null character.
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name
      astMapGetElem$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: Unsigned byte (i.e. char)

      }
      For example, astMapGetElemD would be used to get a \texttt{"} double\texttt{"}  value, while
      astMapGetElemI would be used to get an \texttt{"} int\texttt{"}  value, etc. For D or I, the
      supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a double or int. For
      C, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a character
      string with \texttt{"} l\texttt{"}  elements. For A, the supplied \texttt{"} value\texttt{"}  parameter should
      be a pointer to an AstObject pointer.
   }
}
\sstroutine{
   astMapHasKey
}{
   Check if an entry with a given key exists in a KeyMap
}{
   \sstdescription{
      This function returns a flag indicating if the \htmlref{KeyMap}{KeyMap} contains an
      entry with the given key.
   }
   \sstsynopsis{
      int astMapHasKey( AstKeyMap $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the KeyMap entry. Trailing spaces are
         ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapHasKey()
      }{
         Non-zero if the key was found, and zero otherwise.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A non-zero function value
         is returned if the key exists but has an undefined value (that is,
         the returned value does not depend on whether the entry has a
         defined value or not). See also
         \htmlref{astMapDefined}{astMapDefined}, which returns zero in such a case.

         \sstitem
         A function value of
         zero
         will be returned if an error has already occurred, or if this
         function should fail for any reason.
      }
   }
}
\sstroutine{
   astMapKey
}{
   Get the key at a given index within the KeyMap
}{
   \sstdescription{
      This function returns a string holding the key for the entry with
      the given index within the \htmlref{KeyMap}{KeyMap}.

      This function is intended primarily as a means of iterating round all
      the elements in a KeyMap. For this purpose, the number of entries in
      the KeyMap should first be found using
      \htmlref{astMapSize}{astMapSize}
      and this function should then be called in a loop, with the index
      value going from
      zero to one less than the size of the KeyMap.
      The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy}
      attribute.
   }
   \sstsynopsis{
      const char $*$astMapKey( AstKeyMap $*$this, int index )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         index
      }{
         The index into the KeyMap. The first entry has index
         zero, and the last has index \texttt{"} size-1\texttt{"} , where \texttt{"} size\texttt{"}  is the value
         returned by the astMapSize function.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapKey()
      }{
         A pointer to a null-terminated string containing the key.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned pointer is guaranteed to remain valid and the
         string to which it points will not be over-written for a total
         of 50 successive invocations of this function. After this, the
         memory containing the string may be re-used, so a copy of the
         string should be made if it is needed for longer than this.

         \sstitem
         A NULL pointer will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astMapLenC
}{
   Get the number of characters in a character entry in a KeyMap
}{
   \sstdescription{
      This function returns the minimum length which a character variable
      which must have in order to be able to store a specified entry in
      the supplied \htmlref{KeyMap}{KeyMap}. If the named entry is a vector entry, then the
      returned value is the length of the longest element of the vector
      value.
   }
   \sstsynopsis{
      int astMapLenC( AstKeyMap $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the KeyMap entry. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapLenC()
      }{
         The length (i.e. number of characters) of the longest formatted
         value associated with the named entry.
         This does not include the trailing null character.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A function value of zero will be returned without error if the
         named entry cannot be formatted as a character string.

         \sstitem
         A function value of zero will be returned if an error has already
         occurred, or if this function should fail for any reason.
      }
   }
}
\sstroutine{
   astMapLength
}{
   Get the vector length of an entry in a KeyMap
}{
   \sstdescription{
      This function returns the vector length of a named entry in a \htmlref{KeyMap}{KeyMap},
      (that is, how many values are associated with the entry).
   }
   \sstsynopsis{
      int astMapLength( AstKeyMap $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the KeyMap entry. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapLength()
      }{
         The length of the entry. One for a scalar, greater than one for
         a vector. A value of zero is returned if the KeyMap does not
         contain the named entry.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A function value of zero will be returned if an error has already
         occurred, or if this function should fail for any reason.
      }
   }
}
\sstroutine{
   astMapPut0$<$X$>$
}{
   Add a scalar value to a KeyMap
}{
   \sstdescription{
      This is a set of functions
      for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a
      function
      which matches the data type of the data you wish to add to the KeyMap
      by replacing $<$X$>$ in the generic
      function name astMapPut0$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
   }
   \sstsynopsis{
      void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value,
                          const char $*$comment );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap in which to store the supplied value.
      }
      \sstsubsection{
         key
      }{
         A character string to be stored with the value, which can later
         be used to identify the value. Trailing spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         value
      }{
         The value to be stored. The data type of this value should match the
         1-character type code appended to the
         function name (e.g. if you are using astMapPut0A, the type of this
         value should be \texttt{"} pointer to AstObject\texttt{"} ).
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null-terminated comment string to be stored with the
         value. A NULL pointer may be supplied, in which case no comment is
         stored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the supplied key is already in use in the KeyMap, the new value
         will replace the old value.

         \sstitem
         If the stored value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference
         count is incremented by this call. Any subsequent changes made to
         the Object using the returned pointer will be reflected in any
         any other active pointers for the Object, including any obtained
         later using
         astMapget0A.
         The reference count for the Object will be decremented when the
         KeyMap is destroyed, or the entry is removed or over-written with a
         different pointer.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name astMapPut0$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: unsigned byte (i.e. unsigned char)

      }
      For example, astMapPut0D would be used to store a \texttt{"} double\texttt{"}  value,
      while astMapPut0I would be used to store an \texttt{"} int\texttt{"} , etc.

      Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"}  pointers cannot be
      written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if
      this is attempted.
   }
}
\sstroutine{
   astMapPut1$<$X$>$
}{
   Add a vector value to a KeyMap
}{
   \sstdescription{
      This is a set of functions
      for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a
      function
      which matches the data type of the data you wish to add to the KeyMap
      by replacing $<$X$>$ in the generic
      function name astMapPut1$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
   }
   \sstsynopsis{
      void astMapPut1$<$X$>$( AstKeyMap $*$this, const char $*$key, int size,
                          const $<$X$>$type value[], const char $*$comment );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap in which to store the supplied values.
      }
      \sstsubsection{
         key
      }{
         A character string to be stored with the values, which can later
         be used to identify the values. Trailing spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         size
      }{
         The number of elements in the supplied array of values.
      }
      \sstsubsection{
         value
      }{
         The array of values to be stored. The data type of this value should
         match the 1-character type code appended to the
         function name (e.g. if you are using astMapPut1A, the type of this
         value should be \texttt{"} array of pointers to AstObject\texttt{"} ).
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null-terminated comment string to be stored with the
         values. A NULL pointer may be supplied, in which case no comment is
         stored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the supplied key is already in use in the KeyMap, the new values
         will replace the old values.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name astMapPut1$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: Unsigned byte (i.e. char)

      }
      For example, astMapPut1D would be used to store \texttt{"} double\texttt{"}  values,
      while astMapPut1I would be used to store \texttt{"} int\texttt{"} , etc.

      Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"}  pointers cannot be
      written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if
      this is attempted.
   }
}
\sstroutine{
   astMapPutElem$<$X$>$
}{
   Put a value into an element of a vector value in a KeyMap
}{
   \sstdescription{
      This is a set of functions for storing a value in a single element of
      a vector value in a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic
      function name
      astMapPutElem$<$X$>$
      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
      section below for the code appropriate to each supported data type).
      The supplied value is converted from the data type indicated by $<$X$>$
      to the data type of the KeyMap entry before being stored (an error
      is reported if it is not possible to convert the value to the
      required data type).
   }
   \sstsynopsis{
      void astMapPutElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem,
                             $<$X$>$type $*$value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         elem
      }{
         The index of the vector element to modify, starting at
         zero.
      }
      \sstsubsection{
         value
      }{
         The value to store.
      }
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         If the
         \texttt{"} elem\texttt{"}
         index is outside the range of the vector, the length of
         the vector will be increased by one element and the supplied
         value will be stored at the end of the vector in the new element.
      }
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         If the
         \texttt{"} elem\texttt{"}
         index is outside the range of the vector, an error will be
         reported. The number of elements in each cell of a column is
         specified when the column is created using
         \htmlref{astAddColumn}{astAddColumn}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the entry originally holds a scalar value, it will be treated
         like a vector entry of length 1.

         \sstitem
         If the specified key cannot be found in the given KeyMap, or is
         found but has an undefined value, a new
         vector entry with the given name, and data type implied by $<$X$>$, is
         created and the supplied value is stored in its first entry.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate
      function, you should replace $<$X$>$ in the generic function name
      astMapPutElem$<$X$>$
      with a 1-character data type code, so as to match the data type $<$X$>$type
      of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         C: \texttt{"} const\texttt{"}  pointer to null terminated character string

         \sstitem
         A: Pointer to AstObject

         \sstitem
         P: Generic \texttt{"} void $*$\texttt{"}  pointer

         \sstitem
         S: short int

         \sstitem
         B: Unsigned byte (i.e. char)

      }
      For example, astMapPutElemD would be used to put a \texttt{"} double\texttt{"}  value, while
      astMapPutElemI would be used to put an \texttt{"} int\texttt{"}  value, etc. For D or I, the
      supplied \texttt{"} value\texttt{"}  parameter should be a double or int. For
      C, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a character
      string. For A, the supplied \texttt{"} value\texttt{"}  parameter should be an AstObject
      pointer.
   }
}
\sstroutine{
   astMapPutU
}{
   Add an entry to a KeyMap with an undefined value
}{
   \sstdescription{
      This function
      adds a new entry to a \htmlref{KeyMap}{KeyMap}, but no value is stored with the
      entry. The entry therefore has a special data type represented by
      symbolic constant AST\_\_UNDEFTYPE.

      An example use is to add entries with undefined values to a KeyMap
      prior to locking them with the \htmlref{MapLocked}{MapLocked} attribute. Such entries
      can act as placeholders for values that can be added to the KeyMap
      later.
   }
   \sstsynopsis{
      void astMapPutU( AstKeyMap $*$this, const char $*$key, const char $*$comment );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap in which to store the supplied value.
      }
      \sstsubsection{
         key
      }{
         A character string to be stored with the value, which can later
         be used to identify the value. Trailing spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null-terminated comment string to be stored with the
         value. A NULL pointer may be supplied, in which case no comment is
         stored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the supplied key is already in use in the KeyMap, the value
         associated with the key will be removed.
      }
   }
}
\sstroutine{
   astMapRegion
}{
   Transform a Region into a new Frame using a given Mapping
}{
   \sstdescription{
      This function returns a pointer to a new \htmlref{Region}{Region} which corresponds to
      supplied Region described by some other specified coordinate system. A
      \htmlref{Mapping}{Mapping} is supplied which transforms positions between the old and new
      coordinate systems. The new Region may not be of the same class as
      the original region.
   }
   \sstsynopsis{
      AstRegion $*$astMapRegion( AstRegion $*$this, AstMapping $*$map,
                               AstFrame $*$frame )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         map
      }{
         Pointer to a Mapping which transforms positions from the
         coordinate system represented by the supplied Region to the
         coordinate system specified by
         \texttt{"} frame\texttt{"} .
         The supplied Mapping should define both forward and inverse
         transformations, and these transformations should form a genuine
         inverse pair. That is, transforming a position using the forward
         transformation and then using the inverse transformation should
         produce the original input position. Some Mapping classes (such
         as \htmlref{PermMap}{PermMap}, \htmlref{MathMap}{MathMap}, \htmlref{SphMap}{SphMap}) can result in Mappings for which this
         is not true.
      }
      \sstsubsection{
         frame
      }{
         Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which
         the new Region is required.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapRegion()
      }{
         A pointer to a new Region. This Region will represent the area
         within the coordinate system specified by
         \texttt{"} frame\texttt{"}
         which corresponds to the supplied Region.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The uncertainty associated with the supplied Region is modified
         using the supplied Mapping.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astMapRemove
}{
   Removed a named entry from a KeyMap
}{
   \sstdescription{
      This function
      removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the
      KeyMap does not contain the specified key.
   }
   \sstsynopsis{
      void astMapRemove( AstKeyMap $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the value to be retrieved. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
}
\sstroutine{
   astMapRename
}{
   Rename an existing KeyMap entry
}{
   \sstdescription{
      This function
      associated a new key with an existing entry in a \htmlref{KeyMap}{KeyMap}. It returns
      without action if the oldkey does not exist in the KeyMap.
   }
   \sstsynopsis{
      void astMapRename( AstKeyMap $*$this, const char $*$oldkey, const char $*$newkey )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         oldkey
      }{
         The character string identifying the entry to be renamed. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
      \sstsubsection{
         newkey
      }{
         The new character string to associated with the renamed entry.
         Trailing spaces are ignored.
         The supplied string is converted to upper case before use if the
         KeyCase attribute is currently set to zero.
      }
   }
}
\sstroutine{
   astMapSize
}{
   Get the number of entries in a KeyMap
}{
   \sstdescription{
      This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}.
   }
   \sstsynopsis{
      int astMapSize( AstKeyMap $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapSize()
      }{
         The number of entries in the KeyMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A function value of zero will be returned if an error has already
         occurred, or if this function should fail for any reason.
      }
   }
}
\sstroutine{
   astMapSplit
}{
   Split a Mapping up into parallel component Mappings
}{
   \sstdescription{
      This function
      creates a new \htmlref{Mapping}{Mapping} which connects specified inputs within a
      supplied Mapping to the corresponding outputs of the supplied Mapping.
      This is only possible if the specified inputs correspond to some
      subset of the Mapping outputs. That is, there must exist a subset of
      the Mapping outputs for which each output depends only on the selected
      Mapping inputs, and not on any of the inputs which have not been
      selected. Also, any output which is not in this subset must not depend
      on any of the selected inputs. If these conditions are not met by the
      supplied Mapping, then
      a NULL
      Mapping pointer is returned.
   }
   \sstsynopsis{
      void astMapSplit( AstMapping $*$this, int nin, const int $*$in, int $*$out,
                        AstMapping $*$$*$map )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be split.
      }
      \sstsubsection{
         nin
      }{
         The number of inputs to pick from \texttt{"} this\texttt{"} .
      }
      \sstsubsection{
         in
      }{
         Pointer to an
         array holding the indices within the supplied Mapping of the inputs
         which are to be picked from the Mapping.
         This array should have \texttt{"} nin\texttt{"}  elements.
         If \texttt{"} \htmlref{Nin}{Nin}\texttt{"}  is the number of inputs of the supplied Mapping, then each
         element should have a value in the range 1 to Nin.
      }
      \sstsubsection{
         out
      }{
         Pointer to an
         array in which to return the indices of the outputs of the supplied
         Mapping which are fed by the picked inputs. A value of one is
         used to refer to the first Mapping output. The supplied array should
         have a length at least equal to the number of outputs in the
         supplied Mapping. The number of values stored in the array on
         exit will equal the number of outputs in the returned Mapping.
         The i\texttt{'} th element in the returned array holds the index within
         the supplied Mapping which corresponds to the i\texttt{'} th output of
         the returned Mapping.
      }
      \sstsubsection{
         map
      }{
         Address of a location at which to return a pointer to the
         returned Mapping. This Mapping will have
         \texttt{"} nin\texttt{"}  inputs (the number of outputs may be different to \texttt{"} nin\texttt{"} ). NULL
         is returned if the supplied Mapping has no subset of outputs which
         depend only on the selected inputs. The returned Mapping is a
         deep copy of the required parts of the supplied Mapping.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If this
         function
         is invoked with the global error status set, or if it should fail for
         any reason, then
         a NULL value
         will be returned for
         the \texttt{"} map\texttt{"}  pointer.
      }
   }
}
\sstroutine{
   astMapType
}{
   Get the data type of an entry in a KeyMap
}{
   \sstdescription{
      This function returns a value indicating the data type of a
      named entry in a \htmlref{KeyMap}{KeyMap}. This is the data type which was used when the
      entry was added to the KeyMap.
   }
   \sstsynopsis{
      int astMapType( AstKeyMap $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the KeyMap.
      }
      \sstsubsection{
         key
      }{
         The character string identifying the KeyMap entry. Trailing
         spaces are ignored.
         The supplied string is converted to upper case before use if the
         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMapType()
      }{
         One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
         short int),
         AST\_\_BYTETYPE (for unsigned bytes
         \sstitemlist{

            \sstitem
            i.e. unsigned chars
            ) AST\_\_DOUBLETYPE (for double
            precision floating point), AST\_\_FLOATTYPE (for single
            precision floating point), AST\_\_STRINGTYPE (for character string),
            AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
            arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
            created by
            \htmlref{astMapPutU}{astMapPutU}).
            AST\_\_BADTYPE is returned if the supplied key is not found in the KeyMap.
         }
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A function value of AST\_\_BADTYPE will be returned if an error has
         already occurred, or if this function should fail for any reason.
      }
   }
}
\sstroutine{
   astMark
}{
   Draw a set of markers for a Plot
}{
   \sstdescription{
      This function draws a set of markers (symbols) at positions
      specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The
      positions are transformed into graphical coordinates to
      determine where the markers should appear within the plotting
      area.
   }
   \sstsynopsis{
      void astMark( AstPlot $*$this, int nmark, int ncoord, int indim,
                    const double $*$in, int type )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         nmark
      }{
         The number of markers to draw. This may be zero, in which
         case nothing will be drawn.
      }
      \sstsubsection{
         ncoord
      }{
         The number of coordinates being supplied for each mark
         (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as
         given by its \htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         indim
      }{
         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
         array (which contains the marker coordinates). This value is
         required so that the coordinate values can be correctly
         located if they do not entirely fill this array. The value
         given should not be less than \texttt{"} nmark\texttt{"} .
      }
      \sstsubsection{
         in
      }{
         The address of the first element of a 2-dimensional array of
         shape \texttt{"} [ncoord][indim]\texttt{"}  giving the
         physical coordinates of the points where markers are to be
         drawn. These should be stored such that the value of
         coordinate number \texttt{"} coord\texttt{"}  for input mark number \texttt{"} mark\texttt{"}  is
         found in element \texttt{"} in[coord][mark]\texttt{"} .
      }
      \sstsubsection{
         type
      }{
         A value specifying the type (e.g. shape) of marker to be
         drawn. The set of values which may be used (and the shapes
         that will result) is determined by the underlying graphics
         system.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Markers are not drawn at positions which have any coordinate
         equal to the value AST\_\_BAD (or where the transformation into
         graphical coordinates yields coordinates containing the value
         AST\_\_BAD).

         \sstitem
         If any marker position is clipped (see \htmlref{astClip}{astClip}), then the
         entire marker is not drawn.

         \sstitem
         An error results if the base Frame of the Plot is not 2-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astMask$<$X$>$
}{
   Mask a region of a data grid
}{
   \sstdescription{
      This is a set of functions for masking out regions within gridded data
      (e.g. an image). The functions modifies a given data grid by
      assigning a specified value to all samples which are inside (or outside
      if \texttt{"} inside\texttt{"}  is zero)
      the specified \htmlref{Region}{Region}.

      You should use a masking function which matches the numerical
      type of the data you are processing by replacing $<$X$>$ in
      the generic function name astMask$<$X$>$ by an appropriate 1- or
      2-character type code. For example, if you are masking data
      with type \texttt{"} float\texttt{"} , you should use the function astMaskF (see
      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
      other numerical types).
   }
   \sstsynopsis{
      int astMask$<$X$>$( AstRegion $*$this, AstMapping $*$map, int inside, int ndim,
                      const int lbnd[], const int ubnd[], $<$Xtype$>$ in[],
                      $<$Xtype$>$ val )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to a Region.
      }
      \sstsubsection{
         map
      }{
         Pointer to a \htmlref{Mapping}{Mapping}. The forward transformation should map
         positions in the coordinate system of the supplied Region
         into pixel coordinates as defined by the
         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  parameters. A NULL pointer
         can be supplied if the coordinate system of the supplied Region
         corresponds to pixel coordinates. This is equivalent to
         supplying a \htmlref{UnitMap}{UnitMap}.

         The number of inputs for this Mapping (as given by its \htmlref{Nin}{Nin} attribute)
         should match the number of axes in the supplied Region (as given
         by the \htmlref{Naxes}{Naxes} attribute of the Region).
         The number of outputs for the Mapping (as given by its \htmlref{Nout}{Nout} attribute)
         should match the number of
         grid dimensions given by the value of \texttt{"} ndim\texttt{"}
         below.
      }
      \sstsubsection{
         inside
      }{
         A boolean value which indicates which pixel are to be masked. If
         a non-zero value
         is supplied, then all grid pixels with centres inside the supplied
         Region are assigned the value given by
         \texttt{"} val\texttt{"} ,
         and all other pixels are left unchanged. If
         zero
         is supplied, then all grid pixels with centres not inside the supplied
         Region are assigned the value given by
         \texttt{"} val\texttt{"} ,
         and all other pixels are left unchanged. Note, the \htmlref{Negated}{Negated}
         attribute of the Region is used to determine which pixel are
         inside the Region and which are outside. So the inside of a Region
         which has not been negated is the same as the outside of the
         corresponding negated Region.

         For types of Region such as \htmlref{PointList}{PointList} which have zero volume,
         pixel centres will rarely fall exactly within the Region. For
         this reason, the inclusion criterion is changed for zero-volume
         Regions so that pixels are included (or excluded) if any part of
         the Region passes through the pixel. For a PointList, this means
         that pixels are included (or excluded) if they contain at least
         one of the points listed in the PointList.
      }
      \sstsubsection{
         ndim
      }{
         The number of dimensions in the input grid. This should be at
         least one.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre.
      }
      \sstsubsection{
         in
      }{
         Pointer to an array, with one element for each pixel in the
         input grid, containing the data to be masked.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astMaskF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).

         On exit, the samples specified by
         \texttt{"} inside\texttt{"}  are set to the value of \texttt{"} val\texttt{"} .
         All other samples are left unchanged.
      }
      \sstsubsection{
         val
      }{
         This argument should have the same type as the elements of
         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag the
         masked data (see
         \texttt{"} inside\texttt{"} ).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMask$<$X$>$()
      }{
         The number of pixels to which a value of
         \texttt{"} badval\texttt{"}
         has been assigned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero will be returned if this function is invoked
         with the global error status set, or if it should fail for any
         reason.

         \sstitem
         An error will be reported if the overlap of the Region and
         the array cannot be determined.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate masking function, you should
      replace $<$X$>$ in the generic function name astMask$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         L: long int

         \sstitem
         UL: unsigned long int

         \sstitem
         I: int

         \sstitem
         UI: unsigned int

         \sstitem
         S: short int

         \sstitem
         US: unsigned short int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astMaskD would be used to process \texttt{"} double\texttt{"}
      data, while astMaskS would be used to process \texttt{"} short int\texttt{"}
      data, etc.
   }
}
\sstroutine{
   astMatchAxes
}{
   Find any corresponding axes in two Frames
}{
   \sstdescription{
      This function looks for corresponding axes within two supplied
      Frames. An array of integers is returned that contains an element
      for each axis in the second supplied \htmlref{Frame}{Frame}. An element in this array
      will be set to zero if the associated axis within the second Frame
      has no corresponding axis within the first Frame. Otherwise, it
      will be set to the index (a non-zero positive integer) of the
      corresponding axis within the first supplied Frame.
   }
   \sstsynopsis{
      void astMatchAxes( AstFrame $*$frm1, AstFrame $*$frm2, int $*$axes )
   }
   \sstparameters{
      \sstsubsection{
         frm1
      }{
         Pointer to the first Frame.
      }
      \sstsubsection{
         frm2
      }{
         Pointer to the second Frame.
      }
      \sstsubsection{
         axes
      }{
         Pointer to an
         integer array in which to return the indices of the axes (within
         the first Frame) that correspond to each axis within the second
         Frame. \htmlref{Axis}{Axis} indices start at 1. A value of zero will be stored
         in the returned array for each axis in the second Frame that has
         no corresponding axis in the first Frame.

         The number of elements in this array must be greater than or
         equal to the number of axes in the second Frame.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         This function applies to all Frames.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Corresponding axes are identified by the fact that a \htmlref{Mapping}{Mapping} can
         be found between them using
         \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}.
         Thus, \texttt{"} corresponding axes\texttt{"}  are not necessarily identical. For
         instance, \htmlref{SkyFrame}{SkyFrame} axes in two Frames will match even if they
         describe different celestial coordinate systems
      }
   }
}
\sstroutine{
   astMathMap
}{
   Create a MathMap
}{
   \sstdescription{
      This function creates a new \htmlref{MathMap}{MathMap} and optionally initialises its
      attributes.

      A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward
      and/or inverse transformation functions using arithmetic operations
      and mathematical functions similar to those available in C. The
      MathMap interprets these functions at run-time, whenever its forward
      or inverse transformation is required. Because the functions are not
      compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to
      describe coordinate transformations in a transportable manner. A
      MathMap therefore provides a flexible way of defining new types of
      Mapping whose descriptions may be stored as part of a dataset and
      interpreted by other programs.
   }
   \sstsynopsis{
      AstMathMap $*$astMathMap( int nin, int nout,
                              int nfwd, const char $*$fwd[],
                              int ninv, const char $*$inv[],
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nin
      }{
         Number of input variables for the MathMap. This determines the
         value of its \htmlref{Nin}{Nin} attribute.
      }
      \sstsubsection{
         nout
      }{
         Number of output variables for the MathMap. This determines the
         value of its \htmlref{Nout}{Nout} attribute.
      }
      \sstsubsection{
         nfwd
      }{
         The number of forward transformation functions being supplied.
         This must be at least equal to \texttt{"} nout\texttt{"} , but may be increased to
         accommodate any additional expressions which define intermediate
         variables for the forward transformation (see the \texttt{"} Calculating
         Intermediate Values\texttt{"}  section below).
      }
      \sstsubsection{
         fwd
      }{
         An array (with \texttt{"} nfwd\texttt{"}  elements) of pointers to null terminated strings
         which contain the expressions defining the forward transformation.
         The syntax of these expressions is described below.
      }
      \sstsubsection{
         ninv
      }{
         The number of inverse transformation functions being supplied.
         This must be at least equal to \texttt{"} nin\texttt{"} , but may be increased to
         accommodate any additional expressions which define intermediate
         variables for the inverse transformation (see the \texttt{"} Calculating
         Intermediate Values\texttt{"}  section below).
      }
      \sstsubsection{
         inv
      }{
         An array (with \texttt{"} ninv\texttt{"}  elements) of pointers to null terminated strings
         which contain the expressions defining the inverse transformation.
         The syntax of these expressions is described below.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new MathMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMathMap()
      }{
         A pointer to the new MathMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The sequence of numbers produced by the random number functions
         available within a MathMap is normally unpredictable and different for
         each MathMap. However, this behaviour may be controlled by means of
         the MathMap\texttt{'} s \htmlref{Seed}{Seed} attribute.

         \sstitem
         Normally, compound Mappings (CmpMaps) which involve MathMaps will
         not be subject to simplification (e.g. using \htmlref{astSimplify}{astSimplify}) because AST
         cannot know how different MathMaps will interact. However, in the
         special case where a MathMap occurs in series with its own inverse,
         then simplification may be possible. Whether simplification does, in
         fact, occur under these circumstances is controlled by the MathMap\texttt{'} s
         \htmlref{SimpFI}{SimpFI} and \htmlref{SimpIF}{SimpIF} attributes.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Defining Transformation Functions
   }{
      A MathMap\texttt{'} s transformation functions are supplied as a set of
      expressions in an array of character strings. Normally you would
      supply the same number of expressions for the forward transformation,
      via the \texttt{"} fwd\texttt{"}  parameter, as there are output variables (given by the
      MathMap\texttt{'} s Nout attribute). For instance, if Nout is 2 you might use:
      \sstitemlist{

         \sstitem
         \texttt{"} r = sqrt( x $*$ x $+$ y $*$ y )\texttt{"}

         \sstitem
         \texttt{"} theta = atan2( y, x )\texttt{"}

      }
      which defines a transformation from Cartesian to polar
      coordinates. Here, the variables that appear on the left of each
      expression (\texttt{"} r\texttt{"}  and \texttt{"} theta\texttt{"} ) provide names for the output variables
      and those that appear on the right (\texttt{"} x\texttt{"}  and \texttt{"} y\texttt{"} ) are references to
      input variables.

      To complement this, you must also supply expressions for the inverse
      transformation via the \texttt{"} inv\texttt{"}  parameter.  In this case, the number of
      expressions given would normally match the number of MathMap input
      coordinates (given by the Nin attribute).  If Nin is 2, you might use:
      \sstitemlist{

         \sstitem
         \texttt{"} x = r $*$ cos( theta )\texttt{"}

         \sstitem
         \texttt{"} y = r $*$ sin( theta )\texttt{"}

      }
      which expresses the transformation from polar to Cartesian
      coordinates. Note that here the input variables (\texttt{"} x\texttt{"}  and \texttt{"} y\texttt{"} ) are
      named on the left of each expression, and the output variables (\texttt{"} r\texttt{"}
      and \texttt{"} theta\texttt{"} ) are referenced on the right.

      Normally, you cannot refer to a variable on the right of an expression
      unless it is named on the left of an expression in the complementary
      set of functions. Therefore both sets of functions (forward and
      inverse) must be formulated using the same consistent set of variable
      names. This means that if you wish to leave one of the transformations
      undefined, you must supply dummy expressions which simply name each of
      the output (or input) variables.  For example, you might use:
      \sstitemlist{

         \sstitem
         \texttt{"} x\texttt{"}

         \sstitem
         \texttt{"} y\texttt{"}

      }
      for the inverse transformation above, which serves to name the input
      variables but without defining an inverse transformation.
   }
   \sstdiytopic{
      Calculating Intermediate Values
   }{
      It is sometimes useful to calculate intermediate values and then to
      use these in the final expressions for the output (or input)
      variables. This may be done by supplying additional expressions for
      the forward (or inverse) transformation functions. For instance, the
      following array of five expressions describes 2-dimensional pin-cushion
      distortion:
      \sstitemlist{

         \sstitem
         \texttt{"} r = sqrt( xin $*$ xin $+$ yin $*$ yin )\texttt{"}

         \sstitem
         \texttt{"} rout = r $*$ ( 1 $+$ 0.1 $*$ r $*$ r )\texttt{"}

         \sstitem
         \texttt{"} theta = atan2( yin, xin )\texttt{"}

         \sstitem
         \texttt{"} xout = rout $*$ cos( theta )\texttt{"}

         \sstitem
         \texttt{"} yout = rout $*$ sin( theta )\texttt{"}

      }
      Here, we first calculate three intermediate results (\texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"}
      and \texttt{"} theta\texttt{"} ) and then use these to calculate the final results (\texttt{"} xout\texttt{"}
      and \texttt{"} yout\texttt{"} ). The MathMap knows that only the final two results
      constitute values for the output variables because its Nout attribute
      is set to 2. You may define as many intermediate variables in this
      way as you choose. Having defined a variable, you may then refer to it
      on the right of any subsequent expressions.

      Note that when defining the inverse transformation you may only refer
      to the output variables \texttt{"} xout\texttt{"}  and \texttt{"} yout\texttt{"} .  The intermediate variables
      \texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"}  and \texttt{"} theta\texttt{"}  (above) are private to the forward
      transformation and may not be referenced by the inverse
      transformation. The inverse transformation may, however, define its
      own private intermediate variables.
   }
   \sstdiytopic{
      Expression Syntax
   }{
      The expressions given for the forward and inverse transformations
      closely follow the syntax of the C programming language (with some
      extensions for compatibility with Fortran). They may contain
      references to variables and literal constants, together with
      arithmetic, boolean, relational and bitwise operators, and function
      invocations. A set of symbolic constants is also available. Each of
      these is described in detail below. Parentheses may be used to
      over-ride the normal order of evaluation. There is no built-in limit
      to the length of expressions and they are insensitive to case or the
      presence of additional white space.
   }
   \sstdiytopic{
      Variables
   }{
      Variable names must begin with an alphabetic character and may contain
      only alphabetic characters, digits, and the underscore character
      \texttt{"} \_\texttt{"} . There is no built-in limit to the length of variable names.
   }
   \sstdiytopic{
      Literal Constants
   }{
      Literal constants, such as \texttt{"} 0\texttt{"} , \texttt{"} 1\texttt{"} , \texttt{"} 0.007\texttt{"}  or \texttt{"} 2.505e-16\texttt{"}  may appear
      in expressions, with the decimal point and exponent being optional (a
      \texttt{"} D\texttt{"}  may also be used as an exponent character for compatibility with
      Fortran). A unary minus \texttt{"} -\texttt{"}  may be used as a prefix.
   }
   \sstdiytopic{
      Arithmetic Precision
   }{
      All arithmetic is floating point, performed in double precision.
   }
   \sstdiytopic{
      Propagation of Missing Data
   }{
      Unless indicated otherwise, if any argument of a function or operator
      has the value AST\_\_BAD (indicating missing data), then the result of
      that function or operation is also AST\_\_BAD, so that such values are
      propagated automatically through all operations performed by MathMap
      transformations.  The special value AST\_\_BAD can be represented in
      expressions by the symbolic constant \texttt{"} $<$bad$>$\texttt{"} .

      A $<$bad$>$ result (i.e. equal to AST\_\_BAD) is also produced in response
      to any numerical error (such as division by zero or numerical
      overflow), or if an invalid argument value is provided to a function
      or operator.
   }
   \sstdiytopic{
      Arithmetic Operators
   }{
      The following arithmetic operators are available:
      \sstitemlist{

         \sstitem
         x1 $+$ x2: Sum of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .

         \sstitem
         x1 - x2: Difference of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .

         \sstitem
         x1 $*$ x2: Product of \texttt{"} x1\texttt{"}  and \texttt{"} x1\texttt{"} .

         \sstitem
         x1 / x2: Ratio of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .

         \sstitem
         x1 $*$$*$ x2: \texttt{"} x1\texttt{"}  raised to the power of \texttt{"} x2\texttt{"} .

         \sstitem
         $+$ x: Unary plus, has no effect on its argument.

         \sstitem
         - x: Unary minus, negates its argument.
      }
   }
   \sstdiytopic{
      Boolean Operators
   }{
      Boolean values are represented using zero to indicate false and
      non-zero to indicate true. In addition, the value AST\_\_BAD is taken to
      mean \texttt{"} unknown\texttt{"} . The values returned by boolean operators may therefore
      be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"}  logic is
      implemented. For example, \texttt{"} a$|$$|$b\texttt{"}  may evaluate to 1 if \texttt{"} a\texttt{"}  is non-zero,
      even if \texttt{"} b\texttt{"}  has the value AST\_\_BAD. This is because the result of the
      operation would not be affected by the value of \texttt{"} b\texttt{"} , so long as \texttt{"} a\texttt{"}  is
      non-zero.

      The following boolean operators are available:
      \sstitemlist{

         \sstitem
         x1 \&\& x2: Boolean AND between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning 1 if both \texttt{"} x1\texttt{"}
         and \texttt{"} x2\texttt{"}  are non-zero, and 0 otherwise. This operator implements
         tri-state logic. (The synonym \texttt{"} .and.\texttt{"}  is also provided for compatibility
         with Fortran.)

         \sstitem
         x1 $|$$|$ x2: Boolean OR between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning 1 if either \texttt{"} x1\texttt{"}
         or \texttt{"} x2\texttt{"}  are non-zero, and 0 otherwise. This operator implements
         tri-state logic. (The synonym \texttt{"} .or.\texttt{"}  is also provided for compatibility
         with Fortran.)

         \sstitem
         x1 $\wedge$$\wedge$ x2: Boolean exclusive OR (XOR) between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning
         1 if exactly one of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"}  is non-zero, and 0 otherwise. Tri-state
         logic is not used with this operator. (The synonyms \texttt{"} .neqv.\texttt{"}  and \texttt{"} .xor.\texttt{"}
         are also provided for compatibility with Fortran, although the second
         of these is not standard.)

         \sstitem
         x1 .eqv. x2: This is provided only for compatibility with Fortran
         and tests whether the boolean states of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"}  (i.e. true/false)
         are equal. It is the negative of the exclusive OR (XOR) function.
         Tri-state logic is not used with this operator.

         \sstitem
         ! x: Boolean unary NOT operation, returning 1 if \texttt{"} x\texttt{"}  is zero, and
         0 otherwise. (The synonym \texttt{"} .not.\texttt{"}  is also provided for compatibility
         with Fortran.)
      }
   }
   \sstdiytopic{
      Relational Operators
   }{
      Relational operators return the boolean result (0 or 1) of comparing
      the values of two floating point values for equality or inequality. The
      value AST\_\_BAD may also be returned if either argument is $<$bad$>$.

      The following relational operators are available:
      \sstitemlist{

         \sstitem
         x1 == x2: Tests whether \texttt{"} x1\texttt{"}  equals \texttt{"} x1\texttt{"} . (The synonym \texttt{"} .eq.\texttt{"}  is
         also provided for compatibility with Fortran.)

         \sstitem
         x1 != x2: Tests whether \texttt{"} x1\texttt{"}  is unequal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .ne.\texttt{"}
         is also provided for compatibility with Fortran.)

         \sstitem
         x1 $>$ x2: Tests whether \texttt{"} x1\texttt{"}  is greater than \texttt{"} x2\texttt{"} . (The synonym
         \texttt{"} .gt.\texttt{"}  is also provided for compatibility with Fortran.)

         \sstitem
         x1 $>$= x2: Tests whether \texttt{"} x1\texttt{"}  is greater than or equal to \texttt{"} x2\texttt{"} . (The
         synonym \texttt{"} .ge.\texttt{"}   is also provided for compatibility with Fortran.)

         \sstitem
         x1 $<$ x2: Tests whether \texttt{"} x1\texttt{"}  is less than \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .lt.\texttt{"}
         is also provided for compatibility with Fortran.)

         \sstitem
         x1 $<$= x2: Tests whether \texttt{"} x1\texttt{"}  is less than or equal to \texttt{"} x2\texttt{"} . (The
         synonym \texttt{"} .le.\texttt{"}  is also provided for compatibility with Fortran.)

      }
      Note that relational operators cannot usefully be used to compare
      values with the $<$bad$>$ value (representing missing data), because the
      result is always $<$bad$>$. The isbad() function should be used instead.
   }
   \sstdiytopic{
      Bitwise Operators
   }{
      The bitwise operators provided by C are often useful when operating on
      raw data (e.g. from instruments), so they are also provided for use in
      MathMap expressions. In this case, however, the values on which they
      operate are floating point values rather than pure integers. In order
      to produce results which match the pure integer case, the operands are
      regarded as fixed point binary numbers (i.e. with the binary
      equivalent of a decimal point) with negative numbers represented using
      twos-complement notation. For integer values, the resulting bit
      pattern corresponds to that of the equivalent signed integer (digits
      to the right of the point being zero). Operations on the bits
      representing the fractional part are also possible, however.

      The following bitwise operators are available:
      \sstitemlist{

         \sstitem
         x1 $>$$>$ x2: Rightward bit shift. The integer value of \texttt{"} x2\texttt{"}  is taken
         (rounding towards zero) and the bits representing \texttt{"} x1\texttt{"}  are then
         shifted this number of places to the right (or to the left if the
         number of places is negative). This is equivalent to dividing \texttt{"} x1\texttt{"}  by
         the corresponding power of 2.

         \sstitem
         x1 $<$$<$ x2: Leftward bit shift. The integer value of \texttt{"} x2\texttt{"}  is taken
         (rounding towards zero), and the bits representing \texttt{"} x1\texttt{"}  are then
         shifted this number of places to the left (or to the right if the
         number of places is negative). This is equivalent to multiplying \texttt{"} x1\texttt{"}
         by the corresponding power of 2.

         \sstitem
         x1 \& x2: Bitwise AND between the bits of \texttt{"} x1\texttt{"}  and those of \texttt{"} x2\texttt{"}
         (equivalent to a boolean AND applied at each bit position in turn).

         \sstitem
         x1 $|$ x2: Bitwise OR between the bits of \texttt{"} x1\texttt{"}  and those of \texttt{"} x2\texttt{"}
         (equivalent to a boolean OR applied at each bit position in turn).

         \sstitem
         x1 $\wedge$ x2: Bitwise exclusive OR (XOR) between the bits of \texttt{"} x1\texttt{"}  and
         those of \texttt{"} x2\texttt{"}  (equivalent to a boolean XOR applied at each bit
         position in turn).

      }
      Note that no bit inversion operator (\texttt{"} $\sim$\texttt{"}  in C) is provided. This is
      because inverting the bits of a twos-complement fixed point binary
      number is equivalent to simply negating it. This differs from the
      pure integer case because bits to the right of the binary point are
      also inverted. To invert only those bits to the left of the binary
      point, use a bitwise exclusive OR with the value -1 (i.e. \texttt{"} x$\wedge$-1\texttt{"} ).
   }
   \sstdiytopic{
      Functions
   }{
      The following functions are available:
      \sstitemlist{

         \sstitem
         abs(x): Absolute value of \texttt{"} x\texttt{"}  (sign removal), same as fabs(x).

         \sstitem
         acos(x): Inverse cosine of \texttt{"} x\texttt{"} , in radians.

         \sstitem
         acosd(x): Inverse cosine of \texttt{"} x\texttt{"} , in degrees.

         \sstitem
         acosh(x): Inverse hyperbolic cosine of \texttt{"} x\texttt{"} .

         \sstitem
         acoth(x): Inverse hyperbolic cotangent of \texttt{"} x\texttt{"} .

         \sstitem
         acsch(x): Inverse hyperbolic cosecant of \texttt{"} x\texttt{"} .

         \sstitem
         aint(x): Integer part of \texttt{"} x\texttt{"}  (round towards zero), same as int(x).

         \sstitem
         asech(x): Inverse hyperbolic secant of \texttt{"} x\texttt{"} .

         \sstitem
         asin(x): Inverse sine of \texttt{"} x\texttt{"} , in radians.

         \sstitem
         asind(x): Inverse sine of \texttt{"} x\texttt{"} , in degrees.

         \sstitem
         asinh(x): Inverse hyperbolic sine of \texttt{"} x\texttt{"} .

         \sstitem
         atan(x): Inverse tangent of \texttt{"} x\texttt{"} , in radians.

         \sstitem
         atand(x): Inverse tangent of \texttt{"} x\texttt{"} , in degrees.

         \sstitem
         atanh(x): Inverse hyperbolic tangent of \texttt{"} x\texttt{"} .

         \sstitem
         atan2(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in radians.

         \sstitem
         atan2d(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in degrees.

         \sstitem
         ceil(x): Smallest integer value not less then \texttt{"} x\texttt{"}  (round towards
           plus infinity).

         \sstitem
         cos(x): Cosine of \texttt{"} x\texttt{"}  in radians.

         \sstitem
         cosd(x): Cosine of \texttt{"} x\texttt{"}  in degrees.

         \sstitem
         cosh(x): Hyperbolic cosine of \texttt{"} x\texttt{"} .

         \sstitem
         coth(x): Hyperbolic cotangent of \texttt{"} x\texttt{"} .

         \sstitem
         csch(x): Hyperbolic cosecant of \texttt{"} x\texttt{"} .

         \sstitem
         dim(x1, x2): Returns \texttt{"} x1-x2\texttt{"}  if \texttt{"} x1\texttt{"}  is greater than \texttt{"} x2\texttt{"} , otherwise 0.

         \sstitem
         exp(x): Exponential function of \texttt{"} x\texttt{"} .

         \sstitem
         fabs(x): Absolute value of \texttt{"} x\texttt{"}  (sign removal), same as abs(x).

         \sstitem
         floor(x): Largest integer not greater than \texttt{"} x\texttt{"}  (round towards
           minus infinity).

         \sstitem
         fmod(x1, x2): Remainder when \texttt{"} x1\texttt{"}  is divided by \texttt{"} x2\texttt{"} , same as
           mod(x1, x2).

         \sstitem
         gauss(x1, x2): Random sample from a Gaussian distribution with mean
           \texttt{"} x1\texttt{"}  and standard deviation \texttt{"} x2\texttt{"} .

         \sstitem
         int(x): Integer part of \texttt{"} x\texttt{"}  (round towards zero), same as aint(x).

         \sstitem
         isbad(x): Returns 1 if \texttt{"} x\texttt{"}  has the $<$bad$>$ value (AST\_\_BAD), otherwise 0.

         \sstitem
         log(x): Natural logarithm of \texttt{"} x\texttt{"} .

         \sstitem
         log10(x): Logarithm of \texttt{"} x\texttt{"}  to base 10.

         \sstitem
         max(x1, x2, ...): Maximum of two or more values.

         \sstitem
         min(x1, x2, ...): Minimum of two or more values.

         \sstitem
         mod(x1, x2): Remainder when \texttt{"} x1\texttt{"}  is divided by \texttt{"} x2\texttt{"} , same as
           fmod(x1, x2).

         \sstitem
         nint(x): Nearest integer to \texttt{"} x\texttt{"}  (round to nearest).

         \sstitem
         poisson(x): Random integer-valued sample from a Poisson
           distribution with mean \texttt{"} x\texttt{"} .

         \sstitem
         pow(x1, x2): \texttt{"} x1\texttt{"}  raised to the power of \texttt{"} x2\texttt{"} .

         \sstitem
         qif(x1, x2, x3): Returns \texttt{"} x2\texttt{"}  if \texttt{"} x1\texttt{"}  is true, and \texttt{"} x3\texttt{"}  otherwise.

         \sstitem
         rand(x1, x2): Random sample from a uniform distribution in the
           range \texttt{"} x1\texttt{"}  to \texttt{"} x2\texttt{"}  inclusive.

         \sstitem
         sech(x): Hyperbolic secant of \texttt{"} x\texttt{"} .

         \sstitem
         sign(x1, x2): Absolute value of \texttt{"} x1\texttt{"}  with the sign of \texttt{"} x2\texttt{"}
           (transfer of sign).

         \sstitem
         sin(x): Sine of \texttt{"} x\texttt{"}  in radians.

         \sstitem
         sinc(x): Sinc function of \texttt{"} x\texttt{"}  [= \texttt{"} sin(x)/x\texttt{"} ].

         \sstitem
         sind(x): Sine of \texttt{"} x\texttt{"}  in degrees.

         \sstitem
         sinh(x): Hyperbolic sine of \texttt{"} x\texttt{"} .

         \sstitem
         sqr(x): Square of \texttt{"} x\texttt{"}  (= \texttt{"} x$*$x\texttt{"} ).

         \sstitem
         sqrt(x): Square root of \texttt{"} x\texttt{"} .

         \sstitem
         tan(x): Tangent of \texttt{"} x\texttt{"}  in radians.

         \sstitem
         tand(x): Tangent of \texttt{"} x\texttt{"}  in degrees.

         \sstitem
         tanh(x): Hyperbolic tangent of \texttt{"} x\texttt{"} .
      }
   }
   \sstdiytopic{
      Symbolic Constants
   }{
      The following symbolic constants are available (the enclosing \texttt{"} $<$$>$\texttt{"}
      brackets must be included):
      \sstitemlist{

         \sstitem
         $<$bad$>$: The \texttt{"} bad\texttt{"}  value (AST\_\_BAD) used to flag missing data. Note
         that you cannot usefully compare values with this constant because the
         result is always $<$bad$>$. The isbad() function should be used instead.

         \sstitem
         $<$dig$>$: Number of decimal digits of precision available in a
         floating point (double) value.

         \sstitem
         $<$e$>$: \htmlref{Base}{Base} of natural logarithms.

         \sstitem
         $<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is
         distinguishable from unity.

         \sstitem
         $<$mant\_dig$>$: The number of base $<$radix$>$ digits stored in the
         mantissa of a floating point (double) value.

         \sstitem
         $<$max$>$: Maximum representable floating point (double) value.

         \sstitem
         $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power
         can be represented as a floating point (double) value.

         \sstitem
         $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that
         power minus 1 can be represented as a floating point (double) value.

         \sstitem
         $<$min$>$: Smallest positive number which can be represented as a
         normalised floating point (double) value.

         \sstitem
         $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that
         power can be represented as a normalised floating point (double) value.

         \sstitem
         $<$min\_exp$>$: Minimum negative integer such that $<$radix$>$ raised to
         that power minus 1 can be represented as a normalised floating point
         (double) value.

         \sstitem
         $<$pi$>$: Ratio of the circumference of a circle to its diameter.

         \sstitem
         $<$radix$>$: The radix (number base) used to represent the mantissa of
         floating point (double) values.

         \sstitem
         $<$rounds$>$: The mode used for rounding floating point results after
         addition. Possible values include: -1 (indeterminate), 0 (toward
         zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus
         infinity). Other values indicate machine-dependent behaviour.
      }
   }
   \sstdiytopic{
      Evaluation Precedence and Associativity
   }{
      Items appearing in expressions are evaluated in the following order
      (highest precedence first):
      \sstitemlist{

         \sstitem
         Constants and variables

         \sstitem
         Function arguments and parenthesised expressions

         \sstitem
         Function invocations

         \sstitem
         Unary $+$ - ! .not.

         \sstitem
         $*$$*$

         \sstitem
         $*$ /

         \sstitem
         $+$ -

         \sstitem
         $<$$<$ $>$$>$

         \sstitem
         $<$ .lt. $<$= .le. $>$ .gt. $>$= .ge.

         \sstitem
         == .eq. != .ne.

         \sstitem
         \&

         \sstitem
         $\wedge$

         \sstitem
         $|$

         \sstitem
         \&\& .and.

         \sstitem
         $\wedge$$\wedge$

         \sstitem
         $|$$|$ .or

         \sstitem
         .eqv. .neqv. .xor.

      }
      All operators associate from left-to-right, except for unary $+$,
      unary -, !, .not. and $*$$*$ which associate from right-to-left.
   }
}
\sstroutine{
   astMatrixMap
}{
   Create a MatrixMap
}{
   \sstdescription{
      This function creates a new \htmlref{MatrixMap}{MatrixMap} and optionally initialises
      its attributes.

      A MatrixMap is a form of \htmlref{Mapping}{Mapping} which performs a general linear
      transformation.  Each set of input coordinates, regarded as a
      column-vector, are pre-multiplied by a matrix (whose elements
      are specified when the MatrixMap is created) to give a new
      column-vector containing the output coordinates. If appropriate,
      the inverse transformation may also be performed.
   }
   \sstsynopsis{
      AstMatrixMap $*$astMatrixMap( int nin, int nout, int form,
                                  const double matrix[],
                                  const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nin
      }{
         The number of input coordinates, which determines the number
         of columns in the matrix.
      }
      \sstsubsection{
         nout
      }{
         The number of output coordinates, which determines the number
         of rows in the matrix.
      }
      \sstsubsection{
         form
      }{
         An integer which indicates the form in which the matrix
         elements will be supplied.

         A value of zero indicates that a full \texttt{"} nout\texttt{"}  x \texttt{"} nin\texttt{"}  matrix
         of values will be supplied via the \texttt{"} matrix\texttt{"}  parameter
         (below). In this case, the elements should be given in row
         order (the elements of the first row, followed by the
         elements of the second row, etc.).

         A value of 1 indicates that only the diagonal elements of the
         matrix will be supplied, and that all others should be
         zero. In this case, the elements of \texttt{"} matrix\texttt{"}  should contain
         only the diagonal elements, stored consecutively.

         A value of 2 indicates that a \texttt{"} unit\texttt{"}  matrix is required,
         whose diagonal elements are set to unity (with all other
         elements zero).  In this case, the \texttt{"} matrix\texttt{"}  parameter is
         ignored and a NULL pointer may be supplied.
      }
      \sstsubsection{
         matrix
      }{
         The array of matrix elements to be used, stored according to
         the value of \texttt{"} form\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new MatrixMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMatrixMap()
      }{
         A pointer to the new MatrixMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         In general, a MatrixMap\texttt{'} s forward transformation will always
         be available (as indicated by its \htmlref{TranForward}{TranForward} attribute), but
         its inverse transformation (\htmlref{TranInverse}{TranInverse} attribute) will only be
         available if the associated matrix is square and non-singular.

         \sstitem
         As an exception to this, the inverse transformation is always
         available if a unit or diagonal matrix is specified. In this
         case, if the matrix is not square, one or more of the input
         coordinate values may not be recoverable from a set of output
         coordinates. Any coordinates affected in this way will simply be
         set to the value zero.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astMirrorVariants
}{
   Make the current Frame mirror the variant Mappings in another Frame
}{
   \sstdescription{
      This function
      indicates that all access to the \htmlref{Variant}{Variant} attribute of the current
      \htmlref{Frame}{Frame} should should be forwarded to some other nominated Frame in
      the \htmlref{FrameSet}{FrameSet}. For instance, if a value is set subsequently for the
      Variant attribute of the current Frame, the current Frame will be left
      unchanged and the setting is instead applied to the nominated Frame.
      Likewise, if the value of the Variant attribute is requested, the
      value returned is the value stored for the nominated Frame rather
      than the current Frame itself.

      This provides a mechanism for propagating the effects of variant
      Mappings around a FrameSet. If a new Frame is added to a FrameSet
      by connecting it to an pre-existing Frame that has two or more variant
      Mappings, then it may be appropriate to set the new Frame so that it
      mirrors the variants Mappings of the pre-existing Frame. If this is
      done, then it will be possible to select a specific variant \htmlref{Mapping}{Mapping}
      using either the pre-existing Frame or the new Frame.
   }
   \sstsynopsis{
      void astMirrorVariants( AstFrameSet $*$this, int iframe, int $*$status )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe
      }{
         The index of the Frame within the FrameSet which is to be
         mirrored by the current Frame. This value should lie in the range
         from 1 to the number of Frames in the FrameSet (as given by its
         \htmlref{Nframe}{Nframe} attribute). If AST\_\_NOFRAME is supplied (or the current
         Frame is specified), then any mirroring established by a previous
         call to this
         function
         is disabled.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Mirrors can be chained. That is, if Frame B is set to be a mirror
         of Frame A, and Frame C is set to be a mirror of Frame B, then
         Frame C will act as a mirror of Frame A.

         \sstitem
         Variant Mappings cannot be added to the current Frame if it is
         mirroring another Frame. So calls to the
         \htmlref{astAddVariant}{astAddVariant} function
         will cause an error to be reported if the current Frame is
         mirroring another Frame.

         \sstitem
         A value of AST\_\_BASE may be given for the
         \texttt{"} iframe\texttt{"}  parameter
         to specify the base Frame.

         \sstitem
         Any variant Mappings explicitly added to the current Frame using
         astAddVariant
         will be ignored if the current Frame is mirroring another Frame.
      }
   }
}
\sstroutine{
   astNegate
}{
   Negate the area represented by a Region
}{
   \sstdescription{
      This function negates the area represented by a \htmlref{Region}{Region}. That is,
      points which were previously inside the region will then be
      outside, and points which were outside will be inside. This is
      acomplished by toggling the state of the \htmlref{Negated}{Negated} attribute for
      the supplied region.
   }
   \sstsynopsis{
      void astNegate( AstRegion $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
   }
}
\sstroutine{
   astNorm
}{
   Normalise a set of Frame coordinates
}{
   \sstdescription{
      This function normalises a set of \htmlref{Frame}{Frame} coordinate values which
      might be unsuitable for display (e.g. may lie outside the
      expected range) into a set of acceptable values suitable for
      display.
   }
   \sstsynopsis{
      void astNorm( AstFrame $*$this, double value[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         value
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). Initially, this should contain a set of
         coordinate values representing a point in the space which the
         Frame describes. If these values lie outside the expected
         range for the Frame, they will be replaced with more
         acceptable (normalised) values. Otherwise, they will be
         returned unchanged.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For some classes of Frame, whose coordinate values are not
         constrained, this function will never modify the values
         supplied. However, for Frames whose axes represent cyclic
         quantities (such as angles or positions on the sky), coordinates
         will typically be wrapped into an appropriate standard range,
         such as zero to 2$*$pi.

         \sstitem
         The \htmlref{NormMap}{NormMap} class is a \htmlref{Mapping}{Mapping} which can be used to normalise a
         set of points using the
         astNorm function
         of a specified Frame.

         \sstitem
         It is intended to be possible to put any set of coordinates
         into a form suitable for display by using this function to
         normalise them, followed by appropriate formatting
         (using \htmlref{astFormat}{astFormat}).
      }
   }
}
\sstroutine{
   astNormMap
}{
   Create a NormMap
}{
   \sstdescription{
      This function creates a new \htmlref{NormMap}{NormMap} and optionally initialises its
      attributes.

      A NormMap is a \htmlref{Mapping}{Mapping} which normalises coordinate values using the
      \htmlref{astNorm}{astNorm} function
      of the supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap
      are both equal to the number of axes in the supplied Frame.

      The forward and inverse transformation of a NormMap are both
      defined but are identical (that is, they do not form a real inverse
      pair in that the inverse transformation does not undo the
      normalisation, instead it reapplies it). However, the
      \htmlref{astSimplify}{astSimplify}
      function will replace neighbouring pairs of forward and inverse
      NormMaps by a single \htmlref{UnitMap}{UnitMap}.
   }
   \sstsynopsis{
      AstNormMap $*$astNormMap( AstFrame $*$frame, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame which is to be used to normalise the
         supplied axis values.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new NormMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astNormMap()
      }{
         A pointer to the new NormMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astNullRegion
}{
   Create a NullRegion
}{
   \sstdescription{
      This function creates a new \htmlref{NullRegion}{NullRegion} and optionally initialises its
      attributes.

      A NullRegion is a \htmlref{Region}{Region} with no bounds. If the \htmlref{Negated}{Negated} attribute of a
      NullRegion is false, the NullRegion represents a Region containing no
      points. If the Negated attribute of a NullRegion is true, the NullRegion
      represents an infinite Region containing all points within the
      coordinate system.
   }
   \sstsynopsis{
      AstNullRegion $*$astNullRegion( AstFrame $*$frame, AstRegion $*$unc, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the \htmlref{Frame}{Frame} in which the region is defined. A deep
         copy is taken of the supplied Frame. This means that any
         subsequent changes made to the Frame using the supplied pointer
         will have no effect the Region.
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with positions in the supplied Frame.
         The uncertainty in any point in the Frame is found by shifting the
         supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the point
         being considered. The area covered by the shifted uncertainty
         Region then represents the uncertainty in the position. The
         uncertainty is assumed to be the same for all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created NullRegion. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty of zero is
         used.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new NullRegion. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astNullRegion()
      }{
         A pointer to the new NullRegion.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astOK
}{
   Test whether AST functions have been successful
}{
   \sstdescription{
      This macro returns a boolean value (0 or 1) to indicate if
      preceding AST functions have completed successfully
      (i.e. without setting the AST error status). If the error status
      is set to an error value, a value of zero is returned, otherwise
      the result is one.
   }
   \sstsynopsis{
      int astOK
   }
   \sstreturnedvalue{
      \sstsubsection{
         astOK
      }{
         One if the AST error status is OK, otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the AST error status is set to an error value (after an
         error), most AST functions will not execute and will simply
         return without action. To clear the error status and restore
         normal behaviour, use \htmlref{astClearStatus}{astClearStatus}.
      }
   }
}
\sstroutine{
   astOffset
}{
   Calculate an offset along a geodesic curve
}{
   \sstdescription{
      This function finds the \htmlref{Frame}{Frame} coordinate values of a point which
      is offset a specified distance along the geodesic curve between
      two other points.

      For example, in a basic Frame, this offset will be along the
      straight line joining two points. For a more specialised Frame
      describing a sky coordinate system, however, it would be along
      the great circle passing through two sky positions.
   }
   \sstsynopsis{
      void astOffset( AstFrame $*$this,
                      const double point1[], const double point2[],
                      double offset, double point3[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         point1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
         point marking the start of the geodesic curve.
      }
      \sstsubsection{
         point2
      }{
         An array of double, with one element for each Frame axis
         This should contain the coordinates of the point marking the
         end of the geodesic curve.
      }
      \sstsubsection{
         offset
      }{
         The required offset from the first point along the geodesic
         curve. If this is positive, it will be towards the second
         point. If it is negative, it will be in the opposite
         direction. This offset need not imply a position lying
         between the two points given, as the curve will be
         extrapolated if necessary.
      }
      \sstsubsection{
         point3
      }{
         An array of double, with one element for each Frame axis
         in which the coordinates of the required point will be returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The geodesic curve used by this function is the path of
         shortest distance between two points, as defined by the
         \htmlref{astDistance}{astDistance} function.

         \sstitem
         This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
         if any of the input coordinates has this value.

         \sstitem
         \texttt{"} Bad\texttt{"}  coordinate values will also be returned if the two
         points supplied are coincident (or otherwise fail to uniquely
         specify a geodesic curve) but the requested offset is non-zero.
      }
   }
}
\sstroutine{
   astOffset2
}{
   Calculate an offset along a geodesic curve in a 2D Frame
}{
   \sstdescription{
      This function finds the \htmlref{Frame}{Frame} coordinate values of a point which
      is offset a specified distance along the geodesic curve at a
      given angle from a specified starting point. It can only be
      used with 2-dimensional Frames.

      For example, in a basic Frame, this offset will be along the
      straight line joining two points. For a more specialised Frame
      describing a sky coordinate system, however, it would be along
      the great circle passing through two sky positions.
   }
   \sstsynopsis{
      double astOffset2( AstFrame $*$this, const double point1[2], double angle,
                         double offset, double point2[2] );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         point1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
         point marking the start of the geodesic curve.
      }
      \sstsubsection{
         angle
      }{
         The angle (in radians) from the positive direction of the second
         axis, to the direction of the required position, as seen from
         the starting position. Positive rotation is in the sense of
         rotation from the positive direction of axis 2 to the positive
         direction of axis 1.
      }
      \sstsubsection{
         offset
      }{
         The required offset from the first point along the geodesic
         curve. If this is positive, it will be in the direction of the
         given angle. If it is negative, it will be in the opposite
         direction.
      }
      \sstsubsection{
         point2
      }{
         An array of double, with one element for each Frame axis
         in which the coordinates of the required point will be returned.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astOffset2
      }{
         The direction of the geodesic curve at the end point. That is, the
         angle (in radians) between the positive direction of the second
         axis and the continuation of the geodesic curve at the requested
         end point. Positive rotation is in the sense of rotation from
         the positive direction of axis 2 to the positive direction of axis
         1.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The geodesic curve used by this function is the path of
         shortest distance between two points, as defined by the
         \htmlref{astDistance}{astDistance} function.

         \sstitem
         An error will be reported if the Frame is not 2-dimensional.

         \sstitem
         This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
         if any of the input coordinates has this value.
      }
   }
}
\sstroutine{
   astOutline$<$X$>$
}{
   Create a new Polygon outling values in a 2D data grid
}{
   \sstdescription{
      This is a set of functions that create a \htmlref{Polygon}{Polygon} enclosing a single
      contiguous set of pixels that have a specified value within a gridded
      2-dimensional data array (e.g. an image).

      A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate
      system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to
      \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the
      Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other
      attributes are left unset. The nature of the pixel coordinate system
      is determined by parameter
      \texttt{"} starpix\texttt{"} .

      The
      \texttt{"} maxerr\texttt{"}  and \texttt{"} maxvert\texttt{"}
      parameters can be used to control how accurately the returned
      Polygon represents the required region in the data array. The
      number of vertices in the returned Polygon will be the minimum
      needed to achieve the required accuracy.

      You should use a function which matches the numerical type of the
      data you are processing by replacing $<$X$>$ in the generic function
      name
      astOutline$<$X$>$
      by an appropriate 1- or 2-character type code. For example, if you
      are procesing data with type
      \texttt{"} float\texttt{"} , you should use the function astOutlineF
      (see the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
      other numerical types).
   }
   \sstsynopsis{
      AstPolygon $*$astOutline$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[],
                                 const int lbnd[2], const int ubnd[2], double maxerr,
                                 int maxvert, const int inside[2], int starpix )
   }
   \sstparameters{
      \sstsubsection{
         value
      }{
         A data value that specifies the pixels to be outlined.
      }
      \sstsubsection{
         oper
      }{
         Indicates how the
         \texttt{"} value\texttt{"}
         parameter is used to select the outlined pixels. It can
         have any of the following values:
         \sstitemlist{

            \sstitem
            AST\_\_LT: outline pixels with value less than \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_LE: outline pixels with value less than or equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_EQ: outline pixels with value equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_NE: outline pixels with value not equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_GE: outline pixels with value greater than or equal to \texttt{"} value\texttt{"} .

            \sstitem
            AST\_\_GT: outline pixels with value greater than \texttt{"} value\texttt{"} .
         }
      }
      \sstsubsection{
         array
      }{
         Pointer to a
         2-dimensional array containing the data to be processed.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astOutlineF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the second dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of two integers
         containing the pixel index of the first pixel in the input grid
         along each dimension.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of two integers
         containing the pixel index of the last pixel in the input grid
         along each dimension.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
         and size of the input pixel grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 pixels.
         For FITS images,
         the lbnd values will be 1 and the ubnd
         values will be equal to the NAXISi header values. Other
         data systems, such as the Starlink NDF system, allow an
         arbitrary pixel origin to be used (i.e. lbnd
         is not necessarily 1).

         These bounds also define the input grid\texttt{'} s floating point coordinate
         system, each pixel having unit extent along each dimension with
         integral coordinate values at its centre or upper corner, as selected
         by parameter
         \texttt{"} starpix\texttt{"} .
      }
      \sstsubsection{
         maxerr
      }{
         Together with
         \texttt{"} maxvert\texttt{"} ,
         this determines how accurately the returned Polygon represents
         the required region of the data array. It gives the target
         discrepancy between the returned Polygon and the accurate outline
         in the data array, expressed as a number of pixels. Insignificant
         vertices are removed from the accurate outline, one by one, until
         the number of vertices remaining in the returned Polygon equals
         \texttt{"} maxvert\texttt{"} ,
         or the largest discrepancy between the accurate outline and the
         returned Polygon is greater than
         \texttt{"} maxerr\texttt{"} . If \texttt{"} maxerr\texttt{"}
         is zero or less, its value is ignored and the returned Polygon will
         have the number of vertices specified by
         \texttt{"} maxvert\texttt{"} .
      }
      \sstsubsection{
         maxvert
      }{
         Together with
         \texttt{"} maxerr\texttt{"} ,
         this determines how accurately the returned Polygon represents
         the required region of the data array. It gives the maximum
         allowed number of vertices in the returned Polygon. Insignificant
         vertices are removed from the accurate outline, one by one, until
         the number of vertices remaining in the returned Polygon equals
         \texttt{"} maxvert\texttt{"} ,
         or the largest discrepancy between the accurate outline and the
         returned Polygon is greater than
         \texttt{"} maxerr\texttt{"} . If \texttt{"} maxvert\texttt{"}
         is less than 3, its value is ignored and the number of vertices in
         the returned Polygon will be the minimum needed to ensure that the
         discrepancy between the accurate outline and the returned
         Polygon is less than
         \texttt{"} maxerr\texttt{"} .
      }
      \sstsubsection{
         inside
      }{
         Pointer to an array of two integers
         containing the pixel indices of a pixel known to be inside the
         required region. This is needed because the supplied data
         array may contain several disjoint areas of pixels that satisfy
         the criterion specified by
         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} .
         In such cases, the area described by the returned Polygon will
         be the one that contains the pixel specified by
         \texttt{"} inside\texttt{"} .
         If the specified pixel is outside the bounds given by
         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} ,
         or has a value that does not meet the criterion specified by
         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} ,
         then this function will search for a suitable pixel. The search
         starts at the central pixel and proceeds in a spiral manner until
         a pixel is found that meets the specified crierion.
      }
      \sstsubsection{
         starpix
      }{
         A flag indicating the nature of the pixel coordinate system used
         to describe the vertex positions in the returned Polygon. If
         non-zero,
         the standard Starlink definition of pixel coordinate is used in
         which a pixel with integer index I spans a range of pixel coordinate
         from (I-1) to I (i.e. pixel corners have integral pixel coordinates).
         If zero,
         the definition of pixel coordinate used by other AST functions
         such as astResample, astMask,
         etc., is used. In this definition, a pixel with integer index I
         spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e.
         pixel centres have integral pixel coordinates).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astOutline$<$X$>$()
      }{
         A pointer to the required Polygon.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function proceeds by first finding a very accurate polygon,
         and then removing insignificant vertices from this fine polygon
         using
         \htmlref{astDownsize}{astDownsize}.

         \sstitem
         The returned Polygon is the outer boundary of the contiguous set
         of pixels that includes ths specified \texttt{"} inside\texttt{"}  point, and satisfy
         the specified value requirement. This set of pixels may potentially
         include \texttt{"} holes\texttt{"}  where the pixel values fail to meet the specified
         value requirement. Such holes will be ignored by this function.

         \sstitem
         NULL
         will be returned if this function is invoked with the global
         error status set, or if it should fail for any reason.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate masking function, you should
      replace $<$X$>$ in the generic function name astOutline$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         L: long int

         \sstitem
         UL: unsigned long int

         \sstitem
         I: int

         \sstitem
         UI: unsigned int

         \sstitem
         S: short int

         \sstitem
         US: unsigned short int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astOutlineD would be used to process \texttt{"} double\texttt{"}
      data, while astOutlineS would be used to process \texttt{"} short int\texttt{"}
      data, etc.
   }
}
\sstroutine{
   astOverlap
}{
   Test if two regions overlap each other
}{
   \sstdescription{
      This function returns an integer value indicating if the two
      supplied Regions overlap. The two Regions are converted to a commnon
      coordinate system before performing the check. If this conversion is
      not possible (for instance because the two Regions represent areas in
      different domains), then the check cannot be performed and a zero value
      is returned to indicate this.
   }
   \sstsynopsis{
      int astOverlap( AstRegion $*$this, AstRegion $*$that )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the first \htmlref{Region}{Region}.
      }
      \sstsubsection{
         that
      }{
         Pointer to the second Region.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astOverlap()
      }{
         A value indicating if there is any overlap between the two Regions.
         Possible values are:

         0 - The check could not be performed because the second Region
             could not be mapped into the coordinate system of the first
             Region.

         1 - There is no overlap between the two Regions.

         2 - The first Region is completely inside the second Region.

         3 - The second Region is completely inside the first Region.

         4 - There is partial overlap between the two Regions.

         5 - The Regions are identical to within their uncertainties.

         6 - The second Region is the exact negation of the first Region
             to within their uncertainties.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned values 5 and 6 do not check the value of the \htmlref{Closed}{Closed}
         attribute in the two Regions.

         \sstitem
         A value of zero will be returned if this function is invoked with the
         AST error status set, or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astParameterName
}{
   Get the name of the global parameter at a given index within the Table
}{
   \sstdescription{
      This function returns a string holding the name of the global parameter with
      the given index within the \htmlref{Table}{Table}.

      This function is intended primarily as a means of iterating round all
      the parameters in a Table. For this purpose, the number of parameters in
      the Table is given by the \htmlref{Nparameter}{Nparameter} attribute of the Table. This function
      could then be called in a loop, with the index value going from
      zero to one less than Nparameter.

      Note, the index associated with a parameter decreases monotonically with
      the age of the parameter: the oldest Parameter in the Table will have index
      one, and the Parameter added most recently to the Table will have the
      largest index.
   }
   \sstsynopsis{
      const char $*$astParameterName( AstTable $*$this, int index )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         index
      }{
         The index into the list of parameters. The first parameter has index
         one, and the last has index \texttt{"} Nparameter\texttt{"} .
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astParameterName()
      }{
         A pointer to a null-terminated string containing the
         upper case parameter name.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned pointer is guaranteed to remain valid and the
         string to which it points will not be over-written for a total
         of 50 successive invocations of this function. After this, the
         memory containing the string may be re-used, so a copy of the
         string should be made if it is needed for longer than this.

         \sstitem
         A NULL pointer will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astPcdMap
}{
   Create a PcdMap
}{
   \sstdescription{
      This function creates a new \htmlref{PcdMap}{PcdMap} and optionally initialises its
      attributes.

      A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional
      positions to correct for the radial distortion introduced by some
      cameras and telescopes. This can take the form either of pincushion
      or barrel distortion, and is characterized by a single distortion
      coefficient.

      A PcdMap is specified by giving this distortion coefficient and the
      coordinates of the centre of the radial distortion. The forward
      transformation of a PcdMap applies the distortion:

         RD = R $*$ ( 1 $+$ C $*$ R $*$ R )

      where R is the undistorted radial distance from the distortion
      centre (specified by attribute PcdCen), RD is the radial distance
      from the same centre in the presence of distortion, and C is the
      distortion coefficient (given by attribute \htmlref{Disco}{Disco}).

      The inverse transformation of a PcdMap removes the distortion
      produced by the forward transformation. The expression used to derive
      R from RD is an approximate inverse of the expression above, obtained
      from two iterations of the Newton-Raphson method. The mismatch between
      the forward and inverse expressions is negligible for astrometric
      applications (to reach 1 milliarcsec at the edge of the Anglo-Australian
      Telescope triplet or a Schmidt field would require field diameters of
      2.4 and 42 degrees respectively).

      If a PcdMap is inverted (e.g. using \htmlref{astInvert}{astInvert}) then the roles of the
      forward and inverse transformations are reversed; the forward
      transformation will remove the distortion, and the inverse
      transformation will apply it.
   }
   \sstsynopsis{
      AstPcdMap $*$astPcdMap( double disco, const double pcdcen[2],
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         disco
      }{
         The distortion coefficient. Negative values give barrel
         distortion, positive values give pincushion distortion, and
         zero gives no distortion.
      }
      \sstsubsection{
         pcdcen
      }{
         A 2-element array containing the coordinates of the centre of the
         distortion.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new PcdMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPcdMap()
      }{
         A pointer to the new PcdMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astPermAxes
}{
   Permute the axis order in a Frame
}{
   \sstdescription{
      This function permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur.
   }
   \sstsynopsis{
      void astPermAxes( AstFrame $*$this, const int perm[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         perm
      }{
         An array with one element for each axis of the Frame (\htmlref{Naxes}{Naxes}
         attribute). This should list the axes in their new order,
         using the original axis numbering (which starts at 1 for the
         first axis).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Only genuine permutations of the axis order are permitted, so
         each axis must be referenced exactly once in the \texttt{"} perm\texttt{"}  array.

         \sstitem
         If successive axis permutations are applied to a Frame, then
         the effects are cumulative.
      }
   }
}
\sstroutine{
   astPermMap
}{
   Create a PermMap
}{
   \sstdescription{
      This function creates a new \htmlref{PermMap}{PermMap} and optionally initialises its
      attributes.

      A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates,
      and possibly also changes the number of coordinates, between its
      input and output.

      In addition to permuting the coordinate order, a PermMap may
      also assign constant values to coordinates. This is useful when
      the number of coordinates is being increased as it allows fixed
      values to be assigned to any new ones.
   }
   \sstsynopsis{
      AstPermMap $*$astPermMap( int nin, const int inperm[], int nout,
                              const int outperm[], double constant[],
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nin
      }{
         The number of input coordinates.
      }
      \sstsubsection{
         inperm
      }{
         An optional array with \texttt{"} nin\texttt{"}  elements which, for each input
         coordinate, should contain the number of the output
         coordinate whose value is to be used (note that this array
         therefore defines the inverse coordinate transformation).
         Coordinates are numbered starting from 1.

         For details of additional special values that may be used in
         this array, see the description of the \texttt{"} constant\texttt{"}  parameter.

         If a NULL pointer is supplied instead of an array, each input
         coordinate will obtain its value from the corresponding
         output coordinate (or will be assigned the value AST\_\_BAD if
         there is no corresponding output coordinate).
      }
      \sstsubsection{
         nout
      }{
         The number of output coordinates.
      }
      \sstsubsection{
         outperm
      }{
         An optional array with \texttt{"} nout\texttt{"}  elements which, for each output
         coordinate, should contain the number of the input coordinate
         whose value is to be used (note that this array therefore
         defines the forward coordinate transformation).  Coordinates
         are numbered starting from 1.

         For details of additional special values that may be used in
         this array, see the description of the \texttt{"} constant\texttt{"}  parameter.

         If a NULL pointer is supplied instead of an array, each output
         coordinate will obtain its value from the corresponding
         input coordinate (or will be assigned the value AST\_\_BAD if
         there is no corresponding input coordinate).
      }
      \sstsubsection{
         constant
      }{
         An optional array containing values which may be assigned to
         input and/or output coordinates instead of deriving them
         from other coordinate values. If either of the \texttt{"} inperm\texttt{"}  or
         \texttt{"} outperm\texttt{"}  arrays contains a negative value, it is used to
         address this \texttt{"} constant\texttt{"}  array (such that -1 addresses the
         first element, -2 addresses the second element, etc.) and the
         value obtained is used as the corresponding coordinate value.

         Care should be taken to ensure that locations lying outside
         the extent of this array are not accidentally addressed. The
         array is not used if the \texttt{"} inperm\texttt{"}  and \texttt{"} outperm\texttt{"}  arrays do not
         contain negative values.

         If a NULL pointer is supplied instead of an array, the
         behaviour is as if the array were of infinite length and
         filled with the value AST\_\_BAD.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new PermMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPermMap()
      }{
         A pointer to the new PermMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If either of the \texttt{"} inperm\texttt{"}  or \texttt{"} outperm\texttt{"}  arrays contains a
         zero value (or a positive value which does not identify a valid
         output/input coordinate, as appropriate), then the value
         AST\_\_BAD is assigned as the new coordinate value.

         \sstitem
         This function does not attempt to ensure that the forward and
         inverse transformations performed by the PermMap are
         self-consistent in any way. You are therefore free to supply
         coordinate permutation arrays that achieve whatever effect is
         desired.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPickAxes
}{
   Create a new Frame by picking axes from an existing one
}{
   \sstdescription{
      This function creates a new \htmlref{Frame}{Frame} whose axes are copied from an
      existing Frame along with other Frame attributes, such as its
      \htmlref{Title}{Title}. Any number (zero or more) of the original Frame\texttt{'} s axes
      may be copied, in any order, and additional axes with default
      attributes may also be included in the new Frame.

      Optionally, a \htmlref{Mapping}{Mapping} that converts between the coordinate
      systems described by the two Frames will also be returned.
   }
   \sstsynopsis{
      AstFrame $*$astPickAxes( AstFrame $*$this, int naxes, const int axes[],
                             AstMapping $*$$*$map )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the original Frame.
      }
      \sstsubsection{
         naxes
      }{
         The number of axes required in the new Frame.
      }
      \sstsubsection{
         axes
      }{
         An array, with \texttt{"} naxes\texttt{"}  elements, which lists the axes to be
         copied. These should be given in the order required in the
         new Frame, using the axis numbering in the original Frame
         (which starts at 1 for the first axis). Axes may be selected
         in any order, but each may only be used once.  If additional
         (default) axes are also to be included, the corresponding
         elements of this array should be set to zero.
      }
      \sstsubsection{
         map
      }{
         Address of a location in which to return a pointer to a new
         Mapping. This will be a \htmlref{PermMap}{PermMap} (or a \htmlref{UnitMap}{UnitMap} as a special
         case) that describes the axis permutation that has taken
         place between the original and new Frames. The Mapping\texttt{'} s
         forward transformation will convert coordinates from the
         original Frame into the new one, and vice versa.

         If this Mapping is not required, a NULL value may be supplied
         for this parameter.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         This function applies to all Frames. The class of Frame returned
         may differ from that of the original Frame, depending on which
         axes are selected. For example, if a single axis is picked from a
         \htmlref{SkyFrame}{SkyFrame} (which must always have two axes) then the resulting
         Frame cannot be a valid SkyFrame, so will revert to the parent
         class (Frame) instead.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         Using this function on a FrameSet is identical to using it on
         the current Frame in the FrameSet. The returned Frame will not
         be a FrameSet.
      }
      \sstsubsection{
         \htmlref{Region}{Region}
      }{
         If this function is used on a Region, an attempt is made to
         retain the bounds information on the selected axes. If
         succesful, the returned Frame will be a Region of some class.
         Otherwise, the returned Frame is obtained by calling this
         function on the Frame represented by the supplied Region (the
         returned Frame will then not be a Region). In order to be
         succesful, the selected axes in the Region must be independent
         of the others. For instance, a \htmlref{Box}{Box} can be split in this way but
         a \htmlref{Circle}{Circle} cannot. Another requirement for success is that no
         default axes are added (that is, the
         \texttt{"} axes\texttt{"}
         array must not contain any zero values.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPickAxes()
      }{
         A pointer to the new Frame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The new Frame will contain a \texttt{"} deep\texttt{"}  copy (c.f. \htmlref{astCopy}{astCopy}) of all
         the data selected from the original Frame. Modifying any aspect
         of the new Frame will therefore not affect the original one.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPlot
}{
   Create a Plot
}{
   \sstdescription{
      This function creates a new \htmlref{Plot}{Plot} and optionally initialises its
      attributes.

      A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base
      \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"}  coordinate system and is
      associated with a rectangular plotting area in the underlying
      graphics system. This plotting area is where graphical output
      appears. It is defined when the Plot is created.

      The current Frame of a Plot describes a \texttt{"} physical\texttt{"}  coordinate
      system, which is the coordinate system in which plotting
      operations are specified. The results of each plotting operation
      are automatically transformed into graphical coordinates so as
      to appear in the plotting area (subject to any clipping which
      may be in effect).

      Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates
      may often be non-linear, or even discontinuous, most plotting
      does not result in simple straight lines. The basic plotting
      element is therefore not a straight line, but a geodesic curve
      (see \htmlref{astCurve}{astCurve}). A Plot also provides facilities for drawing
      markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines
      (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with
      optional coordinate grids (\htmlref{astGrid}{astGrid}).
      A range of Plot attributes is available to allow precise control
      over the appearance of graphical output produced by these
      functions.

      You may select different physical coordinate systems in which to
      plot (including the native graphical coordinate system itself)
      by selecting different Frames as the current Frame of a Plot,
      using its \htmlref{Current}{Current} attribute.  You may also set up clipping (see
      \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and
      this may be done in any of the coordinate systems associated
      with the Plot, not necessarily the one you are plotting in.

      Like any FrameSet, a Plot may also be used as a Frame. In this
      case, it behaves like its current Frame, which describes the
      physical coordinate system.

      When used as a Mapping, a Plot describes the inter-relation
      between graphical coordinates (its base Frame) and physical
      coordinates (its current Frame).  It differs from a normal
      FrameSet, however, in that an attempt to transform points which
      lie in clipped areas of the Plot will result in bad coordinate
      values (AST\_\_BAD).
   }
   \sstsynopsis{
      AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ],
                        const double basebox[ 4 ], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         Pointer to a Frame describing the physical coordinate system
         in which to plot. A pointer to a FrameSet may also be given,
         in which case its current Frame will be used to define the
         physical coordinate system and its base Frame will be mapped
         on to graphical coordinates (see below).

         If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default
         2-dimensional Frame will be used to describe the physical
         coordinate system. Labels, etc. may then be attached to this
         by setting the appropriate Frame attributes
         (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot.
      }
      \sstsubsection{
         graphbox
      }{
         An array giving the position and extent of the plotting area
         (on the plotting surface of the underlying graphics system)
         in which graphical output is to appear. This must be
         specified using graphical coordinates appropriate to the
         underlying graphics system.

         The first pair of values should give the coordinates of the
         bottom left corner of the plotting area and the second pair
         should give the coordinates of the top right corner. The
         coordinate on the horizontal axis should be given first in
         each pair. Note that the order in which these points are
         given is important because it defines up, down, left and
         right for subsequent graphical operations.
      }
      \sstsubsection{
         basebox
      }{
         An array giving the coordinates of two points in the supplied
         Frame (or in the base Frame if a FrameSet was supplied) which
         correspond to the bottom left and top right corners of the
         plotting area, as specified above. This range of coordinates
         will be mapped linearly on to the plotting area. The
         coordinates should be given in the same order as above.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Plot. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPlot()
      }{
         A pointer to the new Plot.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The base Frame of the returned Plot will be a new Frame which
         is created by this function to represent the coordinate system
         of the underlying graphics system (graphical coordinates). It is
         given a Frame index of 1 within the Plot. The choice of base
         Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a
         Plot has been created (although you could use this as a way of
         moving the plotting area around on the plotting surface).

         \sstitem
         If a Frame is supplied (via the \texttt{"} frame\texttt{"}  pointer), then it
         becomes the current Frame of the new Plot and is given a Frame
         index of 2.

         \sstitem
         If a FrameSet is supplied (via the \texttt{"} frame\texttt{"}  pointer), then
         all the Frames within this FrameSet become part of the new Plot
         (where their Frame indices are increased by 1), with the
         FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot.

         \sstitem
         If a null Object pointer (AST\_\_NULL) is supplied (via the
         \texttt{"} frame\texttt{"}  pointer), then the returned Plot will contain two
         Frames, both created by this function. The base Frame will
         describe graphics coordinates (as above) and the current Frame
         will be a basic Frame with no attributes set (this will
         therefore give default values for such things as the Plot \htmlref{Title}{Title}
         and the Label on each axis). Physical coordinates will be mapped
         linearly on to graphical coordinates.

         \sstitem
         An error will result if the Frame supplied (or the base Frame
         if a FrameSet was supplied) is not 2-dimensional.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPlot3D
}{
   Create a Plot3D
}{
   \sstdescription{
      This function creates a new \htmlref{Plot3D}{Plot3D} and optionally initialises
      its attributes.

      A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities
      for producing 3D graphical output.
   }
   \sstsynopsis{
      AstPlot3D $*$astPlot3D( AstFrame $*$frame, const float graphbox[ 6 ],
                            const double basebox[ 6 ], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         Pointer to a \htmlref{Frame}{Frame} describing the physical coordinate system
         in which to plot. A pointer to a \htmlref{FrameSet}{FrameSet} may also be given,
         in which case its current Frame will be used to define the
         physical coordinate system and its base Frame will be mapped
         on to graphical coordinates (see below).

         If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default
         3-dimensional Frame will be used to describe the physical
         coordinate system. Labels, etc. may then be attached to this
         by setting the appropriate Frame attributes
         (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot.
      }
      \sstsubsection{
         graphbox
      }{
         An array giving the position and extent of the plotting volume
         (within the plotting space of the underlying graphics system)
         in which graphical output is to appear. This must be
         specified using graphical coordinates appropriate to the
         underlying graphics system.

         The first triple of values should give the coordinates of the
         bottom left corner of the plotting volume and the second triple
         should give the coordinates of the top right corner. The
         coordinate on the horizontal axis should be given first in
         each pair. Note that the order in which these points are
         given is important because it defines up, down, left and
         right for subsequent graphical operations.
      }
      \sstsubsection{
         basebox
      }{
         An array giving the coordinates of two points in the supplied
         Frame (or in the base Frame if a FrameSet was supplied) which
         correspond to the bottom left and top right corners of the
         plotting volume, as specified above. This range of coordinates
         will be mapped linearly on to the plotting area. The
         coordinates should be given in the same order as above.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Plot3D. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPlot3D()
      }{
         A pointer to the new Plot3D.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The base Frame of the returned Plot3D will be a new Frame which
         is created by this function to represent the coordinate system
         of the underlying graphics system (graphical coordinates). It is
         given a Frame index of 1 within the Plot3D. The choice of base
         Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a
         Plot3D has been created (although you could use this as a way of
         moving the plotting area around on the plotting surface).

         \sstitem
         If a Frame is supplied (via the \texttt{"} frame\texttt{"}  pointer), then it
         becomes the current Frame of the new Plot3D and is given a Frame
         index of 2.

         \sstitem
         If a FrameSet is supplied (via the \texttt{"} frame\texttt{"}  pointer), then
         all the Frames within this FrameSet become part of the new Plot3D
         (where their Frame indices are increased by 1), with the
         FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot3D.

         \sstitem
         At least one of the three axes of the current Frame must be
         independent of the other two current Frame axes.

         \sstitem
         If a null Object pointer (AST\_\_NULL) is supplied (via the
         \texttt{"} frame\texttt{"}  pointer), then the returned Plot3D will contain two
         Frames, both created by this function. The base Frame will
         describe graphics coordinates (as above) and the current Frame
         will be a basic Frame with no attributes set (this will
         therefore give default values for such things as the Plot3D \htmlref{Title}{Title}
         and the Label on each axis). Physical coordinates will be mapped
         linearly on to graphical coordinates.

         \sstitem
         An error will result if the Frame supplied (or the base Frame
         if a FrameSet was supplied) is not 3-dimensional.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPointList
}{
   Create a PointList
}{
   \sstdescription{
      This function creates a new \htmlref{PointList}{PointList} object and optionally initialises
      its attributes.

      A PointList object is a specialised type of \htmlref{Region}{Region} which represents a
      collection of points in a coordinate \htmlref{Frame}{Frame}.
   }
   \sstsynopsis{
      AstPointList $*$astPointList( AstFrame $*$frame, int npnt, int ncoord, int dim,
                                  const double $*$points, AstRegion $*$unc,
                                  const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. A deep
         copy is taken of the supplied Frame. This means that any
         subsequent changes made to the Frame using the supplied pointer
         will have no effect the Region.
      }
      \sstsubsection{
         npnt
      }{
         The number of points in the Region.
      }
      \sstsubsection{
         ncoord
      }{
         The number of coordinates being supplied for each point. This
         must equal the number of axes in the supplied Frame, given by
         its \htmlref{Naxes}{Naxes} attribute.
      }
      \sstsubsection{
         dim
      }{
         The number of elements along the second dimension of the \texttt{"} points\texttt{"}
         array (which contains the point coordinates). This value is
         required so that the coordinate values can be correctly
         located if they do not entirely fill this array. The value
         given should not be less than \texttt{"} npnt\texttt{"} .
      }
      \sstsubsection{
         points
      }{
         The address of the first element of a 2-dimensional array of
         shape \texttt{"} [ncoord][dim]\texttt{"}  giving the physical coordinates of the
         points. These should be stored such that the value of coordinate
         number \texttt{"} coord\texttt{"}  for point number \texttt{"} pnt\texttt{"}  is found in element
         \texttt{"} in[coord][pnt]\texttt{"} .
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the uncertainties
         associated with each point in the PointList being created. The
         uncertainty at any point in the PointList is found by shifting the
         supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the point
         being considered. The area covered by the shifted uncertainty Region
         then represents the uncertainty in the position. The uncertainty is
         assumed to be the same for all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Box. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the bounding box of the
         PointList being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new PointList. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPointList()
      }{
         A pointer to the new PointList.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astPolyCurve
}{
   Draw a series of connected geodesic curves
}{
   \sstdescription{
      This function joins a series of points specified in the physical
      coordinate system of a \htmlref{Plot}{Plot} by drawing a sequence of geodesic
      curves.  It is equivalent to making repeated use of the \htmlref{astCurve}{astCurve}
      function (q.v.), except that astPolyCurve will generally be more
      efficient when drawing many geodesic curves end-to-end. A
      typical application of this might be in drawing contour lines.

      As with astCurve, full account is taken of the \htmlref{Mapping}{Mapping} between
      physical and graphical coordinate systems. This includes any
      discontinuities and clipping established using \htmlref{astClip}{astClip}.
   }
   \sstsynopsis{
      void astPolyCurve( AstPlot $*$this, int npoint, int ncoord, int indim,
                         const double $*$in )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         npoint
      }{
         The number of points between which geodesic curves are to be drawn.
      }
      \sstsubsection{
         ncoord
      }{
         The number of coordinates being supplied for each point (i.e.
         the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given
         by its \htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         indim
      }{
         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
         array (which contains the input coordinates). This value is
         required so that the coordinate values can be correctly
         located if they do not entirely fill this array. The value
         given should not be less than \texttt{"} npoint\texttt{"} .
      }
      \sstsubsection{
         in
      }{
         The address of the first element in a 2-dimensional array of shape
         \texttt{"} [ncoord][indim]\texttt{"}  giving the
         physical coordinates of the points which are to be joined in
         sequence by geodesic curves. These should be stored such that
         the value of coordinate number \texttt{"} coord\texttt{"}  for point number
         \texttt{"} point\texttt{"}  is found in element \texttt{"} in[coord][point]\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         No curve is drawn on either side of any point which has any
         coordinate equal to the value AST\_\_BAD.

         \sstitem
         An error results if the base Frame of the Plot is not
         2-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astPolyMap
}{
   Create a PolyMap
}{
   \sstdescription{
      This function creates a new \htmlref{PolyMap}{PolyMap} and optionally initialises
      its attributes.

      A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial
      transformation.  Each output coordinate is a polynomial function of
      all the input coordinates. The coefficients are specified separately
      for each output coordinate. The forward and inverse transformations
      are defined independantly by separate sets of coefficients. If no
      inverse transformation is supplied, an iterative method can be used
      to evaluate the inverse based only on the forward transformation.
   }
   \sstsynopsis{
      AstPolyMap $*$astPolyMap( int nin, int nout, int ncoeff\_f, const double coeff\_f[],
                              int ncoeff\_i, const double coeff\_i[],
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nin
      }{
         The number of input coordinates.
      }
      \sstsubsection{
         nout
      }{
         The number of output coordinates.
      }
      \sstsubsection{
         ncoeff\_f
      }{
         The number of non-zero coefficients necessary to define the
         forward transformation of the PolyMap. If zero is supplied, the
         forward transformation will be undefined.
      }
      \sstsubsection{
         coeff\_f
      }{
         An array containing
         \texttt{"} ncoeff\_f$*$( 2 $+$ nin )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nin\texttt{"}
         adjacent elements describe a single coefficient of the forward
         transformation. Within each such group, the first element is the
         coefficient value; the next element is the integer index of the
         PolyMap output which uses the coefficient within its defining
         polynomial (the first output has index 1); the remaining elements
         of the group give the integer powers to use with each input
         coordinate value (powers must not be negative, and floating
         point values are rounded to the nearest integer).
         If \texttt{"} ncoeff\_f\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_f\texttt{"} .

         For instance, if the PolyMap has 3 inputs and 2 outputs, each group
         consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"}
         describes a coefficient with value 1.2 which is used within the
         definition of output 2. The output value is incremented by the
         product of the coefficient value, the value of input coordinate
         1 raised to the power 1, and the value of input coordinate 2 raised
         to the power 3. Input coordinate 3 is not used since its power is
         specified as zero. As another example, the group \texttt{"} (-1.0, 1.0,
         0.0, 0.0, 0.0 )\texttt{"}  describes adds a constant value -1.0 onto
         output 1 (it is a constant value since the power for every input
         axis is given as zero).

         Each final output coordinate value is the sum of the \texttt{"} ncoeff\_f\texttt{"}  terms
         described by the \texttt{"} ncoeff\_f\texttt{"}  groups within the supplied array.
      }
      \sstsubsection{
         ncoeff\_i
      }{
         The number of non-zero coefficients necessary to define the
         inverse transformation of the PolyMap. If zero is supplied, the
         inverse transformation will be undefined.
      }
      \sstsubsection{
         coeff\_i
      }{
         An array containing
         \texttt{"} ncoeff\_i$*$( 2 $+$ nout )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nout\texttt{"}
         adjacent elements describe a single coefficient of the inverse
         transformation, using the same schame as \texttt{"} coeff\_f\texttt{"} ,
         except that \texttt{"} inputs\texttt{"}  and \texttt{"} outputs\texttt{"}  are transposed.
         If \texttt{"} ncoeff\_i\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_i\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new PolyMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPolyMap()
      }{
         A pointer to the new PolyMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPolyTran
}{
   Fit a PolyMap inverse or forward transformation
}{
   \sstdescription{
      This function creates a new \htmlref{PolyMap}{PolyMap} which is a copy of the supplied
      PolyMap, in which a specified transformation (forward or inverse)
      has been replaced by a new polynomial transformation. The
      coefficients of the new transformation are estimated by sampling
      the other transformation and performing a least squares polynomial
      fit in the opposite direction to the sampled positions and values.

      This method can only be used on (1-input,1-output) or (2-input,2-output)
      PolyMaps.

      The transformation to create is specified by the
      \texttt{"} forward\texttt{"}  parameter.
      In what follows \texttt{"} X\texttt{"}  refers to the inputs of the PolyMap, and \texttt{"} Y\texttt{"}  to
      the outputs of the PolyMap. The forward transformation transforms
      input values (X) into output values (Y), and the inverse transformation
      transforms output values (Y) into input values (X). Within a PolyMap,
      each transformation is represented by an independent set of
      polynomials, P\_f or P\_i: Y=P\_f(X) for the forward transformation and
      X=P\_i(Y) for the inverse transformation.

      The \texttt{"} forward\texttt{"}
      parameter specifies the transformation to be replaced. If it is
      non-zero,
      a new forward transformation is created
      by first finding the input values (X) using the inverse transformation
      (which must be available) at a regular grid of points (Y) covering a
      rectangular region of the PolyMap\texttt{'} s output space. The coefficients of
      the required forward polynomial, Y=P\_f(X), are chosen in order to
      minimise the sum of the squared residuals between the sampled values
      of Y and P\_f(X).

      If \texttt{"} forward\texttt{"}  is zero (probably the most likely case),
      a new inverse transformation is created by
      first finding the output values (Y) using the forward transformation
      (which must be available) at a regular grid of points (X) covering a
      rectangular region of the PolyMap\texttt{'} s input space. The coefficients of
      the required inverse polynomial, X=P\_i(Y), are chosen in order to
      minimise the sum of the squared residuals between the sampled values
      of X and P\_i(Y).

      This fitting process is performed repeatedly with increasing
      polynomial orders (starting with linear) until the target
      accuracy is achieved, or a specified maximum order is reached. If
      the target accuracy cannot be achieved even with this maximum-order
      polynomial, the best fitting maximum-order polynomial is returned so
      long as its accuracy is better than
      \texttt{"} maxacc\texttt{"} .
      If it is not, an error is reported.
   }
   \sstsynopsis{
      AstPolyMap $*$astPolyTran( AstPolyMap $*$this, int forward, double acc,
                               double maxacc, int maxorder, const double $*$lbnd,
                               const double $*$ubnd )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the original \htmlref{Mapping}{Mapping}.
      }
      \sstsubsection{
         forward
      }{
         If non-zero,
         the forward PolyMap transformation is replaced. Otherwise the
         inverse transformation is replaced.
      }
      \sstsubsection{
         acc
      }{
         The target accuracy, expressed as a geodesic distance within
         the PolyMap\texttt{'} s input space (if
         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
      }
      \sstsubsection{
         maxacc
      }{
         The maximum allowed accuracy for an acceptable polynomial,
         expressed as a geodesic distance within the PolyMap\texttt{'} s input
         space (if
         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
      }
      \sstsubsection{
         maxorder
      }{
         The maximum allowed polynomial order. This is one more than the
         maximum power of either input axis. So for instance, a value of
         3 refers to a quadratic polynomial. Note, cross terms with total
         powers greater than or equal to
         maxorder
         are not inlcuded in the fit. So the maximum number of terms in
         each of the fitted polynomials is
         maxorder$*$(maxorder$+$1)/2.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an
         array holding the lower bounds of a rectangular region within
         the PolyMap\texttt{'} s input space (if
         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
         The new polynomial will be evaluated over this rectangle. The
         length of this array should equal the value of the PolyMap\texttt{'} s \htmlref{Nin}{Nin}
         or \htmlref{Nout}{Nout} attribute, depending on
         \texttt{"} forward\texttt{"} .
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an
         array holding the upper bounds of a rectangular region within
         the PolyMap\texttt{'} s input space (if
         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
         The new polynomial will be evaluated over this rectangle.  The
         length of this array should equal the value of the PolyMap\texttt{'} s Nin
         or Nout attribute, depending on
         \texttt{"} forward\texttt{"} .
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPolyTran()
      }{
         A pointer to the new PolyMap.
         A NULL pointer
         will be returned if the fit fails to achieve the accuracy
         specified by
         \texttt{"} maxacc\texttt{"} ,
         but no error will be reported.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function can only be used on 1D or 2D PolyMaps which have
         the same number of inputs and outputs.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPolygon
}{
   Create a Polygon
}{
   \sstdescription{
      This function creates a new \htmlref{Polygon}{Polygon} object and optionally initialises
      its attributes.

      The Polygon class implements a polygonal area, defined by a
      collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices
      are connected together by geodesic curves within the encapsulated Frame.
      For instance, if the encapsulated Frame is a simple Frame then the
      geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then
      the geodesics will be great circles. Note, the vertices must be
      supplied in an order such that the inside of the polygon is to the
      left of the boundary as the vertices are traversed. Supplying them
      in the reverse order will effectively negate the polygon.

      Within a SkyFrame, neighbouring vertices are always joined using the
      shortest path. Thus if an edge of 180 degrees or more in length is
      required, it should be split into section each of which is less
      than 180 degrees. The closed path joining all the vertices in order
      will divide the celestial sphere into two disjoint regions. The
      inside of the polygon is the region which is circled in an
      anti-clockwise manner (when viewed from the inside of the celestial
      sphere) when moving through the list of vertices in the order in
      which they were supplied when the Polygon was created (i.e. the
      inside is to the left of the boundary when moving through the
      vertices in the order supplied).
   }
   \sstsynopsis{
      AstPolygon $*$astPolygon( AstFrame $*$frame, int npnt, int dim,
                              const double $*$points, AstRegion $*$unc,
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame
      }{
         A pointer to the Frame in which the region is defined. It must
         have exactly 2 axes. A deep copy is taken of the supplied Frame.
         This means that any subsequent changes made to the Frame using the
         supplied pointer will have no effect the \htmlref{Region}{Region}.
      }
      \sstsubsection{
         npnt
      }{
         The number of points in the Region.
      }
      \sstsubsection{
         dim
      }{
         The number of elements along the second dimension of the \texttt{"} points\texttt{"}
         array (which contains the point coordinates). This value is
         required so that the coordinate values can be correctly
         located if they do not entirely fill this array. The value
         given should not be less than \texttt{"} npnt\texttt{"} .
      }
      \sstsubsection{
         points
      }{
         The address of the first element of a 2-dimensional array of
         shape \texttt{"} [2][dim]\texttt{"}  giving the physical coordinates of the vertices.
         These should be stored such that the value of coordinate
         number \texttt{"} coord\texttt{"}  for point number \texttt{"} pnt\texttt{"}  is found in element
         \texttt{"} in[coord][pnt]\texttt{"} .
      }
      \sstsubsection{
         unc
      }{
         An optional pointer to an existing Region which specifies the
         uncertainties associated with the boundary of the Polygon being created.
         The uncertainty in any point on the boundary of the Polygon is found by
         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
         the boundary point being considered. The area covered by the
         shifted uncertainty Region then represents the uncertainty in the
         boundary position. The uncertainty is assumed to be the same for
         all points.

         If supplied, the uncertainty Region must be of a class for which
         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
         copy of the supplied Region will be taken, so subsequent changes to
         the uncertainty Region using the supplied pointer will have no
         effect on the created Polygon. Alternatively,
         a NULL \htmlref{Object}{Object} pointer
         may be supplied, in which case a default uncertainty is used
         equivalent to a box 1.0E-6 of the size of the Polygon being created.

         The uncertainty Region has two uses: 1) when the
         \htmlref{astOverlap}{astOverlap}
         function compares two Regions for equality the uncertainty
         Region is used to determine the tolerance on the comparison, and 2)
         when a Region is mapped into a different coordinate system and
         subsequently simplified (using
         \htmlref{astSimplify}{astSimplify}),
         the uncertainties are used to determine if the transformed boundary
         can be accurately represented by a specific shape of Region.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Polygon. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPolygon()
      }{
         A pointer to the new Polygon.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astPrism
}{
   Create a Prism
}{
   \sstdescription{
      This function creates a new \htmlref{Prism}{Prism} and optionally initialises
      its attributes.

      A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region
      into one or more orthogonal dimensions (specified by another Region).
      If the Region to be extruded has N axes, and the Region defining the
      extrusion has M axes, then the resulting Prism will have (M$+$N) axes.
      A point is inside the Prism if the first N axis values correspond to
      a point inside the Region being extruded, and the remaining M axis
      values correspond to a point inside the Region defining the extrusion.

      As an example, a cylinder can be represented by extruding an existing
      \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the
      Interval would have a single axis and would specify the upper and
      lower limits of the cylinder along its length.
   }
   \sstsynopsis{
      AstPrism $*$astPrism( AstRegion $*$region1, AstRegion $*$region2,
                          const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region1
      }{
         Pointer to the Region to be extruded.
      }
      \sstsubsection{
         region2
      }{
         Pointer to the Region defining the extent of the extrusion.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Prism. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astPrism()
      }{
         A pointer to the new Prism.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Deep copies are taken of the supplied Regions. This means that
         any subsequent changes made to the component Regions using the
         supplied pointers will have no effect on the Prism.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astPurgeRows
}{
   Remove all empty rows from a table
}{
   \sstdescription{
      This function removes all empty rows from the \htmlref{Table}{Table}, renaming
      the key associated with each table cell accordingly.
   }
   \sstsynopsis{
      void astPurgeRows( AstTable $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
   }
}
\sstroutine{
   astPurgeWCS
}{
   Delete all cards in the FitsChan describing WCS information
}{
   \sstdescription{
      This function
      deletes all cards in a \htmlref{FitsChan}{FitsChan} that relate to any of the recognised
      WCS encodings. On exit, the current card is the first remaining card
      in the FitsChan.
   }
   \sstsynopsis{
      void astPurgeWCS( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
}
\sstroutine{
   astPutCards
}{
   Store a set of FITS header cards in a FitsChan
}{
   \sstdescription{
      This function
      stores a set of FITS header cards in a \htmlref{FitsChan}{FitsChan}. The cards are
      supplied concatenated together into a single character string.
      Any existing cards in the FitsChan are removed before the new cards
      are added. The FitsChan is \texttt{"} re-wound\texttt{"}  on exit by clearing its \htmlref{Card}{Card}
      attribute. This means that a subsequent invocation of
      \htmlref{astRead}{astRead}
      can be made immediately without the need to re-wind the FitsChan
      first.
   }
   \sstsynopsis{
      void astPutCards( AstFitsChan $*$this, const char $*$cards )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         cards
      }{
         Pointer to a null-terminated character string
         containing the FITS cards to be stored. Each individual card
         should occupy 80 characters in this string, and there should be
         no delimiters, new lines, etc, between adjacent cards. The final
         card may be less than 80 characters long.
         This is the format produced by the fits\_hdr2str function in the
         CFITSIO library.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error will result if the supplied string contains any cards
         which cannot be interpreted.
      }
   }
}
\sstroutine{
   astPutChannelData
}{
   Store arbitrary data to be passed to a source or sink function
}{
   \sstdescription{
      This function stores a supplied arbitrary pointer in the \htmlref{Channel}{Channel}.
      When a source or sink function is invoked by the Channel, the
      invoked function can use the \htmlref{astChannelData}{astChannelData} macro to retrieve the
      pointer. This provides a thread-safe alternative to passing file
      descriptors, etc, via global static variables.
   }
   \sstsynopsis{
      void astPutChannelData( AstChannel $*$this, void $*$data )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Channel.
      }
      \sstsubsection{
         data
      }{
         A pointer to be made available to the source and sink functions
         via the astChannelData macro. May be NULL.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         All Channels have this function.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This routine is not available in the Fortran 77 interface to
         the AST library.
      }
   }
}
\sstroutine{
   astPutColumnData
}{
   Store new data values for all rows of a column
}{
   \sstdescription{
      This function
      copies data values from a supplied buffer into a named column. The
      first element in the buffer becomes the first element in the first
      row of the column. If the buffer does not completely fill the
      column, then any trailing rows are filled with null values.
   }
   \sstsynopsis{
      void astPutColumnData( AstFitsTable $*$this, const char $*$column,
                             int clen, size\_t size, void $*$coldata )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{FitsTable}{FitsTable}.
      }
      \sstsubsection{
         column
      }{
         The character string holding the name of the column. Trailing
         spaces are ignored.
      }
      \sstsubsection{
         clen
      }{
         If the column holds character strings, then this must be set to
         the length of each fixed length string in the supplied array.
         This is often determined by the appropriate TFORMn keyword in
         the binary table header. The supplied value is ignored if the
         column does not hold character data.
      }
      \sstsubsection{
         size
      }{
         The size of the
         \texttt{"} coldata\texttt{"}
         array, in bytes. This should be an integer multiple of the
         number of bytes needed to hold the full vector value stored in a
         single cell of the column. An error is reported if this is not
         the case.
      }
      \sstsubsection{
         coldata
      }{
         A pointer to an
         area of memory holding the data to copy into the column. The values
         should be stored in row order. If the column holds non-scalar values,
         the elements of each value should be stored in \texttt{"} Fortran\texttt{"}  order. No
         data type conversion is performed.
      }
   }
}
\sstroutine{
   astPutFits
}{
   Store a FITS header card in a FitsChan
}{
   \sstdescription{
      This function stores a FITS header card in a \htmlref{FitsChan}{FitsChan}. The card
      is either inserted before the current card (identified by the
      \htmlref{Card}{Card} attribute), or over-writes the current card, as required.
   }
   \sstsynopsis{
      void astPutFits( AstFitsChan $*$this, const char card[ 80 ],
                       int overwrite )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         card
      }{
         Pointer to a possibly null-terminated character string
         containing the FITS card to be stored. No more than 80
         characters will be used from this string (or fewer if a null
         occurs earlier).
      }
      \sstsubsection{
         overwrite
      }{
         If this value is zero, the new card is inserted in front of
         the current card in the FitsChan (as identified by the
         initial value of the Card attribute). If it is non-zero, the
         new card replaces the current card. In either case, the Card
         attribute is then incremented by one so that it subsequently
         identifies the card following the one stored.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the Card attribute initially points at the \texttt{"} end-of-file\texttt{"}
         (i.e. exceeds the number of cards in the FitsChan), then the new
         card is appended as the last card in the FitsChan.

         \sstitem
         An error will result if the supplied string cannot be interpreted
         as a FITS header card.
      }
   }
}
\sstroutine{
   astPutTable
}{
   Store a single FitsTable in a FitsChan
}{
   \sstdescription{
      This function
      allows a representation of a single FITS binary table to be
      stored in a \htmlref{FitsChan}{FitsChan}. For instance, this may provide the coordinate
      look-up tables needed subequently when reading FITS-WCS headers
      for axes described using the \texttt{"} -TAB\texttt{"}  algorithm. Since, in general,
      the calling application may not know which tables will be needed -
      if any - prior to calling
      \htmlref{astRead}{astRead}, the astTablesSource function
      provides an alternative mechanism in which a caller-supplied
      function is invoked to store a named table in the FitsChan.
   }
   \sstsynopsis{
      void astPutTable( AstFitsChan $*$this, AstFitsTable $*$table,
                        const char $*$extnam )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         table
      }{
         Pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. If a FitsTable
         with the associated extension name already exists in the FitsChan,
         it is replaced with the new one. A deep copy of the FitsTable is
         stored in the FitsChan, so any subsequent changes made to the
         FitsTable will have no effect on the behaviour of the FitsChan.
      }
      \sstsubsection{
         extnam
      }{
         The name of the FITS extension associated with the table.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Tables stored in the FitsChan may be retrieved using
         \htmlref{astGetTables}{astGetTables}.

         \sstitem
         The \htmlref{astPutTables}{astPutTables} method can add multiple FitsTables in a single call.
      }
   }
}
\sstroutine{
   astPutTableHeader
}{
   Store new FITS headers in a FitsTable
}{
   \sstdescription{
      This function
      stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing
      headers are first deleted.
   }
   \sstsynopsis{
      void astPutTableHeader( AstFitsTable $*$this, AstFitsChan $*$header )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsTable.
      }
      \sstsubsection{
         header
      }{
         Pointer to a \htmlref{FitsChan}{FitsChan} holding the headers for the FitsTable.
         A deep copy of the supplied FitsChan is stored in the FitsTable,
         replacing the current FitsChan in the Fitstable. Keywords that
         are fixed either by the properties of the \htmlref{Table}{Table}, or by the FITS
         standard, are removed from the copy (see \texttt{"} Notes:\texttt{"}  below).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The attributes of the supplied FitsChan, together with any source
         and sink functions associated with the FitsChan, are copied to the
         FitsTable.

         \sstitem
         Values for the following keywords are generated automatically by
         the FitsTable (any values for these keywords in the supplied
         FitsChan will be ignored): \texttt{"} XTENSION\texttt{"} , \texttt{"} BITPIX\texttt{"} , \texttt{"} NAXIS\texttt{"} , \texttt{"} NAXIS1\texttt{"} ,
         \texttt{"} NAXIS2\texttt{"} , \texttt{"} PCOUNT\texttt{"} , \texttt{"} GCOUNT\texttt{"} , \texttt{"} TFIELDS\texttt{"} , \texttt{"} TFORM\%d\texttt{"} , \texttt{"} TTYPE\%d\texttt{"} ,
         \texttt{"} TNULL\%d\texttt{"} , \texttt{"} THEAP\texttt{"} , \texttt{"} TDIM\%d\texttt{"} .
      }
   }
}
\sstroutine{
   astPutTables
}{
   Store one or more FitsTables in a FitsChan
}{
   \sstdescription{
      This function
      allows representations of one or more FITS binary tables to be
      stored in a \htmlref{FitsChan}{FitsChan}. For instance, these may provide the coordinate
      look-up tables needed subequently when reading FITS-WCS headers
      for axes described using the \texttt{"} -TAB\texttt{"}  algorithm. Since, in general,
      the calling application may not know which tables will be needed -
      if any - prior to calling
      \htmlref{astRead}{astRead}, the astTablesSource function
      provides an alternative mechanism in which a caller-supplied
      function is invoked to store a named table in the FitsChan.
   }
   \sstsynopsis{
      void astPutTables( AstFitsChan $*$this, AstKeyMap $*$tables )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         tables
      }{
         Pointer to a \htmlref{KeyMap}{KeyMap} holding the tables that are to be added
         to the FitsChan. Each entry should hold a scalar value which is a
         pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. Any unusable
         entries are ignored. The key associated with each entry should be
         the name of the FITS binary extension from which the table was
         read. If a FitsTable with the associated key already exists in the
         FitsChan, it is replaced with the new one. A deep copy of each
         usable FitsTable is stored in the FitsChan, so any subsequent
         changes made to the FitsTables will have no effect on the
         behaviour of the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Tables stored in the FitsChan may be retrieved using
         \htmlref{astGetTables}{astGetTables}.

         \sstitem
         The tables in the supplied KeyMap are added to any tables already
         in the FitsChan.

         \sstitem
         The \htmlref{astPutTable}{astPutTable}
         method provides a simpler means of adding a single table to a FitsChan.
      }
   }
}
\sstroutine{
   astQuadApprox
}{
   Obtain a quadratic approximation to a 2D Mapping
}{
   \sstdescription{
      This function returns the co-efficients of a quadratic fit to the
      supplied \htmlref{Mapping}{Mapping} over the input area specified by
      \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} .
      The Mapping must have 2 inputs, but may have any number of outputs.
      The i\texttt{'} th Mapping output is modelled as a quadratic function of the
      2 inputs (x,y):

      output\_i = a\_i\_0 $+$ a\_i\_1$*$x $+$ a\_i\_2$*$y $+$ a\_i\_3$*$x$*$y $+$ a\_i\_4$*$x$*$x $+$
                 a\_i\_5$*$y$*$y

      The \texttt{"} fit\texttt{"}
      array is returned holding the values of the co-efficients a\_0\_0,
      a\_0\_1, etc.
   }
   \sstsynopsis{
      int QuadApprox( AstMapping $*$this,  const double lbnd[2],
                      const double ubnd[2], int nx, int ny, double $*$fit,
                      double $*$rms )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of doubles
         containing the lower bounds of a box defined within the input
         coordinate system of the Mapping. The number of elements in this
         array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This
         box should specify the region over which the fit is to be
         performed.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of doubles
         containing the upper bounds of the box specifying the region over
         which the fit is to be performed.
      }
      \sstsubsection{
         nx
      }{
         The number of points to place along the first Mapping input. The
         first point is at
         \texttt{"} lbnd[0]\texttt{"}  and the last is at \texttt{"} ubnd[0]\texttt{"} .
         If a value less than three is supplied a value of three will be used.
      }
      \sstsubsection{
         ny
      }{
         The number of points to place along the second Mapping input. The
         first point is at
         \texttt{"} lbnd[1]\texttt{"}  and the last is at \texttt{"} ubnd[1]\texttt{"} .
         If a value less than three is supplied a value of three will be used.
      }
      \sstsubsection{
         fit
      }{
         Pointer to an array of doubles
         in which to return the co-efficients of the quadratic
         approximation to the specified transformation. This array should
         have at least \texttt{"} 6$*$\htmlref{Nout}{Nout}\texttt{"} , elements. The first 6 elements hold the
         fit to the first Mapping output. The next 6 elements hold the
         fit to the second Mapping output, etc. So if the Mapping has 2
         inputs and 2 outputs the quadratic approximation to the forward
         transformation is:

            X\_out = fit[0] $+$ fit[1]$*$X\_in $+$ fit[2]$*$Y\_in $+$ fit[3]$*$X\_in$*$Y\_in $+$
                    fit[4]$*$X\_in$*$X\_in $+$ fit[5]$*$Y\_in$*$Y\_in
            Y\_out = fit[6] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in $+$ fit[9]$*$X\_in$*$Y\_in $+$
                    fit[10]$*$X\_in$*$X\_in $+$ fit[11]$*$Y\_in$*$Y\_in
      }
      \sstsubsection{
         rms
      }{
         Pointer to a double in which to return the
         RMS residual between the fit and the Mapping, summed over all
         Mapping outputs.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astQuadApprox()
      }{
         If a quadratic approximation was created,
         a non-zero value is returned. Otherwise zero is returned
         and the fit co-efficients are set to AST\_\_BAD.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function fits the Mapping\texttt{'} s forward transformation. To fit
         the inverse transformation, the Mapping should be inverted using
         \htmlref{astInvert}{astInvert}
         before invoking this function.

         \sstitem
         A value of zero
         will be returned if this function is invoked
         with the global error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astRate
}{
   Calculate the rate of change of a Mapping output
}{
   \sstdescription{
      This function
      evaluates the rate of change of a specified output of the supplied
      \htmlref{Mapping}{Mapping} with respect to a specified input, at a specified input
      position.

      The result is estimated by interpolating the function using a
      fourth order polynomial in the neighbourhood of the specified
      position. The size of the neighbourhood used is chosen to minimise
      the RMS residual per unit length between the interpolating
      polynomial and the supplied Mapping function. This method produces
      good accuracy but can involve evaluating the Mapping 100 or more
      times.
   }
   \sstsynopsis{
      double astRate( AstMapping $*$this, double $*$at, int ax1, int ax2 )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         at
      }{
         The address of an
         array holding the axis values at the position at which the rate
         of change is to be evaluated. The number of elements in this
         array should equal the number of inputs to the Mapping.
      }
      \sstsubsection{
         ax1
      }{
         The index of the Mapping output for which the rate of change is to
         be found (output numbering starts at 1 for the first output).
      }
      \sstsubsection{
         ax2
      }{
         The index of the Mapping input which is to be varied in order to
         find the rate of change (input numbering starts at 1 for the first
         input).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astRate()
      }{
         The rate of change of Mapping output \texttt{"} ax1\texttt{"}  with respect to input
         \texttt{"} ax2\texttt{"} , evaluated at \texttt{"} at\texttt{"} , or AST\_\_BAD if the value cannot be
         calculated.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of AST\_\_BAD will be returned if this function is invoked
         with the global error status set, or if it should fail for any
         reason.
      }
   }
}
\sstroutine{
   astRateMap
}{
   Create a RateMap
}{
   \sstdescription{
      This function creates a new \htmlref{RateMap}{RateMap} and optionally initialises
      its attributes.

      A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the
      Jacobian matrix of another Mapping. The Mapping for which the
      Jacobian is required is specified when the new RateMap is created,
      and is referred to as the \texttt{"} encapsulated Mapping\texttt{"}  below.

      The number of inputs to a RateMap is the same as the number of inputs
      to its encapsulated Mapping. The number of outputs from a RateMap
      is always one. This one output equals the rate of change of a
      specified output of the encapsulated Mapping with respect to a
      specified input of the encapsulated Mapping (the input and output
      to use are specified when the RateMap is created).

      A RateMap which has not been inverted does not define an inverse
      transformation. If a RateMap has been inverted then it will define
      an inverse transformation but not a forward transformation.
   }
   \sstsynopsis{
      AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2,
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         map
      }{
         Pointer to the encapsulated Mapping.
      }
      \sstsubsection{
         ax1
      }{
         Index of the output from the encapsulated Mapping for which the
         rate of change is required. This corresponds to the delta
         quantity forming the numerator of the required element of the
         Jacobian matrix. The first axis has index 1.
      }
      \sstsubsection{
         ax2
      }{
         Index of the input to the encapsulated Mapping which is to be
         varied. This corresponds to the delta quantity forming the
         denominator of the required element of the Jacobian matrix.
         The first axis has index 1.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new RateMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astRateMap()
      }{
         A pointer to the new RateMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The forward transformation of the encapsulated Mapping must be
         defined.

         \sstitem
         Note that the component Mappings supplied are not copied by
         astRateMap (the new RateMap simply retains a reference to
         them). They may continue to be used for other purposes, but
         should not be deleted. If a RateMap containing a copy of its
         component Mappings is required, then a copy of the RateMap should
         be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astRead
}{
   Read an Object from a Channel
}{
   \sstdescription{
      This function reads the next \htmlref{Object}{Object} from a \htmlref{Channel}{Channel} and returns a
      pointer to the new Object.
   }
   \sstsynopsis{
      AstObject $*$astRead( AstChannel $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Channel.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         All successful use of astRead on a FitsChan 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 FitsChan
         \htmlref{astRetainFits}{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.
      }
      \sstsubsection{
         \htmlref{StcsChan}{StcsChan}
      }{
         The AST Object returned by a successful use of
         astRead
         on an StcsChan, will be either a \htmlref{Region}{Region} or a \htmlref{KeyMap}{KeyMap}, depending
         on the values of the \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps}
         attributes. See the documentation for these attributes for further
         information.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astRead()
      }{
         A pointer to the new Object. The class to which this will
         belong is determined by the input data, so is not known in
         advance.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned, without
         error, if the Channel contains no further Objects to be read.

         \sstitem
         A null Object pointer will also be returned if this function
         is invoked with the AST error status set, or if it should fail
         for any reason.
      }
   }
}
\sstroutine{
   astReadFits
}{
   Read cards into a FitsChan from the source function
}{
   \sstdescription{
      This function
      reads cards from the source function that was specified when the
      \htmlref{FitsChan}{FitsChan} was created, and stores them in the FitsChan. This
      normally happens once-only, when the FitsChan is accessed for the
      first time.
      This function
      provides a means of forcing a re-read of the external source, and
      may be useful if (say) new cards have been deposited into the
      external source. Any newcards read from the source are appended to
      the end of the current contents of the FitsChan.
   }
   \sstsynopsis{
      void astReadFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function returns without action if no source function was
         specified when the FitsChan was created.

         \sstitem
         The \htmlref{SourceFile}{SourceFile} attribute is ignored by this
         function.
         New cards are read from the source file whenever a new value is
         assigned to the SourceFile attribute.
      }
   }
}
\sstroutine{
   astRebin$<$X$>$
}{
   Rebin a region of a data grid
}{
   \sstdescription{
      This is a set of functions for rebinning gridded data (e.g. an
      image) under the control of a geometrical transformation, which
      is specified by a \htmlref{Mapping}{Mapping}.  The functions operate on a pair of
      data grids (input and output), each of which may have any number
      of dimensions. Rebinning may be restricted to a specified
      region of the input grid. An associated grid of error estimates
      associated with the input data may also be supplied (in the form
      of variance values), so as to produce error estimates for the
      rebined output data. Propagation of missing data (bad pixels)
      is supported.

      Note, if you will be rebining a sequence of input arrays and then
      co-adding them into a single array, the alternative
      \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} functions
      will in general be more efficient.

      You should use a rebinning function which matches the numerical
      type of the data you are processing by replacing $<$X$>$ in
      the generic function name astRebin$<$X$>$ by an appropriate 1- or
      2-character type code. For example, if you are rebinning data
      with type \texttt{"} float\texttt{"} , you should use the function astRebinF (see
      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
      other numerical types).

      Rebinning of the grid of input data is performed by transforming
      the coordinates of the centre of each input grid element (or pixel)
      into the coordinate system of the output grid. The input pixel
      value is then divided up and assigned to the output pixels in the
      neighbourhood of the central output coordinates. A choice of
      schemes are provided for determining how each input pixel value is
      divided up between the output pixels. In general, each output pixel
      may be assigned values from more than one input pixel. All
      contributions to a given output pixel are summed to produce the
      final output pixel value. Output pixels can be set to the supplied
      bad value if they receive contributions from an insufficient number
      of input pixels. This is controlled by the
      \texttt{"} wlim\texttt{"}  parameter.

      Input pixel coordinates are transformed into the coordinate
      system of the output grid using the forward transformation of the
      Mapping which is supplied. This means that geometrical features
      in the input data are subjected to the Mapping\texttt{'} s forward
      transformation as they are transferred from the input to the
      output grid.

      In practice, transforming the coordinates of every pixel of a
      large data grid can be time-consuming, especially if the Mapping
      involves complicated functions, such as sky projections. To
      improve performance, it is therefore possible to approximate
      non-linear Mappings by a set of linear transformations which are
      applied piece-wise to separate sub-regions of the data. This
      approximation process is applied automatically by an adaptive
      algorithm, under control of an accuracy criterion which
      expresses the maximum tolerable geometrical distortion which may
      be introduced, as a fraction of a pixel.

      This algorithm first attempts to approximate the Mapping with a
      linear transformation applied over the whole region of the
      input grid which is being used. If this proves to be
      insufficiently accurate, the input region is sub-divided into
      two along its largest dimension and the process is repeated
      within each of the resulting sub-regions. This process of
      sub-division continues until a sufficiently good linear
      approximation is found, or the region to which it is being
      applied becomes too small (in which case the original Mapping is
      used directly).
   }
   \sstsynopsis{
      void astRebin$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in,
                       const int lbnd\_in[], const int ubnd\_in[],
                       const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
                       int spread, const double params[], int flags,
                       double tol, int maxpix,
                       $<$Xtype$>$ badval, int ndim\_out,
                       const int lbnd\_out[], const int ubnd\_out[],
                       const int lbnd[], const int ubnd[],
                       $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to a Mapping, whose forward transformation will be
         used to transform the coordinates of pixels in the input
         grid into the coordinate system of the output grid.

         The number of input coordinates used by this Mapping (as
         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
         attribute) should match the number of output grid dimensions
         given by \texttt{"} ndim\_out\texttt{"} .
      }
      \sstsubsection{
         wlim
      }{
         Gives the required number of input pixel values which must contribute
         to an output pixel in order for the output pixel value to be
         considered valid. If the sum of the input pixel weights contributing
         to an output pixel is less than the supplied
         \texttt{"} wlim\texttt{"}
         value, then the output pixel value is returned set to the
         supplied bad value.
      }
      \sstsubsection{
         ndim\_in
      }{
         The number of dimensions in the input grid. This should be at
         least one.
      }
      \sstsubsection{
         lbnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre.
      }
      \sstsubsection{
         in
      }{
         Pointer to an array, with one element for each pixel in the
         input grid, containing the input data to be rebined.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astRebinF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         in\_var
      }{
         An optional pointer to a second array with the same size and
         type as the \texttt{"} in\texttt{"}  array. If given, this should contain a set
         of non-negative values which represent estimates of the
         statistical variance associated with each element of the \texttt{"} in\texttt{"}
         array. If this array is supplied (together with the
         corresponding \texttt{"} out\_var\texttt{"}  array), then estimates of the
         variance of the rebined output data will be calculated.

         If no input variance estimates are being provided, a NULL
         pointer should be given.
      }
      \sstsubsection{
         spread
      }{
         This parameter specifies the scheme to be used for dividing
         each input data value up amongst the corresponding output pixels.
         It may be used to select
         from a set of pre-defined schemes by supplying one of the
         values described in the \texttt{"} Pixel Spreading Schemes\texttt{"}
         section below.  If a value of zero is supplied, then the
         default linear spreading scheme is used (equivalent to
         supplying the value AST\_\_LINEAR).
      }
      \sstsubsection{
         params
      }{
         An optional pointer to an array of double which should contain
         any additional parameter values required by the pixel
         spreading scheme. If such parameters are required, this
         will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"}
         section below.

         If no additional parameters are required, this array is not
         used and a NULL pointer may be given.
      }
      \sstsubsection{
         flags
      }{
         The bitwise OR of a set of flag values which may be used to
         provide additional control over the rebinning operation. See
         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
         options available.  If no flag values are to be set, a value
         of zero should be given.
      }
      \sstsubsection{
         tol
      }{
         The maximum tolerable geometrical distortion which may be
         introduced as a result of approximating non-linear Mappings
         by a set of piece-wise linear transformations. This should be
         expressed as a displacement in pixels in the output grid\texttt{'} s
         coordinate system.

         If piece-wise linear approximation is not required, a value
         of zero may be given. This will ensure that the Mapping is
         used without any approximation, but may increase execution
         time.

         If the value is too high, discontinuities between the linear
         approximations used in adjacent panel will be higher, and may
         cause the edges of the panel to be visible when viewing the output
         image at high contrast. If this is a problem, reduce the
         tolerance value used.
      }
      \sstsubsection{
         maxpix
      }{
         A value which specifies an initial scale size (in pixels) for
         the adaptive algorithm which approximates non-linear Mappings
         with piece-wise linear transformations. Normally, this should
         be a large value (larger than any dimension of the region of
         the input grid being used). In this case, a first attempt to
         approximate the Mapping by a linear transformation will be
         made over the entire input region.

         If a smaller value is used, the input region will first be
         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
         pixels in any dimension. Only at this point will attempts at
         approximation commence.

         This value may occasionally be useful in preventing false
         convergence of the adaptive algorithm in cases where the
         Mapping appears approximately linear on large scales, but has
         irregularities (e.g. holes) on smaller scales. A value of,
         say, 50 to 100 pixels can also be employed as a safeguard in
         general-purpose software, since the effect on performance is
         minimal.

         If too small a value is given, it will have the effect of
         inhibiting linear approximation altogether (equivalent to
         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
         performance, accurate results will still be obtained.
      }
      \sstsubsection{
         badval
      }{
         This argument should have the same type as the elements of
         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
         data (bad pixels) in the input and output arrays.

         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
         (and \texttt{"} in\_var\texttt{"} ) array(s).

         In all cases, this value is also used to flag any output
         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
         rebined values could not be obtained (see the \texttt{"} Propagation
         of Missing Data\texttt{"}  section below for details of the
         circumstances under which this may occur).
      }
      \sstsubsection{
         ndim\_out
      }{
         The number of dimensions in the output grid. This should be
         at least one. It need not necessarily be equal to the number
         of dimensions in the input grid.
      }
      \sstsubsection{
         lbnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the output grid along each dimension.
      }
      \sstsubsection{
         ubnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the output grid along each dimension.

         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
         shape, size and coordinate system of the output grid in the
         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
         and coordinate system of the input grid.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the first pixel in the region
         of the input grid which is to be included in the rebined output
         array.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the last pixel in the region of
         the input grid which is to be included in the rebined output
         array.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
         position of a (hyper-)rectangular region of the input grid
         which is to be included in the rebined output array. This region
         should lie wholly within the extent of the input grid (as
         defined by the \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  arrays). Regions of
         the input grid lying outside this region will not be used.
      }
      \sstsubsection{
         out
      }{
         Pointer to an array, with one element for each pixel in the
         output grid, in which the rebined data values will be
         returned. The numerical type of this array should match that
         of the \texttt{"} in\texttt{"}  array, and the data storage order should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         out\_var
      }{
         An optional pointer to an array with the same type and size
         as the \texttt{"} out\texttt{"}  array. If given, this array will be used to
         return variance estimates for the rebined data values. This
         array will only be used if the \texttt{"} in\_var\texttt{"}  array has also been
         supplied.

         The output variance values will be calculated on the
         assumption that errors on the input data values are
         statistically independent and that their variance estimates
         may simply be summed (with appropriate weighting factors)
         when several input pixels contribute to an output data
         value. If this assumption is not valid, then the output error
         estimates may be biased. In addition, note that the
         statistical errors on neighbouring output data values (as
         well as the estimates of those errors) may often be
         correlated, even if the above assumption about the input data
         is correct, because of the pixel spreading schemes
         employed.

         If no output variance estimates are required, a NULL pointer
         should be given.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate rebinning function, you should
      replace $<$X$>$ in the generic function name astRebin$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astRebinD would be used to process \texttt{"} double\texttt{"}
      data, while astRebinI would be used to process \texttt{"} int\texttt{"}
      data, etc.

      Note that, unlike
      \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, the astRebin$<$X$>$
      set of functions does not yet support unsigned integer data types
      or integers of different sizes.
   }
   \sstdiytopic{
      Pixel Spreading Schemes
   }{
      The pixel spreading scheme specifies the Point Spread Function (PSF)
      applied to each input pixel value as it is copied into the output
      array. It can be thought of as the inverse of the sub-pixel
      interpolation schemes used by the
      astResample$<$X$>$
      group of functions. That is, in a sub-pixel interpolation scheme the
      kernel specifies the weight to assign to each input pixel when
      forming the weighted mean of the input pixels, whereas the kernel in a
      pixel spreading scheme specifies the fraction of the input data value
      which is to be assigned to each output pixel. As for interpolation, the
      choice of suitable pixel spreading scheme involves stricking a balance
      between schemes which tend to degrade sharp features in the data by
      smoothing them, and those which attempt to preserve sharp features but
      which often tend to introduce unwanted artifacts. See the
      astResample$<$X$>$
      documentation for further discussion.

      The binning algorithm used has the ability to introduce artifacts
      not seen when using a resampling algorithm. Particularly, when
      viewing the output image at high contrast, systems of curves lines
      covering the entire image may be visible. These are caused by a
      beating effect between the input pixel positions and the output pixels
      position, and their nature and strength depend critically upon the
      nature of the Mapping and the spreading function being used. In
      general, the nearest neighbour spreading function demonstrates this
      effect more clearly than the other functions, and for this reason
      should be used with caution.

      The following values (defined in the
      \texttt{"} ast.h\texttt{"}  header file)
      may be assigned to the
      \texttt{"} spread\texttt{"}
      parameter. See the
      astResample$<$X$>$
      documentation for details of these schemes including the use of the
      \texttt{"} fspread\texttt{"}  and \texttt{"} params\texttt{"}  parameters:

      \sstitemlist{

         \sstitem
         AST\_\_NEAREST

         \sstitem
         AST\_\_LINEAR

         \sstitem
         AST\_\_SINC

         \sstitem
         AST\_\_SINCSINC

         \sstitem
         AST\_\_SINCCOS

         \sstitem
         AST\_\_SINCGAUSS

         \sstitem
         AST\_\_SOMBCOS

      }
      In addition, the following schemes can be used with
      astRebin$<$X$>$ but not with astResample$<$X$>$:

      \sstitemlist{

         \sstitem
         AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k
         a positive constant determined by the full-width at half-maximum (FWHM).
         The FWHM should be supplied in units of output pixels by means of the
         \texttt{"} params[1]\texttt{"}
         value and should be at least 0.1. The
         \texttt{"} params[0]\texttt{"}
         value should be used to specify at what point the Gaussian is truncated
         to zero. This should be given as a number of output pixels on either
         side of the central output point in each dimension (the nearest integer
         value is used).
      }
   }
   \sstdiytopic{
      Control Flags
   }{
      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
      may be used to provide additional control over the rebinning
      process. Having selected a set of flags, you should supply the
      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:

      \sstitemlist{

         \sstitem
         AST\_\_USEBAD: Indicates that there may be bad pixels in the
         input array(s) which must be recognised by comparing with the
         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
         If this flag is not set, all input values are treated literally
         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
         values.
      }
   }
   \sstdiytopic{
      Propagation of Missing Data
   }{
      Instances of missing data (bad pixels) in the output grid are
      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
      array. These are produced if the sum of the weights of the
      contributing input pixels is less than
      \texttt{"} wlim\texttt{"} .

      An input pixel is considered bad (and is consequently ignored) if
      its
      data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
      set via the \texttt{"} flags\texttt{"}  parameter.

      In addition, associated output variance estimates (if
      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
      value in the \texttt{"} out\_var\texttt{"}  array for similar reasons.
   }
}
\sstroutine{
   astRebinSeq$<$X$>$
}{
   Rebin a region of a sequence of data grids
}{
   \sstdescription{
      This set of
      functions is identical to \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}
      except that the rebinned input data is added into the supplied
      output arrays, rather than simply over-writing the contents of the
      output arrays. Thus, by calling this
      function
      repeatedly, a sequence of input arrays can be rebinned and accumulated
      into a single output array, effectively forming a mosaic of the
      input data arrays.

      In addition, the weights associated with each output pixel are
      returned. The weight of an output pixel indicates the number of input
      pixels which have been accumulated in that output pixel. If the entire
      value of an input pixel is assigned to a single output pixel, then the
      weight of that output pixel is incremented by one. If some fraction of
      the value of an input pixel is assigned to an output pixel, then the
      weight of that output pixel is incremented by the fraction used.

      The start of a new sequence is indicated by specifying the
      AST\_\_REBININIT flag via the
      \texttt{"} flags\texttt{"}  parameter.
      This causes the supplied arrays to be filled with zeros before the
      rebinned input data is added into them. Subsequenct invocations
      within the same sequence should omit the AST\_\_REBININIT flag.

      The last call in a sequence is indicated by specifying the
      AST\_\_REBINEND flag. Depending on which flags are supplied, this may
      cause the output data and variance arrays to be normalised before
      being returned. This normalisation consists of dividing the data
      array by the weights array, and can eliminate artifacts which may be
      introduced into the rebinned data as a consequence of aliasing
      between the input and output grids. This results in each output
      pixel value being the weighted mean of the input pixel values that
      fall in the neighbourhood of the output pixel (rather like
      \htmlref{astResample$<$X$>$}{astResample$<$X$>$}).
      Optionally, these normalised
      values can then be multiplied by a scaling factor to ensure that the
      total data sum in any small area is unchanged. This scaling factor
      is equivalent to the number of input pixel values that fall into each
      output pixel. In addition to
      normalisation of the output data values, any output variances are
      also appropriately normalised, and any output data values with
      weight less than
      \texttt{"} wlim\texttt{"}  are set to \texttt{"} badval\texttt{"} .

      Output variances can be generated in two ways; by rebinning the supplied
      input variances with appropriate weights, or by finding the spread of
      input data values contributing to each output pixel (see the AST\_\_GENVAR
      and AST\_\_USEVAR flags).
   }
   \sstsynopsis{
      void astRebinSeq$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in,
                           const int lbnd\_in[], const int ubnd\_in[],
                           const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
                           int spread, const double params[], int flags,
                           double tol, int maxpix, $<$Xtype$>$ badval,
                           int ndim\_out, const int lbnd\_out[],
                           const int ubnd\_out[], const int lbnd[],
                           const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[],
                           double weights[], int64\_t $*$nused );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to a \htmlref{Mapping}{Mapping}, whose forward transformation will be
         used to transform the coordinates of pixels in the input
         grid into the coordinate system of the output grid.

         The number of input coordinates used by this Mapping (as
         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
         attribute) should match the number of output grid dimensions
         given by \texttt{"} ndim\_out\texttt{"} .
         If \texttt{"} in\texttt{"}  is NULL, the Mapping will not be used, but a valid
         Mapping must still be supplied.
      }
      \sstsubsection{
         wlim
      }{
         This value is only used if the AST\_\_REBINEND flag is specified
         via the
         \texttt{"} flags\texttt{"}  parameter.
         It gives the required number of input pixel values which must
         contribute to an output pixel (i.e. the output pixel weight) in
         order for the output pixel value to be considered valid. If the sum
         of the input pixel weights contributing to an output pixel is less
         than the supplied
         \texttt{"} wlim\texttt{"}
         value, then the output pixel value is returned set to the
         supplied bad value. If the supplied value is less than 1.0E-10
         then 1.0E-10 is used instead.
      }
      \sstsubsection{
         ndim\_in
      }{
         The number of dimensions in the input grid. This should be at
         least one.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         lbnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         ubnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         in
      }{
         Pointer to an array, with one element for each pixel in the
         input grid, containing the input data to be rebined.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astRebinSeqF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
         If a NULL pointer is supplied for \texttt{"} in\texttt{"} , then no data is added to
         the output arrays, but any initialisation or normalisation
         requested by \texttt{"} flags\texttt{"}  is still performed.
      }
      \sstsubsection{
         in\_var
      }{
         An optional
         pointer to a
         second array with the same size and type as the
         \texttt{"} in\texttt{"}
         array. If given, this should contain a set of non-negative values
         which represent estimates of the statistical variance associated
         with each element of the
         \texttt{"} in\texttt{"}
         array.
         If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no
         input variance estimates are required and this
         pointer
         will not be used.
         A NULL pointer
         may then be supplied.
      }
      \sstsubsection{
         spread
      }{
         This parameter specifies the scheme to be used for dividing
         each input data value up amongst the corresponding output pixels.
         It may be used to select
         from a set of pre-defined schemes by supplying one of the
         values described in the \texttt{"} Pixel Spreading Schemes\texttt{"}
         section in the description of the
         astRebin$<$X$>$ functions.
         If a value of zero is supplied, then the default linear spreading
         scheme is used (equivalent to supplying the value AST\_\_LINEAR).
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         params
      }{
         An optional pointer to an array of double which should contain
         any additional parameter values required by the pixel
         spreading scheme. If such parameters are required, this
         will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"}  section in the
         description of the
         astRebin$<$X$>$ functions.

         If no additional parameters are required, this array is not
         used and a NULL pointer may be given.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         flags
      }{
         The bitwise OR of a set of flag values which may be used to
         provide additional control over the rebinning operation. See
         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
         options available.  If no flag values are to be set, a value
         of zero should be given.
      }
      \sstsubsection{
         tol
      }{
         The maximum tolerable geometrical distortion which may be
         introduced as a result of approximating non-linear Mappings
         by a set of piece-wise linear transformations. This should be
         expressed as a displacement in pixels in the output grid\texttt{'} s
         coordinate system.

         If piece-wise linear approximation is not required, a value
         of zero may be given. This will ensure that the Mapping is
         used without any approximation, but may increase execution
         time.

         If the value is too high, discontinuities between the linear
         approximations used in adjacent panel will be higher, and may
         cause the edges of the panel to be visible when viewing the output
         image at high contrast. If this is a problem, reduce the
         tolerance value used.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         maxpix
      }{
         A value which specifies an initial scale size (in pixels) for
         the adaptive algorithm which approximates non-linear Mappings
         with piece-wise linear transformations. Normally, this should
         be a large value (larger than any dimension of the region of
         the input grid being used). In this case, a first attempt to
         approximate the Mapping by a linear transformation will be
         made over the entire input region.

         If a smaller value is used, the input region will first be
         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
         pixels in any dimension. Only at this point will attempts at
         approximation commence.

         This value may occasionally be useful in preventing false
         convergence of the adaptive algorithm in cases where the
         Mapping appears approximately linear on large scales, but has
         irregularities (e.g. holes) on smaller scales. A value of,
         say, 50 to 100 pixels can also be employed as a safeguard in
         general-purpose software, since the effect on performance is
         minimal.

         If too small a value is given, it will have the effect of
         inhibiting linear approximation altogether (equivalent to
         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
         performance, accurate results will still be obtained.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         badval
      }{
         This argument should have the same type as the elements of
         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
         data (bad pixels) in the input and output arrays.

         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
         (and \texttt{"} in\_var\texttt{"} ) array(s).

         In all cases, this value is also used to flag any output
         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
         rebined values could not be obtained (see the \texttt{"} Propagation
         of Missing Data\texttt{"}  section below for details of the
         circumstances under which this may occur).
      }
      \sstsubsection{
         ndim\_out
      }{
         The number of dimensions in the output grid. This should be
         at least one. It need not necessarily be equal to the number
         of dimensions in the input grid.
      }
      \sstsubsection{
         lbnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the output grid along each dimension.
      }
      \sstsubsection{
         ubnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the output grid along each dimension.

         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
         shape, size and coordinate system of the output grid in the
         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
         and coordinate system of the input grid.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the first pixel in the region
         of the input grid which is to be included in the rebined output
         array.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the last pixel in the region of
         the input grid which is to be included in the rebined output
         array.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
         position of a (hyper-)rectangular region of the input grid
         which is to be included in the rebined output array. This region
         should lie wholly within the extent of the input grid (as
         defined by the \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  arrays). Regions of
         the input grid lying outside this region will not be used.
         Not used if \texttt{"} in\texttt{"}  is NULL.
      }
      \sstsubsection{
         out
      }{
         Pointer to an array, with one element for each pixel in the
         output grid. The rebined data values will be added into the
         original contents of this array. The numerical type of this array
         should match that of the
         \texttt{"} in\texttt{"}  array, and the data storage order should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         out\_var
      }{
         A
         pointer to an
         array with the same type and size as the
         \texttt{"} out\texttt{"}
         array. This
         pointer
         will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set
         in which case variance estimates for the rebined data values will
         be added into the array. If neither the AST\_\_USEVAR flag nor the
         AST\_\_GENVAR flag is set, no output variance estimates will be
         calculated and this
         pointer
         will not be used. A
         NULL pointer
         may then be supplied.
      }
      \sstsubsection{
         weights
      }{
         Pointer to an array of double,
         with one or two elements for each pixel in the output grid,
         depending on whether or not the AST\_\_GENVAR flag has been supplied
         via the
         \texttt{"} flags\texttt{"}  parameter.
         If AST\_\_GENVAR has not been specified then the array should have
         one element for each output pixel, and it will be used to
         accumulate the weight associated with each output pixel.
         If AST\_\_GENVAR has been specified then the array should have
         two elements for each output pixel. The first half of the array
         is again used to accumulate the weight associated with each output
         pixel, and the second half is used to accumulate the square of
         the weights. In each half, the data storage order should be such that
         the index of the first grid dimension varies most rapidly and that of
         the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         nused
      }{
         A pointer to an int64\_t containing the
         number of input data values that have been added into the output
         array so far. The supplied value is incremented on exit by the
         number of input values used. The value is initially set to zero
         if the AST\_\_REBININIT flag is set in
         \texttt{"} flags\texttt{"} .
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate rebinning function, you should
      replace $<$X$>$ in the generic function name astRebinSeq$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         I: int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astRebinSeqD would be used to process \texttt{"} double\texttt{"}
      data, while astRebinSeqI would be used to process \texttt{"} int\texttt{"}
      data, etc.

      Note that, unlike
      astResample$<$X$>$, the astRebinSeq$<$X$>$
      set of functions does not yet support unsigned integer data types
      or integers of different sizes.
   }
   \sstdiytopic{
      Control Flags
   }{
      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
      may be used to provide additional control over the rebinning
      process. Having selected a set of flags, you should supply the
      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:

      \sstitemlist{

         \sstitem
         AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates
         that the supplied
         \texttt{"} out\texttt{"} , \texttt{"} out\_var\texttt{"}  and \texttt{"} weights\texttt{"}
         arrays should be filled with zeros (thus over-writing any supplied
         values) before adding the rebinned input data into them. This flag
         should be used when rebinning the first input array in a sequence.

         \sstitem
         AST\_\_REBINEND: Used to mark the last call in a sequence. It causes
         each value in the
         \texttt{"} out\texttt{"}  and \texttt{"} out\_var\texttt{"}
         arrays to be divided by a normalisation factor before being
         returned. The normalisation factor for each output data value is just
         the corresponding value from the weights array. The normalisation
         factor for each output variance value is the square of the data value
         normalisation factor (see also AST\_\_CONSERVEFLUX). It also causes
         output data values to be set bad if the corresponding weight is less
         than the value supplied for
         parameter \texttt{"} wlim\texttt{"} .
         It also causes any temporary values stored in the output variance array
         (see flag AST\_\_GENVAR below) to be converted into usable variance values.
         Note, this flag is ignored if the AST\_\_NONORM flag is set.

         \sstitem
         AST\_\_USEBAD: Indicates that there may be bad pixels in the
         input array(s) which must be recognised by comparing with the
         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
         If this flag is not set, all input values are treated literally
         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
         values.

         \sstitem
         AST\_\_USEVAR: Indicates that output variance estimates should be
         created by rebinning the supplied input variance estimates. An
         error will be reported if both this flag and the AST\_\_GENVAR flag
         are supplied.

         \sstitem
         AST\_\_GENVAR: Indicates that output variance estimates should be
         created based on the spread of input data values contributing to each
         output pixel. An error will be reported if both this flag and the
         AST\_\_USEVAR flag are supplied. If the AST\_\_GENVAR flag is specified,
         the supplied output variance array is first used as a work array to
         accumulate the temporary values needed to generate the output
         variances. When the sequence ends (as indicated by the
         AST\_\_REBINEND flag), the contents of the output variance array are
         converted into the required variance estimates. If the generation of
         such output variances is required, this flag should be used on every
         invocation of this
         function
         within a sequence, and any supplied input variances will have no effect
         on the output variances (although input variances will still be used
         to weight the input data if the AST\_\_VARWGT flag is also supplied).
         The statistical meaning of these output varianes is determined by
         the presence or absence of the AST\_\_DISVAR flag (see below).

         \sstitem
         AST\_\_DISVAR: This flag is ignored unless the AST\_\_GENVAR flag
         has also been specified. It determines the statistical meaning of
         the generated output variances. If AST\_\_DISVAR is not specified,
         generated variances represent variances on the output mean  values. If
         AST\_\_DISVAR is specified, the generated variances represent the variance
         of the distribution from which the input values were taken. Each output
         variance created with AST\_\_DISVAR will be larger than that created
         without AST\_\_DISVAR by a factor equal to the number of input samples
         that contribute to the output sample.

         \sstitem
         AST\_\_VARWGT: Indicates that the input data should be weighted by
         the reciprocal of the input variances. Otherwise, all input data are
         given equal weight. If this flag is specified, the calculation of the
         output variances (if any) is modified to take account of the
         varying weights assigned to the input data values.

         \sstitem
         AST\_\_NONORM: If the simple unnormalised sum of all input data falling
         in each output pixel is required, then this flag should be set on
         each call in the sequence and the AST\_\_REBINEND should not be used
         on the last call. In this case
         NULL pointers can be supplied for \texttt{"} weights\texttt{"}  and \texttt{"} nused\texttt{"} .
         This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR
         or AST\_\_VARWGT flag.

         \sstitem
         AST\_\_CONSERVEFLUX: Indicates that the normalized output pixel values
         generated by the AST\_\_REBINEND flag should be scaled in such a way as
         to preserve the total data value in a feature on the sky. Without this
         flag, each normalised output pixel value represents a weighted mean
         of the input data values around the corresponding input position.
         is appropriate if the input data represents the spatial density of
         some quantity (e.g. surface brightness in Janskys per square
         arc-second) because the output pixel values will have the same
         normalisation and units as the input pixel values. However, if the
         input data values represent flux (or some other physical quantity)
         per pixel, then the AST\_\_CONSERVEFLUX flag could be of use. It causes
         each output pixel value to be scaled by the ratio of the output pixel
         size to the input pixel size.

      }
      This flag can only be used if the Mapping is successfully approximated
      by one or more linear transformations. Thus an error will be reported
      if it used when the
      \texttt{"} tol\texttt{"}  parameter
      is set to zero (which stops the use of linear approximations), or
      if the Mapping is too non-linear to be approximated by a piece-wise
      linear transformation. The ratio of output to input pixel size is
      evaluated once for each panel of the piece-wise linear approximation to
      the Mapping, and is assumed to be constant for all output pixels in the
      panel. The scaling factors for adjacent panels will in general
      differ slightly, and so the joints between panels may be visible when
      viewing the output image at high contrast. If this is a problem,
      reduce the value of the
      \texttt{"} tol\texttt{"}  parameter
      until the difference between adjacent panels is sufficiently small
      to be insignificant.

      This flag should normally be supplied on each invocation of
      astRebinSeq$<$X$>$
      within a given sequence.

      Note, this flag cannot be used in conjunction with the AST\_\_NOSCALE
      flag (an error will be reported if both flags are specified).
   }
   \sstdiytopic{
      Propagation of Missing Data
   }{
      Instances of missing data (bad pixels) in the output grid are
      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
      array. These are only produced if the AST\_\_REBINEND flag is
      specified and a pixel has zero weight.

      An input pixel is considered bad (and is consequently ignored) if
      its
      data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
      set via the \texttt{"} flags\texttt{"}  parameter.

      In addition, associated output variance estimates (if
      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
      value in the \texttt{"} out\_var\texttt{"}  array for similar reasons.
   }
}
\sstroutine{
   astRegionOutline
}{
   Draw the outline of an AST Region
}{
   \sstdescription{
      This function draws an outline around the supplied AST \htmlref{Region}{Region} object.
   }
   \sstsynopsis{
      void astRegionOutline( AstPlot $*$this, AstRegion $*$region )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Plot}{Plot}.
      }
      \sstsubsection{
         region
      }{
         Pointer to the Region.
      }
   }
}
\sstroutine{
   astRemapFrame
}{
   Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet
}{
   \sstdescription{
      This function modifies the relationship (i.e. \htmlref{Mapping}{Mapping}) between a
      specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet} and the other Frames in that
      FrameSet.

      Typically, this might be required if the FrameSet has been used
      to calibrate (say) an image, and that image is re-binned. The
      Frame describing the image will then have undergone a coordinate
      transformation, and this should be communicated to the associated
      FrameSet using this function.
   }
   \sstsynopsis{
      void astRemapFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe
      }{
         The index within the FrameSet of the Frame to be modified.
         This value should lie in the range from 1 to the number of
         Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
      }
      \sstsubsection{
         map
      }{
         Pointer to a Mapping whose forward transformation converts
         coordinate values from the original coordinate system
         described by the Frame to the new one, and whose inverse
         transformation converts in the opposite direction.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
         Frame respectively.

         \sstitem
         The relationship between the selected Frame and any other
         Frame within the FrameSet will be modified by this function,
         but the relationship between all other Frames in the FrameSet
         remains unchanged.

         \sstitem
         The number of input coordinate values accepted by the Mapping
         (its \htmlref{Nin}{Nin} attribute) and the number of output coordinate values
         generated (its \htmlref{Nout}{Nout} attribute) must be equal and must match the
         number of axes in the Frame being modified.

         \sstitem
         If a simple change of axis order is required, then the
         \htmlref{astPermAxes}{astPermAxes} function may provide a more straightforward method
         of making the required changes to the FrameSet.

         \sstitem
         This function cannot be used to change the number of Frame
         axes. To achieve this, a new Frame must be added to the FrameSet
         (\htmlref{astAddFrame}{astAddFrame}) and the original one removed if necessary
         (\htmlref{astRemoveFrame}{astRemoveFrame}).

         \sstitem
         Any variant Mappings associated with the remapped Frame (except
         for the current variant) will be lost as a consequence of calling this
         method (see attribute \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ).
      }
   }
}
\sstroutine{
   astRemoveColumn
}{
   Remove a column from a table
}{
   \sstdescription{
      This function removes a specified column from the supplied table.
      The
      function
      returns without action if the named column does not exist in the
      \htmlref{Table}{Table} (no error is reported).
   }
   \sstsynopsis{
      void astRemoveColumn( AstTable $*$this, const char $*$name )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         name
      }{
         The column name. Trailing spaces are ignored (all other spaces
         are significant). Case is significant.
      }
   }
}
\sstroutine{
   astRemoveFrame
}{
   Remove a Frame from a FrameSet
}{
   \sstdescription{
      This function removes a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet}. All other Frames
      in the FrameSet have their indices re-numbered from one (if
      necessary), but are otherwise unchanged.
   }
   \sstsynopsis{
      void astRemoveFrame( AstFrameSet $*$this, int iframe )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FrameSet.
      }
      \sstsubsection{
         iframe
      }{
         The index within the FrameSet of the Frame to be removed.
         This value should lie in the range from 1 to the number of
         Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Removing a Frame from a FrameSet does not affect the
         relationship between other Frames in the FrameSet, even if they
         originally depended on the Frame being removed.

         \sstitem
         The number of Frames in a FrameSet cannot be reduced to zero.
         An error will result if an attempt is made to remove the only
         remaining Frame.

         \sstitem
         A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
         Frame respectively.

         \sstitem
         If a FrameSet\texttt{'} s base or current Frame is removed, the \htmlref{Base}{Base} or
         \htmlref{Current}{Current} attribute (respectively) of the FrameSet will have its
         value cleared, so that another Frame will then assume its role
         by default.

         \sstitem
         If any other Frame is removed, the base and current Frames
         will remain the same. To ensure this, the Base and/or Current
         attributes of the FrameSet will be changed, if necessary, to
         reflect any change in the indices of these Frames.
      }
   }
}
\sstroutine{
   astRemoveParameter
}{
   Remove a global parameter from a table
}{
   \sstdescription{
      This function removes a specified global parameter from the supplied table.
      The
      function
      returns without action if the named parameter does not exist in the
      \htmlref{Table}{Table} (no error is reported).
   }
   \sstsynopsis{
      void astRemoveParameter( AstTable $*$this, const char $*$name )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         name
      }{
         The parameter name. Trailing spaces are ignored (all other spaces
         are significant). Case is significant.
      }
   }
}
\sstroutine{
   astRemoveRegions
}{
   Remove any Regions from a Mapping
}{
   \sstdescription{
      This function searches the suppliedMapping (which may be a
      compound \htmlref{Mapping}{Mapping} such as a \htmlref{CmpMap}{CmpMap}) for any component Mappings
      that are instances of the AST \htmlref{Region}{Region} class. It then creates a new
      Mapping from which all Regions have been removed. If a Region
      cannot simply be removed (for instance, if it is a component of a
      parallel CmpMap), then it is replaced with an equivalent \htmlref{UnitMap}{UnitMap}
      in the returned Mapping.
   }
   \sstsynopsis{
      AstMapping $*$astRemoveRegions( AstMapping $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the original Mapping.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         If the supplied Mapping is a CmpFrame, any component Frames that
         are instances of the Region class are replaced by the equivalent
         \htmlref{Frame}{Frame}.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         If the supplied Mapping is a FrameSet, the returned Mapping
         will be a copy of the supplied FrameSet in which Regions have
         been removed from all the inter-Frame Mappings, and any Frames
         which are instances of the Region class are repalced by the
         equivalent Frame.
      }
      \sstsubsection{
         Mapping
      }{
         This function applies to all Mappings.
      }
      \sstsubsection{
         Region
      }{
         If the supplied Mapping is a Region, the returned Mapping will
         be the equivalent Frame.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astRemoveRegions()
      }{
         A new pointer to the (possibly modified) Mapping.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function can safely be applied even to Mappings which
         contain no Regions. If no Regions are found, it
         behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the
         original Mapping.

         \sstitem
         The Mapping returned by this function may not be independent
         of the original (even if some Regions were removed), and
         modifying it may therefore result in indirect modification of
         the original. If a completely independent result is required, a
         copy should be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astRemoveRow
}{
   Remove a row from a table
}{
   \sstdescription{
      This function removes a specified row from the supplied table.
      The
      function
      returns without action if the row does not exist in the
      \htmlref{Table}{Table} (no error is reported).
   }
   \sstsynopsis{
      void astRemoveRow( AstTable $*$this, int index )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Table.
      }
      \sstsubsection{
         index
      }{
         The index of the row to be removed. The first row has index 1.
      }
   }
}
\sstroutine{
   astRemoveTables
}{
   Remove one or more tables from a FitsChan
}{
   \sstdescription{
      This function
      removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error
      is reported if any the tables do not exist).
   }
   \sstsynopsis{
      void astRemoveTables( AstFitsChan $*$this, const char $*$key )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         key
      }{
         The key indicating which tables to exist. A single key or a
         comma-separated list of keys can be supplied. If a blank string
         is supplied, all tables are removed.
      }
   }
}
\sstroutine{
   astResample$<$X$>$
}{
   Resample a region of a data grid
}{
   \sstdescription{
      This is a set of functions for resampling gridded data (e.g. an
      image) under the control of a geometrical transformation, which
      is specified by a \htmlref{Mapping}{Mapping}.  The functions operate on a pair of
      data grids (input and output), each of which may have any number
      of dimensions. Resampling may be restricted to a specified
      region of the output grid. An associated grid of error estimates
      associated with the input data may also be supplied (in the form
      of variance values), so as to produce error estimates for the
      resampled output data. Propagation of missing data (bad pixels)
      is supported.

      You should use a resampling function which matches the numerical
      type of the data you are processing by replacing $<$X$>$ in
      the generic function name astResample$<$X$>$ by an appropriate 1- or
      2-character type code. For example, if you are resampling data
      with type \texttt{"} float\texttt{"} , you should use the function astResampleF (see
      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
      other numerical types).

      Resampling of the grid of input data is performed by
      transforming the coordinates of the centre of each output grid
      element (or pixel) into the coordinate system of the input grid.
      Since the resulting coordinates will not, in general, coincide
      with the centre of an input pixel, sub-pixel interpolation is
      performed between the neighbouring input pixels. This produces a
      resampled value which is then assigned to the output pixel. A
      choice of sub-pixel interpolation schemes is provided, but you
      may also implement your own.

      This algorithm samples the input data value, it does not integrate
      it. Thus total data value in the input image will not, in general,
      be conserved. However, an option is provided (see the \texttt{"} Control Flags\texttt{"}
      section below) which can produce approximate flux conservation by
      scaling the output values using the ratio of the output pixel size
      to the input pixel size. However, if accurate flux conservation is
      important to you, consder using the
      \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} or \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} family of functions
      instead.

      Output pixel coordinates are transformed into the coordinate
      system of the input grid using the inverse transformation of the
      Mapping which is supplied. This means that geometrical features
      in the input data are subjected to the Mapping\texttt{'} s forward
      transformation as they are transferred from the input to the
      output grid (although the Mapping\texttt{'} s forward transformation is
      not explicitly used).

      In practice, transforming the coordinates of every pixel of a
      large data grid can be time-consuming, especially if the Mapping
      involves complicated functions, such as sky projections. To
      improve performance, it is therefore possible to approximate
      non-linear Mappings by a set of linear transformations which are
      applied piece-wise to separate sub-regions of the data. This
      approximation process is applied automatically by an adaptive
      algorithm, under control of an accuracy criterion which
      expresses the maximum tolerable geometrical distortion which may
      be introduced, as a fraction of a pixel.

      This algorithm first attempts to approximate the Mapping with a
      linear transformation applied over the whole region of the
      output grid which is being used. If this proves to be
      insufficiently accurate, the output region is sub-divided into
      two along its largest dimension and the process is repeated
      within each of the resulting sub-regions. This process of
      sub-division continues until a sufficiently good linear
      approximation is found, or the region to which it is being
      applied becomes too small (in which case the original Mapping is
      used directly).
   }
   \sstsynopsis{
      int astResample$<$X$>$( AstMapping $*$this, int ndim\_in,
                          const int lbnd\_in[], const int ubnd\_in[],
                          const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
                          int interp, void ($*$ finterp)( void ),
                          const double params[], int flags,
                          double tol, int maxpix,
                          $<$Xtype$>$ badval, int ndim\_out,
                          const int lbnd\_out[], const int ubnd\_out[],
                          const int lbnd[], const int ubnd[],
                          $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to a Mapping, whose inverse transformation will be
         used to transform the coordinates of pixels in the output
         grid into the coordinate system of the input grid. This
         yields the positions which are used to obtain resampled
         values by sub-pixel interpolation within the input grid.

         The number of input coordinates used by this Mapping (as
         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
         attribute) should match the number of output grid dimensions
         given by \texttt{"} ndim\_out\texttt{"} .
      }
      \sstsubsection{
         ndim\_in
      }{
         The number of dimensions in the input grid. This should be at
         least one.
      }
      \sstsubsection{
         lbnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre.
      }
      \sstsubsection{
         in
      }{
         Pointer to an array, with one element for each pixel in the
         input grid, containing the input data to be resampled.  The
         numerical type of this array should match the 1- or
         2-character type code appended to the function name (e.g. if
         you are using astResampleF, the type of each array element
         should be \texttt{"} float\texttt{"} ).

         The storage order of data within this array should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         in\_var
      }{
         An optional pointer to a second array with the same size and
         type as the \texttt{"} in\texttt{"}  array. If given, this should contain a set
         of non-negative values which represent estimates of the
         statistical variance associated with each element of the \texttt{"} in\texttt{"}
         array. If this array is supplied (together with the
         corresponding \texttt{"} out\_var\texttt{"}  array), then estimates of the
         variance of the resampled output data will be calculated.

         If no input variance estimates are being provided, a NULL
         pointer should be given.
      }
      \sstsubsection{
         interp
      }{
         This parameter specifies the scheme to be used for sub-pixel
         interpolation within the input grid. It may be used to select
         from a set of pre-defined schemes by supplying one of the
         values described in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}
         section below.  If a value of zero is supplied, then the
         default linear interpolation scheme is used (equivalent to
         supplying the value AST\_\_LINEAR).

         Alternatively, you may supply a value which indicates that
         you will provide your own function to perform sub-pixel
         interpolation by means of the \texttt{"} finterp \texttt{"}  parameter. Again, see
         the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}  section below for
         details.
      }
      \sstsubsection{
         finterp
      }{
         If the value given for the \texttt{"} interp\texttt{"}  parameter indicates that
         you will provide your own function for sub-pixel
         interpolation, then a pointer to that function should be
         given here. For details of the interface which the function
         should have (several are possible, depending on the value of
         \texttt{"} interp\texttt{"} ), see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}  section
         below.

         If the \texttt{"} interp\texttt{"}  parameter has any other value, corresponding
         to one of the pre-defined interpolation schemes, then this
         function will not be used and you may supply a NULL pointer.
      }
      \sstsubsection{
         params
      }{
         An optional pointer to an array of double which should contain
         any additional parameter values required by the sub-pixel
         interpolation scheme. If such parameters are required, this
         will be noted in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}
         section below (you may also use this array to pass values
         to your own interpolation function).

         If no additional parameters are required, this array is not
         used and a NULL pointer may be given.
      }
      \sstsubsection{
         flags
      }{
         The bitwise OR of a set of flag values which may be used to
         provide additional control over the resampling operation. See
         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
         options available.  If no flag values are to be set, a value
         of zero should be given.
      }
      \sstsubsection{
         tol
      }{
         The maximum tolerable geometrical distortion which may be
         introduced as a result of approximating non-linear Mappings
         by a set of piece-wise linear transformations. This should be
         expressed as a displacement in pixels in the input grid\texttt{'} s
         coordinate system.

         If piece-wise linear approximation is not required, a value
         of zero may be given. This will ensure that the Mapping is
         used without any approximation, but may increase execution
         time.
      }
      \sstsubsection{
         maxpix
      }{
         A value which specifies an initial scale size (in pixels) for
         the adaptive algorithm which approximates non-linear Mappings
         with piece-wise linear transformations. Normally, this should
         be a large value (larger than any dimension of the region of
         the output grid being used). In this case, a first attempt to
         approximate the Mapping by a linear transformation will be
         made over the entire output region.

         If a smaller value is used, the output region will first be
         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
         pixels in any dimension. Only at this point will attempts at
         approximation commence.

         This value may occasionally be useful in preventing false
         convergence of the adaptive algorithm in cases where the
         Mapping appears approximately linear on large scales, but has
         irregularities (e.g. holes) on smaller scales. A value of,
         say, 50 to 100 pixels can also be employed as a safeguard in
         general-purpose software, since the effect on performance is
         minimal.

         If too small a value is given, it will have the effect of
         inhibiting linear approximation altogether (equivalent to
         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
         performance, accurate results will still be obtained.
      }
      \sstsubsection{
         badval
      }{
         This argument should have the same type as the elements of
         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
         data (bad pixels) in the input and output arrays.

         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
         (and \texttt{"} in\_var\texttt{"} ) array(s).

         Unless the AST\_\_NOBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
         this value is also used to flag any output
         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
         resampled values could not be obtained (see the \texttt{"} Propagation
         of Missing Data\texttt{"}  section below for details of the
         circumstances under which this may occur). The astResample$<$X$>$
         function return value indicates whether any such values have
         been produced. If the AST\_\_NOBAD flag is set. then output array
         elements for which no resampled value could be obtained are
         left set to the value they had on entry to this function.
      }
      \sstsubsection{
         ndim\_out
      }{
         The number of dimensions in the output grid. This should be
         at least one. It need not necessarily be equal to the number
         of dimensions in the input grid.
      }
      \sstsubsection{
         lbnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the output grid along each dimension.
      }
      \sstsubsection{
         ubnd\_out
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the output grid along each dimension.

         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
         shape, size and coordinate system of the output grid in the
         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
         and coordinate system of the input grid.
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the first pixel in the region
         of the output grid for which a resampled value is to be
         calculated.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
         containing the coordinates of the last pixel in the region of
         the output grid for which a resampled value is to be
         calculated.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
         position of a (hyper-)rectangular region of the output grid
         for which resampled values should be produced. This region
         should lie wholly within the extent of the output grid (as
         defined by the \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  arrays). Regions of
         the output grid lying outside this region will not be
         modified.
      }
      \sstsubsection{
         out
      }{
         Pointer to an array, with one element for each pixel in the
         output grid, into which the resampled data values will be
         returned. The numerical type of this array should match that
         of the \texttt{"} in\texttt{"}  array, and the data storage order should be such
         that the index of the first grid dimension varies most
         rapidly and that of the final dimension least rapidly
         (i.e. Fortran array indexing is used).
      }
      \sstsubsection{
         out\_var
      }{
         An optional pointer to an array with the same type and size
         as the \texttt{"} out\texttt{"}  array. If given, this array will be used to
         return variance estimates for the resampled data values. This
         array will only be used if the \texttt{"} in\_var\texttt{"}  array has also been
         supplied.

         The output variance values will be calculated on the
         assumption that errors on the input data values are
         statistically independent and that their variance estimates
         may simply be summed (with appropriate weighting factors)
         when several input pixels contribute to an output data
         value. If this assumption is not valid, then the output error
         estimates may be biased. In addition, note that the
         statistical errors on neighbouring output data values (as
         well as the estimates of those errors) may often be
         correlated, even if the above assumption about the input data
         is correct, because of the sub-pixel interpolation schemes
         employed.

         If no output variance estimates are required, a NULL pointer
         should be given.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astResample$<$X$>$()
      }{
         The number of output pixels for which no valid resampled value
         could be obtained. Thus, in the absence of any error, a returned
         value of zero indicates that all the required output pixels
         received valid resampled data values (and variances). See the
         \texttt{"} badval\texttt{"}  and \texttt{"} flags\texttt{"}  parameters.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero will be returned if this function is invoked
         with the global error status set, or if it should fail for any
         reason.
      }
   }
   \sstdiytopic{
      Data Type Codes
   }{
      To select the appropriate resampling function, you should
      replace $<$X$>$ in the generic function name astResample$<$X$>$ with a
      1- or 2-character data type code, so as to match the numerical
      type $<$Xtype$>$ of the data you are processing, as follows:
      \sstitemlist{

         \sstitem
         D: double

         \sstitem
         F: float

         \sstitem
         L: long int (may be 32 or 64 bit)

         \sstitem
         K: 64 bit int

         \sstitem
         UL: unsigned long int (may be 32 or 64 bit)

         \sstitem
         UK: unsigned 64 bit int

         \sstitem
         I: int

         \sstitem
         UI: unsigned int

         \sstitem
         S: short int

         \sstitem
         US: unsigned short int

         \sstitem
         B: byte (signed char)

         \sstitem
         UB: unsigned byte (unsigned char)

      }
      For example, astResampleD would be used to process \texttt{"} double\texttt{"}
      data, while astResampleS would be used to process \texttt{"} short int\texttt{"}
      data, etc.
   }
   \sstdiytopic{
      Sub-Pixel Interpolation Schemes
   }{
      There is no such thing as a perfect sub-pixel interpolation
      scheme and, in practice, all resampling will result in some
      degradation of gridded data.  A range of schemes is therefore
      provided, from which you can choose the one which best suits
      your needs.

      In general, a balance must be struck between schemes which tend
      to degrade sharp features in the data by smoothing them, and
      those which attempt to preserve sharp features. The latter will
      often tend to introduce unwanted oscillations, typically visible
      as \texttt{"} ringing\texttt{"}  around sharp features and edges, especially if the
      data are under-sampled (i.e. if the sharpest features are less
      than about two pixels across). In practice, a good interpolation
      scheme is likely to be a compromise and may exhibit some aspects
      of both these features.

      For under-sampled data, some interpolation schemes may appear to
      preserve data resolution because they transform single input
      pixels into single output pixels, rather than spreading their
      data between several output pixels. While this may look
      better cosmetically, it can result in a geometrical shift of
      sharp features in the data. You should beware of this if you
      plan to use such features (e.g.) for image alignment.

      The following are two easy-to-use sub-pixel interpolation
      schemes which are generally applicable. They are selected by
      supplying the appropriate value (defined in the \texttt{"} ast.h\texttt{"}  header
      file) via the \texttt{"} interp\texttt{"}  parameter. In these cases, the \texttt{"} finterp\texttt{"}
      and \texttt{"} params\texttt{"}  parameters are not used:

      \sstitemlist{

         \sstitem
         AST\_\_NEAREST: This is the simplest possible scheme, in which
         the value of the input pixel with the nearest centre to the
         interpolation point is used. This is very quick to execute and
         will preserve single-pixel features in the data, but may
         displace them by up to half their width along each dimension. It
         often gives a good cosmetic result, so is useful for quick-look
         processing, but is unsuitable if accurate geometrical
         transformation is required.

         \sstitem
         AST\_\_LINEAR: This is the default scheme, which uses linear
         interpolation between the nearest neighbouring pixels in the
         input grid (there are two neighbours in one dimension, four
         neighbours in two dimensions, eight in three dimensions,
         etc.). It is superior to the nearest-pixel scheme (above) in not
         displacing features in the data, yet it still executes fairly
         rapidly. It is generally a safe choice if you do not have any
         particular reason to favour another scheme, since it cannot
         introduce oscillations. However, it does introduce some spatial
         smoothing which varies according to the distance of the
         interpolation point from the neighbouring pixels. This can
         degrade the shape of sharp features in the data in a
         position-dependent way. It may also show in the output variance
         grid (if used) as a pattern of stripes or fringes.

      }
      An alternative set of interpolation schemes is based on forming
      the interpolated value from the weighted sum of a set of
      surrounding pixel values (not necessarily just the nearest
      neighbours). This approach has its origins in the theory of
      digital filtering, in which interpolated values are obtained by
      conceptually passing the sampled data (represented by a grid of
      delta functions) through a linear filter which implements a
      convolution. Because the convolution kernel is continuous, the
      convolution yields a continuous function which may then be
      evaluated at fractional pixel positions. The (possibly
      multi-dimensional) kernel is usually regarded as \texttt{"} separable\texttt{"}  and
      formed from the product of a set of identical 1-dimensional
      kernel functions, evaluated along each dimension. Different
      interpolation schemes are then distinguished by the choice of
      this 1-dimensional interpolation kernel. The number of
      surrounding pixels which contribute to the result may also be
      varied.

      From a practical standpoint, it is useful to divide the weighted
      sum of pixel values by the sum of the weights when determining
      the interpolated value.  Strictly, this means that a true
      convolution is no longer being performed. However, the
      distinction is rarely important in practice because (for
      slightly subtle reasons) the sum of weights is always
      approximately constant for good interpolation kernels. The
      advantage of this technique, which is used here, is that it can
      easily accommodate missing data and tends to minimise unwanted
      oscillations at the edges of the data grid.

      In the following schemes, which are based on a 1-dimensional
      interpolation kernel, the first element of the \texttt{"} params\texttt{"}  array
      should be used to specify how many pixels are to contribute to the
      interpolated result on either side of the interpolation point in
      each dimension (the nearest integer value is used). Execution time
      increases rapidly with this number. Typically, a value of 2 is
      appropriate and the minimum value used will be 1 (i.e. two pixels
      altogether, one on either side of the interpolation point).
      A value of zero or less may be given for \texttt{"} params[0]\texttt{"}
      to indicate that a suitable number of pixels should be calculated
      automatically.

      In each of these cases, the \texttt{"} finterp\texttt{"}  parameter is not used:

      \sstitemlist{

         \sstitem
         AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with
         k a positive constant. The full-width at half-maximum (FWHM) is
         given by
         \texttt{"} params[1]\texttt{"}
         to zero will select the number of contributing pixels so as to utilise
         the width of the kernel out to where the envelope declines to 1\% of its
         maximum value). This kernel suppresses noise at the expense of
         smoothing the output array.

         \sstitem
         AST\_\_SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the
         pixel offset from the interpolation point and sinc(z)=sin(z)/z. This
         sometimes features as an \texttt{"} optimal\texttt{"}  interpolation kernel in books on
         image processing. Its supposed optimality depends on the assumption
         that the data are band-limited (i.e. have no spatial frequencies above
         a certain value) and are adequately sampled. In practice, astronomical
         data rarely meet these requirements. In addition, high spatial
         frequencies are often present due (e.g.) to image defects and cosmic
         ray events. Consequently, substantial ringing can be experienced with
         this kernel. The kernel also decays slowly with distance, so that
         many surrounding pixels are required, leading to poor performance.
         Abruptly truncating it, by using only a few neighbouring pixels,
         improves performance and may reduce ringing (if \texttt{"} params[0]\texttt{"}  is set to
         zero, then only two pixels will be used on either side). However, a
         more gradual truncation, as implemented by other kernels, is generally
         to be preferred. This kernel is provided mainly so that you can
         convince yourself not to use it!

         \sstitem
         AST\_\_SINCSINC: This scheme uses an improved kernel, of the form
         sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where
         sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor
         provides an \texttt{"} envelope\texttt{"}  which gradually rolls off the normal sinc(pi$*$x)
         kernel at large offsets. The width of this envelope is specified by
         giving the number of pixels offset at which it goes to zero by means
         of the \texttt{"} params[1]\texttt{"}  value, which should be at least 1.0 (in addition,
         setting \texttt{"} params[0]\texttt{"}  to zero will select the number of contributing
         pixels so as to utilise the full width of the kernel, out to where it
         reaches zero). The case given by \texttt{"} params[0]=2, params[1]=2\texttt{"}  is typically
         a good choice and is sometimes known as the Lanczos kernel. This is a
         valuable general-purpose interpolation scheme, intermediate in its
         visual effect on images between the AST\_\_NEAREST and AST\_\_LINEAR
         schemes. Although the kernel is slightly oscillatory, ringing is
         adequately suppressed if the data are well sampled.

         \sstitem
         AST\_\_SINCCOS: This scheme uses a kernel of the form
         sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where
         cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor
         provides an envelope which gradually rolls off the sinc() kernel
         at large offsets. The width of this envelope is specified by giving
         the number of pixels offset at which it goes to zero by means
         of the \texttt{"} params[1]\texttt{"}  value, which should be at least 1.0 (in addition,
         setting \texttt{"} params[0]\texttt{"}  to zero will select the number of contributing
         pixels so as to utilise the full width of the kernel, out to where it
         reaches zero). This scheme gives similar results to the
         AST\_\_SINCSINC scheme, which it resembles.

         \sstitem
         AST\_\_SINCGAUSS: This scheme uses a kernel of the form
         sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc()
         kernel is rolled off using a Gaussian envelope which is specified by
         giving its full-width at half-maximum (FWHM) by means of the \texttt{"} params[1]\texttt{"}
         value, which should be at least 0.1 (in addition, setting \texttt{"} params[0]\texttt{"}
         to zero will select the number of contributing pixels so as to utilise
         the width of the kernel out to where the envelope declines to 1\% of its
         maximum value). On astronomical images and spectra, good results are
         often obtained by approximately matching the FWHM of the
         envelope function, given by \texttt{"} params[1]\texttt{"} , to the point spread function
         of the input data. However, there does not seem to be any theoretical
         reason for this.

         \sstitem
         AST\_\_SOMB: This scheme uses a somb(pi$*$x) kernel (a \texttt{"} sombrero\texttt{"}
         function), where x is the pixel offset from the interpolation point
         and somb(z)=2$*$J1(z)/z  (J1 is a Bessel function of the first kind of
         order 1). It is similar to the AST\_\_SINC kernel, and has the same
         parameter usage.

         \sstitem
         AST\_\_SOMBCOS: This scheme uses a kernel of the form
         somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where
         cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the
         AST\_\_SINCCOS kernel, and has the same parameter usage.

      }
      In addition, the following schemes are provided which are not based
      on a 1-dimensional kernel:

      \sstitemlist{

         \sstitem
         AST\_\_BLOCKAVE: This scheme simply takes an average of all the
         pixels on the input grid in a cube centred on the interpolation
         point.  The number of pixels in the cube is determined by the
         value of the first element of the \texttt{"} params\texttt{"}  array, which gives
         the number of pixels in each dimension on either side of the
         central point.  Hence a block of (2 $*$ params[0])$\wedge$ndim\_in
         pixels in the input grid will be examined to determine the
         value of the output pixel.  If the variance is not being used
         (var\_in or var\_out = NULL) then all valid pixels in this cube
         will be averaged in to the result with equal weight.
         If variances are being used, then each input pixel will be
         weighted proportionally to the reciprocal of its variance; any
         pixel without a valid variance will be discarded.  This scheme
         is suitable where the output grid is much coarser than the
         input grid; if the ratio of pixel sizes is R then a suitable
         value of params[0] may be R/2.

      }
      Finally, supplying the following values for \texttt{"} interp\texttt{"}  allows you
      to implement your own sub-pixel interpolation scheme by means of
      your own function. You should supply a pointer to this function
      via the \texttt{"} finterp\texttt{"}  parameter:

      \sstitemlist{

         \sstitem
         AST\_\_UKERN1: In this scheme, you supply a function to evaluate
         your own 1-dimensional interpolation kernel, which is then used
         to perform sub-pixel interpolation (as described above). The
         function you supply should have the same interface as the
         fictitious \htmlref{astUkern1}{astUkern1} function (q.v.).  In addition, a value
         should be given via \texttt{"} params[0]\texttt{"}  to specify the number of
         neighbouring pixels which are to contribute to each interpolated
         value (in the same way as for the pre-defined interpolation
         schemes described above). Other elements of the \texttt{"} params\texttt{"}  array
         are available to pass values to your interpolation function.

         \sstitem
         AST\_\_UINTERP: This is a completely general scheme, in which
         your interpolation function has access to all of the input
         data. This allows you to implement any interpolation algorithm
         you choose, which could (for example) be non-linear, or
         adaptive. In this case, the astResample$<$X$>$ functions play no
         role in the sub-pixel interpolation process and simply handle
         the geometrical transformation of coordinates and other
         housekeeping. The function you supply should have the same
         interface as the fictitious \htmlref{astUinterp}{astUinterp} function (q.v.). In this
         case, the \texttt{"} params\texttt{"}  parameter is not used by astResample$<$X$>$, but
         is available to pass values to your interpolation function.
      }
   }
   \sstdiytopic{
      Control Flags
   }{
      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
      may be used to provide additional control over the resampling
      process. Having selected a set of flags, you should supply the
      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:

      \sstitemlist{

         \sstitem
         AST\_\_NOBAD: Indicates that any output array elements for which no
         resampled value could be obtained should be left set to the value
         they had on entry to this function. If this flag is not supplied,
         such output array elements are set to the value supplied for
         parameter \texttt{"} badval\texttt{"} . Note, this flag cannot be used in conjunction
         with the AST\_\_CONSERVEFLUX flag (an error will be reported if both
         flags are specified).

         \sstitem
         AST\_\_URESAMP1, 2, 3 \& 4: A set of four flags which are
         reserved for your own use. They may be used to pass private
         information to any sub-pixel interpolation function which you
         implement yourself. They are ignored by all the pre-defined
         interpolation schemes.

         \sstitem
         AST\_\_USEBAD: Indicates that there may be bad pixels in the
         input array(s) which must be recognised by comparing with the
         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
         If this flag is not set, all input values are treated literally
         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
         values.

         \sstitem
         AST\_\_CONSERVEFLUX: Indicates that the output pixel values should
         be scaled in such a way as to preserve (approximately) the total data
         value in a feature on the sky. Without this flag, each output pixel
         value represents an instantaneous sample of the input data values at
         the corresponding input position. This is appropriate if the input
         data represents the spatial density of some quantity (e.g. surface
         brightness in Janskys per square arc-second) because the output
         pixel values will have the same normalisation and units as the
         input pixel values. However, if the input data values represent
         flux (or some other physical quantity) per pixel, then the
         AST\_\_CONSERVEFLUX flag could be used. This causes each output
         pixel value to be scaled by the ratio of the output pixel size to
         the input pixel size.

      }
      This flag can only be used if the Mapping is successfully approximated
      by one or more linear transformations. Thus an error will be reported
      if it used when the
      \texttt{"} tol\texttt{"}  parameter
      is set to zero (which stops the use of linear approximations), or
      if the Mapping is too non-linear to be approximated by a piece-wise
      linear transformation. The ratio of output to input pixel size is
      evaluated once for each panel of the piece-wise linear approximation to
      the Mapping, and is assumed to be constant for all output pixels in the
      panel. The scaling factors for adjacent panels will in general
      differ slightly, and so the joints between panels may be visible when
      viewing the output image at high contrast. If this is a problem,
      reduce the value of the
      \texttt{"} tol\texttt{"}  parameter
      until the difference between adjacent panels is sufficiently small
      to be insignificant.

      Note, this flag cannot be used in conjunction with the AST\_\_NOBAD
      flag (an error will be reported if both flags are specified).
   }
   \sstdiytopic{
      Propagation of Missing Data
   }{
      Unless the AST\_\_NOBAD flag is specified, instances of missing data
      (bad pixels) in the output grid are
      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
      array. These may be produced if any of the following happen:

      \sstitemlist{

         \sstitem
         The input position (the transformed position of the output
         pixel\texttt{'} s centre) lies outside the boundary of the grid of input
         pixels.

         \sstitem
         The input position lies inside the boundary of a bad input
         pixel. In this context, an input pixel is considered bad if its
         data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
         set via the \texttt{"} flags\texttt{"}  parameter.
         (Positions which have half-integral coordinate values, and
         therefore lie on a pixel boundary, are regarded as lying within
         the pixel with the larger, i.e. more positive, index.)

         \sstitem
         The set of neighbouring input pixels (excluding those which
         are bad) is unsuitable for calculating an interpolated
         value. Whether this is true may depend on the sub-pixel
         interpolation scheme in use.

         \sstitem
         The interpolated value lies outside the range which can be
         represented using the data type of the \texttt{"} out\texttt{"}  array.

      }
      In addition, associated output variance estimates (if
      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
      value in the \texttt{"} out\_var\texttt{"}  array under any of the following
      circumstances:

      \sstitemlist{

         \sstitem
         The associated resampled data value (in the \texttt{"} out\texttt{"}  array) is bad.

         \sstitem
         The set of neighbouring input pixels which contributed to the
         output data value do not all have valid variance estimates
         associated with them. In this context, an input variance
         estimate may be regarded as bad either because it has the value
         \texttt{"} badval\texttt{"}  (and the AST\_\_USEBAD flag is set), or because it is
         negative.

         \sstitem
         The set of neighbouring input pixels for which valid variance
         values are available is unsuitable for calculating an overall
         variance value. Whether this is true may depend on the sub-pixel
         interpolation scheme in use.

         \sstitem
         The variance value lies outside the range which can be
         represented using the data type of the \texttt{"} out\_var\texttt{"}  array.

      }
      If the AST\_\_NOBAD flag is specified via
      parameter \texttt{"} flags\texttt{"} ,
      then output array elements that would otherwise be set to
      \texttt{"} badval\texttt{"}
      are instead left holding the value they had on entry to this
      function. The number of such array elements is returned as
      the function value.
   }
}
\sstroutine{
   astResolve
}{
   Resolve a vector into two orthogonal components
}{
   \sstdescription{
      This function resolves a vector into two perpendicular components.
      The vector from point 1 to point 2 is used as the basis vector.
      The vector from point 1 to point 3 is resolved into components
      parallel and perpendicular to this basis vector. The lengths of the
      two components are returned, together with the position of closest
      aproach of the basis vector to point 3.
   }
   \sstsynopsis{
      void astResolve( AstFrame $*$this, const double point1[],
                       const double point2[], const double point3[],
                       double point4[], double $*$d1, double $*$d2 );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{Frame}{Frame}.
      }
      \sstsubsection{
         point1
      }{
         An array of double, with one element for each Frame axis
         (\htmlref{Naxes}{Naxes} attribute). This marks the start of the basis vector,
         and of the vector to be resolved.
      }
      \sstsubsection{
         point2
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute). This marks the end of the basis vector.
      }
      \sstsubsection{
         point3
      }{
         An array of double, with one element for each Frame axis
         (Naxes attribute). This marks the end of the vector to be
         resolved.
      }
      \sstsubsection{
         point4
      }{
         An array of double, with one element for each Frame axis
         in which the coordinates of the point of closest approach of the
         basis vector to point 3 will be returned.
      }
      \sstsubsection{
         d1
      }{
         The address of a location at which to return the distance from
         point 1 to point 4 (that is, the length of the component parallel
         to the basis vector). Positive values are in the same sense as
         movement from point 1 to point 2.
      }
      \sstsubsection{
         d2
      }{
         The address of a location at which to return the distance from
         point 4 to point 3 (that is, the length of the component
         perpendicular to the basis vector). The value is always positive.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Each vector used in this function is the path of
         shortest distance between two points, as defined by the
         \htmlref{astDistance}{astDistance} function.

         \sstitem
         This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
         if any of the input coordinates has this value, or if the required
         output values are undefined.
      }
   }
}
\sstroutine{
   astRetainFits
}{
   Indicate that the current card in a FitsChan should be retained
}{
   \sstdescription{
      This function
      stores a flag with the current card in the \htmlref{FitsChan}{FitsChan} indicating that
      the card should not be removed from the FitsChan when an \htmlref{Object}{Object} is
      read from the FitsChan using
      \htmlref{astRead}{astRead}.

      Cards that have not been flagged in this way are removed when a
      read operation completes succesfully, but only if the card was used
      in the process of creating the returned AST Object. Any cards that
      are irrelevant to the creation of the AST Object are retained whether
      or not they are flagged.
   }
   \sstsynopsis{
      void astRetainFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function returns without action if the FitsChan is
         initially positioned at the \texttt{"} end-of-file\texttt{"}  (i.e. if the \htmlref{Card}{Card}
         attribute exceeds the number of cards in the FitsChan).

         \sstitem
         The current card is not changed by this function.
      }
   }
}
\sstroutine{
   astSame
}{
   Test if two AST pointers refer to the same Object
}{
   \sstdescription{
      This function returns a boolean result (0 or 1) to indicate
      whether two pointers refer to the same \htmlref{Object}{Object}.
   }
   \sstsynopsis{
      int astSame( AstObject $*$this,  AstObject $*$that )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the first Object.
      }
      \sstsubsection{
         that
      }{
         Pointer to the second Object.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSame()
      }{
         One if the two pointers refer to the same Object, otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Two independent Objects that happen to be identical are not
         considered to be the same Object by this function.

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astSelectorMap
}{
   Create a SelectorMap
}{
   \sstdescription{
      This function creates a new \htmlref{SelectorMap}{SelectorMap} and optionally initialises
      its attributes.

      A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains
      a given input position.

      A SelectorMap encapsulates a number of Regions that all have the same
      number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of
      inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes
      spanned by one of the encapsulated Region. All SelectorMaps have only
      a single output. SelectorMaps do not define an inverse transformation.

      For each input position, the forward transformation of a SelectorMap
      searches through the encapsulated Regions (in the order supplied when
      the SelectorMap was created) until a Region is found which contains
      the input position. The index associated with this Region is
      returned as the SelectorMap output value (the index value is the
      position of the Region within the list of Regions supplied when the
      SelectorMap was created, starting at 1 for the first Region). If an
      input position is not contained within any Region, a value of zero is
      returned by the forward transformation.

      If a compound Mapping contains a SelectorMap in series with its own
      inverse, the combination of the two adjacent SelectorMaps will be
      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
      \htmlref{astSimplify}{astSimplify}.

      In practice, SelectorMaps are often used in conjunction with SwitchMaps.
   }
   \sstsynopsis{
      AstSelectorMap $*$astSelectorMap( int nreg, AstRegion $*$regs[],
                                      double badval, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nreg
      }{
         The number of supplied Regions.
      }
      \sstsubsection{
         regs
      }{
         An array of pointers to the Regions. All the supplied Regions must
         relate to the same coordinate Frame. The number of axes in this
         coordinate Frame defines the number of inputs for the SelectorMap.
      }
      \sstsubsection{
         badval
      }{
         The value to be returned by the forward transformation of the
         SelectorMap for any input positions that have a bad (AST\_\_BAD)
         value on any axis.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SelectorMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSelectorMap()
      }{
         A pointer to the new SelectorMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Deep copies are taken of the supplied Regions. This means that
         any subsequent changes made to the component Regions using the
         supplied pointers will have no effect on the SelectorMap.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSet
}{
   Set attribute values for an Object
}{
   \sstdescription{
      This function assigns a set of attribute values to an \htmlref{Object}{Object},
      over-riding any previous values. The attributes and their new
      values are specified via a character string, which should
      contain a comma-separated list of the form:

         \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"}

      where \texttt{"} attribute\_n\texttt{"}  specifies an attribute name, and the value
      to the right of each \texttt{"} =\texttt{"}  sign should be a suitable textual
      representation of the value to be assigned. This value will be
      interpreted according to the attribute\texttt{'} s data type.

      The string supplied may also contain \texttt{"} printf\texttt{"} -style format
      specifiers, identified by \texttt{"} \%\texttt{"}  signs in the usual way. If
      present, these will be substituted by values supplied as
      additional optional arguments (using the normal \texttt{"} printf\texttt{"}  rules)
      before the string is used.
   }
   \sstsynopsis{
      void astSet( AstObject $*$this, const char $*$settings, ... )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         settings
      }{
         Pointer to a null-terminated character string containing a
         comma-separated list of attribute settings in the form described
         above.
      }
      \sstsubsection{
         ...
      }{
         Optional additional arguments which supply values to be
         substituted for any \texttt{"} printf\texttt{"} -style format specifiers that
         appear in the \texttt{"} settings\texttt{"}  string.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"}  );
      }{
         Sets the Report attribute for Object \texttt{"} map\texttt{"}  to the value 1 and
         the Zoom attribute to 25.0.
      }
      \sstexamplesubsection{
         astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis );
      }{
         Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"}  to a
         suitable string, where the axis number is obtained from
         \texttt{"} axis\texttt{"} , a variable of type int.
      }
      \sstexamplesubsection{
         astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring );
      }{
         Sets the Title attribute for Object \texttt{"} frame\texttt{"}  to the contents of
         the string \texttt{"} mystring\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         White space may also surround attribute values, where it will
         generally be ignored (except for string-valued attributes where
         it is significant and forms part of the value to be assigned).

         \sstitem
         To include a literal comma in the value assigned to an attribute,
         the whole attribute value should be enclosed in quotation markes.
         Alternatively, you can use \texttt{"} \%s\texttt{"}  format and supply the value as a
         separate additional argument to astSet (or use the astSetC
         function instead).

         \sstitem
         The same procedure may be adopted if \texttt{"} \%\texttt{"}  signs are to be included
         and are not to be interpreted as format specifiers (alternatively,
         the \texttt{"} printf\texttt{"}  convention of writing \texttt{"} \%\%\texttt{"}  may be used).

         \sstitem
         An error will result if an attempt is made to set a value for
         a read-only attribute.
      }
   }
}
\sstroutine{
   astSet$<$X$>$
}{
   Set an attribute value for an Object
}{
   \sstdescription{
      This is a family of functions which set a specified attribute
      value for an \htmlref{Object}{Object} using one of several different data
      types. The type is selected by replacing $<$X$>$ in the function name
      by C, D, F, I or L, to supply a value in const char$*$ (i.e. string),
      double, float, int, or long format, respectively.

      If possible, the value you supply is converted to the type of
      the attribute. If conversion is not possible, an error will
      result.
   }
   \sstsynopsis{
      void astSet$<$X$>$( AstObject $*$this, const char $*$attrib, $<$X$>$type value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         attrib
      }{
         Pointer to a null-terminated character string containing the
         name of the attribute whose value is to be set.
      }
      \sstsubsection{
         value
      }{
         The value to be set for the attribute, in the data type corresponding
         to $<$X$>$ (or, in the case of astSetC, a pointer to a null-terminated
         character string containing this value).
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         These functions apply to all Objects.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         astSetI( frame, \texttt{"} Preserve\texttt{"} , 1 );
      }{
         Sets the Preserve attribute value for Object \texttt{"} frame\texttt{"}  to 1.
      }
      \sstexamplesubsection{
         astSetC( plot, \texttt{"} Format(1)\texttt{"} , \texttt{"} \%.2g\texttt{"}  );
      }{
         Sets the Format(1) attribute value for Object \texttt{"} plot\texttt{"}  to the
         character string \texttt{"} \%.2g\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         An error will result if an attempt is made to set a value for
         a read-only attribute.
      }
   }
}
\sstroutine{
   astSetActiveUnit
}{
   Specify how the Unit attribute should be used
}{
   \sstdescription{
      This function
      sets the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}, which
      controls how the Frame behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert})
      to match another Frame. If the ActiveUnit flag is set in both
      template and target Frames then the returned \htmlref{Mapping}{Mapping} takes into account
      any differences in axis units. The default value for simple Frames is
      zero, which preserves the behaviour of versions of AST prior to
      version 2.0.

      If the ActiveUnit flag of either Frame is
      zero,
      then the Mapping will ignore any difference in the Unit attributes of
      corresponding template and target axes. In this mode, the Unit
      attributes are purely descriptive commentary for the benefit of
      human readers and do not influence the Mappings between Frames.
      This is the behaviour which all Frames had in older version of AST,
      prior to the introduction of this attribute.

      If the ActiveUnit flag of both Frames is
      non-zero,
      then the Mapping from template to target will take account of any
      difference in the axis Unit attributes, where-ever possible. For
      instance, if corresponding target and template axes have Unit strings of
      \texttt{"} km\texttt{"}  and \texttt{"} m\texttt{"} , then the \htmlref{FrameSet}{FrameSet} class will use a \htmlref{ZoomMap}{ZoomMap} to connect
      them which introduces a scaling of 1000. If no Mapping can be found
      between the corresponding units string, then an error is reported.
      In this mode, it is assumed that values of the Unit attribute conform
      to the syntax for units strings described in the FITS WCS Paper I
      \texttt{"} Representations of world coordinates in FITS\texttt{"}  (Greisen \& Calabretta).
      Particularly, any of the named unit symbols, functions, operators or
      standard multiplier prefixes listed within that paper can be used within
      a units string. A units string may contain symbols for unit which are
      not listed in the FITS paper, but transformation to any other units
      will then not be possible (except to units which depend only on the
      same unknown units - thus \texttt{"} flops\texttt{"}  can be transformed to \texttt{"} Mflops\texttt{"}
      even though \texttt{"} flops\texttt{"}  is not a standard FITS unit symbol).

      A range of common non-standard variations of unit names and multiplier
      prefixes are also allowed, such as adding an \texttt{"} s\texttt{"}  to the end of Angstrom,
      using a lower case \texttt{"} a\texttt{"}  at the start of \texttt{"} angstrom\texttt{"} , \texttt{"} micron\texttt{"}  instead of
      \texttt{"} um\texttt{"} , \texttt{"} sec\texttt{"}  instead of \texttt{"} s\texttt{"} , etc.

      If the ActiveUnit flag is non-zero, setting a new Unit value for an
      axis may also change its Label and Symbol attributes. For instance, if
      an axis has Unit \texttt{"} Hz\texttt{"}  and Label \texttt{"} frequency\texttt{"} , then changing its Unit to
      \texttt{"} log(Hz)\texttt{"}  will change its Label to \texttt{"} log( frequency )\texttt{"} . In addition,
      the \htmlref{Axis}{Axis} Format attribute will be cleared when-ever a new value
      is assigned to the Unit attribute.

      Note, if a non-zero value is set for the ActiveUnit flag, then changing a
      Unit value for the current Frame within a FrameSet will result in the
      Frame being re-mapped (that is, the Mappings which define the
      relationships between Frames within the FrameSet will be modified to
      take into account the change in Units).
   }
   \sstsynopsis{
      void astSetActiveUnit( AstFrame $*$this, int value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         value
      }{
         The new value to use.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The ActiveUnit flag for a SkyFrame is always 0 (any value
         supplied using this function is ignored).
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         The ActiveUnit flag for a SpecFrame is always 1 (any value
         supplied using this function is ignored).
      }
      \sstsubsection{
         \htmlref{FluxFrame}{FluxFrame}
      }{
         The ActiveUnit flag for a FluxFrame is always 1 (any value
         supplied using this function is ignored).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The default ActiveUnit flag for a CmpFrame is 1 if both of the
         component Frames are using active units, and zero otherwise. When
         a new value is set for the ActiveUnit flag, the flag value
         is propagated to the component Frames. This change will be
         reflected through all references to the component Frames, not
         just those encapsulated within the CmpFrame.
      }
      \sstsubsection{
         \htmlref{Region}{Region}:
      }{
         Regions always use active units if possible.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The ActiveUnit flag resembles a Frame attribute, except that it
         cannot be tested or cleared, and it cannot be accessed using the
         generic \htmlref{astGet$<$X$>$}{astGet$<$X$>$} and \htmlref{astSet$<$X$>$}{astSet$<$X$>$} functions.

         \sstitem
         The \htmlref{astGetActiveUnit}{astGetActiveUnit} function can be used to retrieve the current
         value of the ActiveUnit flag.
      }
   }
}
\sstroutine{
   astSetFits$<$X$>$
}{
   Store a keyword value in a FitsChan
}{
   \sstdescription{
      This is a family of functions which store values for named keywords
      within a \htmlref{FitsChan}{FitsChan} at the current card position. The supplied keyword
      value can either over-write an existing keyword value, or can be
      inserted as a new header card into the FitsChan.

      The keyword data type is selected by replacing $<$X$>$ in the function name
      by one of the following strings representing the recognised FITS data

      types:

      \sstitemlist{

         \sstitem
         CF - Complex floating point values.

         \sstitem
         CI - Complex integer values.

         \sstitem
         F  - Floating point values.

         \sstitem
         I  - Integer values.

         \sstitem
         L  - Logical (i.e. boolean) values.

         \sstitem
         S  - String values.

         \sstitem
         CN - A \texttt{"} CONTINUE\texttt{"}  value, these are treated like string values, but
                are encoded without an equals sign.

      }
      The data type of the \texttt{"} value\texttt{"}  parameter depends on $<$X$>$ as follows:

      \sstitemlist{

         \sstitem
         CF - \texttt{"} double $*$\texttt{"}  (a pointer to a 2 element array holding the real and
                imaginary parts of the complex value).

         \sstitem
         CI - \texttt{"} int $*$\texttt{"}  (a pointer to a 2 element array holding the real and
                imaginary parts of the complex value).

         \sstitem
         F  - \texttt{"} double\texttt{"} .

         \sstitem
         I  - \texttt{"} int\texttt{"} .

         \sstitem
         L  - \texttt{"} int\texttt{"} .

         \sstitem
         S  - \texttt{"} const char $*$\texttt{"} .

         \sstitem
         CN - \texttt{"} const char $*$\texttt{"} .
      }
   }
   \sstsynopsis{
      void astSetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type value,
                          const char $*$comment, int overwrite )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated character string
         containing the FITS keyword name. This may be a complete FITS
         header card, in which case the keyword to use is extracted from
         it. No more than 80 characters are read from this string.
      }
      \sstsubsection{
         value
      }{
         The keyword value to store with the named keyword. The data type
         of this parameter depends on $<$X$>$ as described above.
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null terminated string
         holding a comment to associated with the keyword.
         If a NULL pointer or
         a blank string is supplied, then any comment included in the string
         supplied for the
         \texttt{"} name\texttt{"}  parameter is used instead. If \texttt{"} name\texttt{"}
         contains no comment, then any existing comment in the card being
         over-written is retained. Otherwise, no comment is stored with
         the card.
      }
      \sstsubsection{
         overwrite
      }{
         If non-zero,
         the new card formed from the supplied keyword name, value and comment
         string over-writes the current card, and the current card is
         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
         zero,
         the new card is inserted in front of the current card and the current
         card is left unchanged. In either case, if the current card on entry
         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
         the list.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The
         function \htmlref{astSetFitsU}{astSetFitsU}
         can be used to indicate that no value is associated with a keyword.

         \sstitem
         The
         function \htmlref{astSetFitsCM}{astSetFitsCM}
         can be used to store a pure comment card (i.e. a card with a blank
         keyword).

         \sstitem
         To assign a new value for an existing keyword within a FitsChan,
         first find the card describing the keyword using \htmlref{astFindFits}{astFindFits}, and
         then use one of the astSetFits$<$X$>$ family to over-write the old value.

         \sstitem
         If, on exit, there are no cards following the card written by
         this function, then the current card is left pointing at the
         \texttt{"} end-of-file\texttt{"} .

         \sstitem
         An error will be reported if the keyword name does not conform
         to FITS requirements.
      }
   }
}
\sstroutine{
   astSetFitsCM
}{
   Store a comment card in a FitsChan
}{
   \sstdescription{
      This
      function
      stores a comment card ( i.e. a card with no keyword name or equals
      sign) within a \htmlref{FitsChan}{FitsChan} at the current card position. The new card
      can either over-write an existing card, or can be inserted as a new
      card into the FitsChan.
   }
   \sstsynopsis{
      void astSetFitsCM( AstFitsChan $*$this, const char $*$comment,
                         int overwrite )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null terminated string
         holding the text of the comment card.
         If a NULL pointer or
         a blank string is supplied, then a totally blank card is produced.
      }
      \sstsubsection{
         overwrite
      }{
         If non-zero,
         the new card over-writes the current card, and the current card is
         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
         zero,
         the new card is inserted in front of the current card and the current
         card is left unchanged. In either case, if the current card on entry
         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
         the list.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If, on exit, there are no cards following the card written by
         this function, then the current card is left pointing at the
         \texttt{"} end-of-file\texttt{"} .
      }
   }
}
\sstroutine{
   astSetFitsU
}{
   Store an undefined keyword value in a FitsChan
}{
   \sstdescription{
      This
      function
      stores an undefined value for a named keyword within
      a \htmlref{FitsChan}{FitsChan} at the current card position. The new undefined value
      can either over-write an existing keyword value, or can be inserted
      as a new header card into the FitsChan.
   }
   \sstsynopsis{
      void astSetFitsU( AstFitsChan $*$this, const char $*$name,
                        const char $*$comment, int overwrite )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated character string
         containing the FITS keyword name. This may be a complete FITS
         header card, in which case the keyword to use is extracted from
         it. No more than 80 characters are read from this string.
      }
      \sstsubsection{
         comment
      }{
         A pointer to a null terminated string
         holding a comment to associated with the keyword.
         If a NULL pointer or
         a blank string is supplied, then any comment included in the string
         supplied for the
         \texttt{"} name\texttt{"}  parameter is used instead. If \texttt{"} name\texttt{"}
         contains no comment, then any existing comment in the card being
         over-written is retained. Otherwise, no comment is stored with
         the card.
      }
      \sstsubsection{
         overwrite
      }{
         If non-zero,
         the new card formed from the supplied keyword name and comment
         string over-writes the current card, and the current card is
         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
         zero,
         the new card is inserted in front of the current card and the current
         card is left unchanged. In either case, if the current card on entry
         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
         the list.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If, on exit, there are no cards following the card written by
         this function, then the current card is left pointing at the
         \texttt{"} end-of-file\texttt{"} .

         \sstitem
         An error will be reported if the keyword name does not conform
         to FITS requirements.
      }
   }
}
\sstroutine{
   astSetRefPos
}{
   Set the reference position in a specified celestial coordinate system
}{
   \sstdescription{
      This function
      sets the reference position (see attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) using
      axis values (in radians) supplied within the celestial coordinate
      system represented by a supplied \htmlref{SkyFrame}{SkyFrame}.
   }
   \sstsynopsis{
      void astSetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double lon,
                         double lat )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the \htmlref{SpecFrame}{SpecFrame}.
      }
      \sstsubsection{
         frm
      }{
         Pointer to the SkyFrame which defines the celestial coordinate
         system in which the longitude and latitude values are supplied.
         If NULL
         is supplied, then the supplied longitude and latitude values are
         assumed to be FK5 J2000 RA and Dec values.
      }
      \sstsubsection{
         lon
      }{
         The longitude of the reference point, in the coordinate system
         represented by the supplied SkyFrame (radians).
      }
      \sstsubsection{
         lat
      }{
         The latitude of the reference point, in the coordinate system
         represented by the supplied SkyFrame (radians).
      }
   }
}
\sstroutine{
   astSetStatus
}{
   Set the AST error status to an explicit value
}{
   \sstdescription{
      This function sets the AST error status to the value supplied.
      It does not cause any error message to be produced and should
      not be used as part of normal error reporting. Its purpose is
      simply to communicate to AST that an error has occurred in some
      other item of software.

      For example, a source or sink function supplied as an argument
      to \htmlref{astChannel}{astChannel} or \htmlref{astFitsChan}{astFitsChan} might use this to signal that an
      input/output error has occurred. AST could then respond by
      terminating the current read or write operation.
   }
   \sstsynopsis{
      void astSetStatus( int status\_value )
   }
   \sstparameters{
      \sstsubsection{
         status\_value
      }{
         The new error status value to be set.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the AST error status is set to an error value, most AST
         functions will not execute and will simply return without
         action. To clear the error status and restore normal behaviour,
         use \htmlref{astClearStatus}{astClearStatus}.
      }
   }
}
\sstroutine{
   astSetUnc
}{
   Store uncertainty information in a Region
}{
   \sstdescription{
      Each \htmlref{Region}{Region} (of any class) can have an \texttt{"} uncertainty\texttt{"}  which specifies
      the uncertainties associated with the boundary of the Region. This
      information is supplied in the form of a second Region. The uncertainty
      in any point on the boundary of a Region is found by shifting the
      associated \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the boundary
      point being considered. The area covered by the shifted uncertainty
      Region then represents the uncertainty in the boundary position.
      The uncertainty is assumed to be the same for all points.

      The uncertainty is usually specified when the Region is created, but
      this
      function
      allows it to be changed at any time.
   }
   \sstsynopsis{
      void astSetUnc( AstRegion $*$this, AstRegion $*$unc )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region which is to be assigned a new uncertainty.
      }
      \sstsubsection{
         unc
      }{
         Pointer to the new uncertainty Region. This must be of a class for
         which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse},
         etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions.
         A deep copy of the supplied Region will be taken, so subsequent
         changes to the uncertainty Region using the supplied pointer will
         have no effect on the Region
         \texttt{"} this\texttt{"} .
      }
   }
}
\sstroutine{
   astShiftMap
}{
   Create a ShiftMap
}{
   \sstdescription{
      This function creates a new \htmlref{ShiftMap}{ShiftMap} and optionally initialises its
      attributes.

      A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a
      specified constant value.
   }
   \sstsynopsis{
      AstShiftMap $*$astShiftMap( int ncoord, const double shift[],
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of coordinate values for each point to be
         transformed (i.e. the number of dimensions of the space in
         which the points will reside). The same number is applicable
         to both input and output points.
      }
      \sstsubsection{
         shift
      }{
         An array containing the values to be added on to the input
         coordinates in order to create the output coordinates. A separate
         value should be supplied for each coordinate.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new ShiftMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astShiftMap()
      }{
         A pointer to the new ShiftMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astShow
}{
   Display a textual representation of an Object on standard output
}{
   \sstdescription{
      This function displays a textual description of any AST \htmlref{Object}{Object}
      on standard output. It is provided primarily as an aid to
      debugging.
   }
   \sstsynopsis{
      void astShow( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be displayed.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
}
\sstroutine{
   astShowFits
}{
   Display the contents of a FitsChan on standard output
}{
   \sstdescription{
      This function
      formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output.
   }
   \sstsynopsis{
      void astShowFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
}
\sstroutine{
   astShowMesh
}{
   Display a mesh of points covering the surface of a Region
}{
   \sstdescription{
      This function
      writes a table to standard output containing the axis values at a
      mesh of points covering the surface of the supplied \htmlref{Region}{Region}. Each row
      of output contains a tab-separated list of axis values, one for
      each axis in the \htmlref{Frame}{Frame} encapsulated by the Region. The number of
      points in the mesh is determined by the \htmlref{MeshSize}{MeshSize} attribute.

      The table is preceded by a given title string, and followed by a
      single line containing the word \texttt{"} ENDMESH\texttt{"} .
   }
   \sstsynopsis{
      void astShowMesh( AstRegion $*$this, int format, const char $*$ttl )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Region.
      }
      \sstsubsection{
         format
      }{
         A boolean value indicating if the displayed axis values should
         be formatted according to the Format attribute associated with
         the Frame\texttt{'} s axis. Otherwise, they are displayed as simple
         floating point values.
      }
      \sstsubsection{
         ttl
      }{
         A title to display before displaying the first position.
      }
   }
}
\sstroutine{
   astSimplify
}{
   Simplify a Mapping
}{
   \sstdescription{
      This function simplifies a \htmlref{Mapping}{Mapping} (which may be a compound
      Mapping such as a \htmlref{CmpMap}{CmpMap}) to eliminate redundant computational
      steps, or to merge separate steps which can be performed more
      efficiently in a single operation.

      As a simple example, a Mapping which multiplied coordinates by
      5, and then multiplied the result by 10, could be simplified to
      a single step which multiplied by 50. Similarly, a Mapping which
      multiplied by 5, and then divided by 5, could be reduced to a
      simple copying operation.

      This function should typically be applied to Mappings which have
      undergone substantial processing or have been formed by merging
      other Mappings. It is of potential benefit, for example, in
      reducing execution time if applied before using a Mapping to
      transform a large number of coordinates.
   }
   \sstsynopsis{
      AstMapping $*$astSimplify( AstMapping $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the original Mapping.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         This function applies to all Mappings.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         If the supplied Mapping is a FrameSet, the returned Mapping
         will be a copy of the supplied FrameSet in which all the
         inter-\htmlref{Frame}{Frame} Mappings have been simplified.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSimplify()
      }{
         A new pointer to the (possibly simplified) Mapping.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Mappings that have a set value for their \htmlref{Ident}{Ident} attribute are
         left unchanged after simplification. This is so that their
         individual identity is preserved. This restriction does not
         apply to the simplification of Frames.

         \sstitem
         This function can safely be applied even to Mappings which
         cannot be simplified. If no simplification is possible, it
         behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the
         original Mapping.

         \sstitem
         The Mapping returned by this function may not be independent
         of the original (even if simplification was possible), and
         modifying it may therefore result in indirect modification of
         the original. If a completely independent result is required, a
         copy should be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSkyFrame
}{
   Create a SkyFrame
}{
   \sstdescription{
      This function creates a new \htmlref{SkyFrame}{SkyFrame} and optionally initialises
      its attributes.

      A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes
      celestial longitude/latitude coordinate systems. The particular
      celestial coordinate system to be represented is specified by
      setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default
      is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or
      an \htmlref{Epoch}{Epoch}.

      For each of the supported celestial coordinate systems, a SkyFrame
      can apply an optional shift of origin to create a coordinate system
      representing offsets within the celestial coordinate system from some
      specified point. This offset coordinate system can also be rotated to
      define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}
      and SkyRefP

      All the coordinate values used by a SkyFrame are in
      radians. These may be formatted in more conventional ways for
      display by using \htmlref{astFormat}{astFormat}.
   }
   \sstsynopsis{
      AstSkyFrame $*$astSkyFrame( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SkyFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSkyFrame()
      }{
         A pointer to the new SkyFrame.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         frame = astSkyFrame( \texttt{"} \texttt{"}  );
      }{
         Creates a SkyFrame to describe the default ICRS celestial
         coordinate system.
      }
      \sstexamplesubsection{
         frame = astSkyFrame( \texttt{"} System = FK5, Equinox = J2005, Digits = 10\texttt{"}  );
      }{
         Creates a SkyFrame to describe the FK5 celestial
         coordinate system, with a mean Equinox of J2005.0.
         Because especially accurate coordinates will be used,
         additional precision (10 digits) has been requested. This will
         be used when coordinate values are formatted for display.
      }
      \sstexamplesubsection{
         frame = astSkyFrame( \texttt{"} System = FK4, Equinox = 1955-sep-2\texttt{"}  );
      }{
         Creates a SkyFrame to describe the old FK4 celestial
         coordinate system.  A default Epoch value (B1950.0) is used,
         but the mean Equinox value is given explicitly as \texttt{"} 1955-sep-2\texttt{"} .
      }
      \sstexamplesubsection{
         frame = astSkyFrame( \texttt{"} System = GAPPT, Epoch = \%s\texttt{"} , date );
      }{
         Creates a SkyFrame to describe the Geocentric Apparent
         celestial coordinate system. The Epoch value, which specifies
         the date of observation, is obtained from a date/time string
         supplied via the string pointer \texttt{"} date\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Currently, the default celestial coordinate system is
         ICRS. However, this default may change in future as new
         astrometric standards evolve. The intention is to track the most
         modern appropriate standard. For this reason, you should use the
         default only if this is what you intend (and can tolerate any
         associated slight change in behaviour with future versions of
         this function). If you intend to use the ICRS system
         indefinitely, then you should specify it explicitly using an
         \texttt{"} options\texttt{"}  value of \texttt{"} System=ICRS\texttt{"} .

         \sstitem
         Whichever celestial coordinate system is represented, it will
         have two axes.  The first of these will be the longitude axis
         and the second will be the latitude axis. This order can be
         changed using \htmlref{astPermAxes}{astPermAxes} if required.

         \sstitem
         When conversion between two SkyFrames is requested (as when
         supplying SkyFrames to \htmlref{astConvert}{astConvert}),
         account will be taken of the nature of the celestial coordinate
         systems they represent, together with any qualifying mean Equinox or
         Epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} attribute will also be taken into
         account. The results will therefore fully reflect the
         relationship between positions on the sky measured in the two
         systems.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSkyOffsetMap
}{
   Returns a Mapping which goes from absolute coordinates to offset
   coordinates
}{
   \sstdescription{
      This function returns a \htmlref{Mapping}{Mapping} in which the forward transformation
      transforms a position in the coordinate system given by the \htmlref{System}{System}
      attribute of the supplied \htmlref{SkyFrame}{SkyFrame}, into the offset coordinate system
      specified by the SkyRef, SkyRefP and \htmlref{SkyRefIs}{SkyRefIs} attributes of the
      supplied SkyFrame.

      A \htmlref{UnitMap}{UnitMap} is returned if the SkyFrame does not define an offset
      coordinate system.
   }
   \sstsynopsis{
      AstMapping $*$astSkyOffsetMap( AstSkyFrame $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the SkyFrame.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSkyOffsetMap()
      }{
         Pointer to the returned Mapping.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSlaAdd
}{
   Add a celestial coordinate conversion to an SlaMap
}{
   \sstdescription{
      This function adds one of the standard celestial coordinate
      system conversions provided by the SLALIB Positional Astronomy
      Library (Starlink User Note SUN/67) to an existing \htmlref{SlaMap}{SlaMap}.

      When an SlaMap is first created (using \htmlref{astSlaMap}{astSlaMap}), it simply
      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSlaAdd (repeatedly
      if necessary), one or more coordinate conversion steps may then
      be added, which the SlaMap will perform in sequence. This allows
      multi-step conversions between a variety of celestial coordinate
      systems to be assembled out of the building blocks provided by
      SLALIB.

      Normally, if an SlaMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
      then its forward transformation is performed by carrying out
      each of the individual coordinate conversions specified by
      astSlaAdd in the order given (i.e. with the most recently added
      conversion applied last).

      This order is reversed if the SlaMap\texttt{'} s Invert attribute is
      non-zero (or if the inverse transformation is requested by any
      other means) and each individual coordinate conversion is also
      replaced by its own inverse. This process inverts the overall
      effect of the SlaMap. In this case, the first conversion to be
      applied would be the inverse of the one most recently added.
   }
   \sstsynopsis{
      void astSlaAdd( AstSlaMap $*$this, const char $*$cvt, const double args[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the SlaMap.
      }
      \sstsubsection{
         cvt
      }{
         Pointer to a null-terminated string which identifies the
         celestial coordinate conversion to be added to the
         SlaMap. See the \texttt{"} SLALIB Conversions\texttt{"}  section for details of
         those available.
      }
      \sstsubsection{
         args
      }{
         An array containing argument values for the celestial
         coordinate conversion. The number of arguments required, and
         hence the number of array elements used, depends on the
         conversion specified (see the \texttt{"} SLALIB Conversions\texttt{"}
         section). This array is ignored
         and a NULL pointer may be supplied
         if no arguments are needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         All coordinate values processed by an SlaMap are in
         radians. The first coordinate is the celestial longitude and the
         second coordinate is the celestial latitude.

         \sstitem
         When assembling a multi-stage conversion, it can sometimes be
         difficult to determine the most economical conversion path. For
         example, converting to the standard FK5 coordinate system as an
         intermediate stage is often sensible in formulating the problem,
         but may introduce unnecessary extra conversion steps. A solution
         to this is to include all the steps which are (logically)
         necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting
         SlaMap. The simplification process will eliminate any steps
         which turn out not to be needed.

         \sstitem
         This function does not check to ensure that the sequence of
         coordinate conversions added to an SlaMap is physically
         meaningful.
      }
   }
   \sstdiytopic{
      SLALIB Conversions
   }{
      The following strings (which are case-insensitive) may be supplied
      via the \texttt{"} cvt\texttt{"}  parameter to indicate which celestial coordinate
      conversion is to be added to the SlaMap. Each string is derived
      from the name of the SLALIB routine that performs the
      conversion and the relevant documentation (SUN/67) should be
      consulted for details.  Where arguments are needed by
      the conversion, they are listed in parentheses. Values for
      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
      order indicated. The argument names match the corresponding
      SLALIB routine arguments and their values should be given using
      exactly the same units, time scale, calendar, etc. as described
      in SUN/67:

      \sstitemlist{

         \sstitem
         \texttt{"} ADDET\texttt{"}  (EQ): Add E-terms of aberration.

         \sstitem
         \texttt{"} SUBET\texttt{"}  (EQ): Subtract E-terms of aberration.

         \sstitem
         \texttt{"} PREBN\texttt{"}  (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4)
         precession model.

         \sstitem
         \texttt{"} PREC\texttt{"}  (EP0,EP1): Apply IAU 1975 (FK5) precession model.

         \sstitem
         \texttt{"} FK45Z\texttt{"}  (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax).

         \sstitem
         \texttt{"} FK54Z\texttt{"}  (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax).

         \sstitem
         \texttt{"} AMP\texttt{"}  (DATE,EQ): Convert geocentric apparent to mean place.

         \sstitem
         \texttt{"} MAP\texttt{"}  (EQ,DATE): Convert mean place to geocentric apparent.

         \sstitem
         \texttt{"} ECLEQ\texttt{"}  (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial.

         \sstitem
         \texttt{"} EQECL\texttt{"}  (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates.

         \sstitem
         \texttt{"} GALEQ\texttt{"} : Convert galactic coordinates to FK5 J2000.0 equatorial.

         \sstitem
         \texttt{"} EQGAL\texttt{"} : Convert FK5 J2000.0 equatorial to galactic coordinates.

         \sstitem
         \texttt{"} HFK5Z\texttt{"}  (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial.

         \sstitem
         \texttt{"} FK5HZ\texttt{"}  (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS.

         \sstitem
         \texttt{"} GALSUP\texttt{"} : Convert galactic to supergalactic coordinates.

         \sstitem
         \texttt{"} SUPGAL\texttt{"} : Convert supergalactic coordinates to galactic.

         \sstitem
         \texttt{"} J2000H\texttt{"} : Convert dynamical J2000.0 to ICRS.

         \sstitem
         \texttt{"} HJ2000\texttt{"} : Convert ICRS to dynamical J2000.0.

         \sstitem
         \texttt{"} R2H\texttt{"}  (LAST): Convert RA to Hour Angle.

         \sstitem
         \texttt{"} H2R\texttt{"}  (LAST): Convert Hour Angle to RA.

      }
      For example, to use the \texttt{"} ADDET\texttt{"}  conversion, which takes a single
      argument EQ, you should consult the documentation for the SLALIB
      routine SLA\_ADDET. This describes the conversion in detail and
      shows that EQ is the Besselian epoch of the mean equator and
      equinox.
      This value should then be supplied to astSlaAdd in args[0].

      In addition the following strings may be supplied for more complex
      conversions which do not correspond to any one single SLALIB routine
      (DIURAB is the magnitude of the diurnal aberration vector in units
      of \texttt{"} day/(2.PI)\texttt{"} , DATE is the Modified Julian Date of the observation,
      and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian
      coordinates, in metres, of the observer):

      \sstitemlist{

         \sstitem
         \texttt{"} HPCEQ\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial.

         \sstitem
         \texttt{"} EQHPC\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian.

         \sstitem
         \texttt{"} HPREQ\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial.

         \sstitem
         \texttt{"} EQHPR\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial.

         \sstitem
         \texttt{"} HEEQ\texttt{"}  (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial.

         \sstitem
         \texttt{"} EQHE\texttt{"}  (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic.

         \sstitem
         \texttt{"} H2E\texttt{"}  (LAT,DIRUAB): Convert horizon coordinates to equatorial.

         \sstitem
         \texttt{"} E2H\texttt{"}  (LAT,DIURAB): Convert equatorial coordinates to horizon.

      }
      Note, the \texttt{"} H2E\texttt{"}  and \texttt{"} E2H\texttt{"}  conversions convert between topocentric
      horizon coordinates (azimuth,elevation), and apparent local equatorial
      coordinates (hour angle,declination). Thus, the effects of diurnal
      aberration are taken into account in the conversions but the effects
      of atmospheric refraction are not.
   }
}
\sstroutine{
   astSlaMap
}{
   Create an SlaMap
}{
   \sstdescription{
      This function creates a new \htmlref{SlaMap}{SlaMap} and optionally initialises
      its attributes.

      An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
      represent a sequence of conversions between standard celestial
      (longitude, latitude) coordinate systems.

      When an SlaMap is first created, it simply performs a unit
      (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd}
      function, a series of coordinate conversion steps may then be
      added, selected from those provided by the SLALIB Positional
      Astronomy Library (Starlink User Note SUN/67). This allows
      multi-step conversions between a variety of celestial coordinate
      systems to be assembled out of the building blocks provided by
      SLALIB.

      For details of the individual coordinate conversions available,
      see the description of the astSlaAdd function.
   }
   \sstsynopsis{
      AstSlaMap $*$astSlaMap( int flags, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         flags
      }{
         This parameter is reserved for future use and should currently
         always be set to zero.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SlaMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSlaMap()
      }{
         A pointer to the new SlaMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes (number of input and output
         coordinates) for an SlaMap are both equal to 2. The first
         coordinate is the celestial longitude and the second coordinate
         is the celestial latitude. All coordinate values are in radians.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSpecAdd
}{
   Add a spectral coordinate conversion to a SpecMap
}{
   \sstdescription{
      This function adds one of the standard spectral coordinate
      system conversions listed below to an existing \htmlref{SpecMap}{SpecMap}.

      When a SpecMap is first created (using \htmlref{astSpecMap}{astSpecMap}), it simply
      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSpecAdd (repeatedly
      if necessary), one or more coordinate conversion steps may then
      be added, which the SpecMap will perform in sequence. This allows
      multi-step conversions between a variety of spectral coordinate
      systems to be assembled out of the building blocks provided by
      this class.

      Normally, if a SpecMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
      then its forward transformation is performed by carrying out
      each of the individual coordinate conversions specified by
      astSpecAdd in the order given (i.e. with the most recently added
      conversion applied last).

      This order is reversed if the SpecMap\texttt{'} s Invert attribute is
      non-zero (or if the inverse transformation is requested by any
      other means) and each individual coordinate conversion is also
      replaced by its own inverse. This process inverts the overall
      effect of the SpecMap. In this case, the first conversion to be
      applied would be the inverse of the one most recently added.
   }
   \sstsynopsis{
      void astSpecAdd( AstSpecMap $*$this, const char $*$cvt, const double args[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the SpecMap.
      }
      \sstsubsection{
         cvt
      }{
         Pointer to a null-terminated string which identifies the
         spectral coordinate conversion to be added to the
         SpecMap. See the \texttt{"} Available Conversions\texttt{"}  section for details of
         those available.
      }
      \sstsubsection{
         args
      }{
         An array containing argument values for the spectral
         coordinate conversion. The number of arguments required, and
         hence the number of array elements used, depends on the
         conversion specified (see the \texttt{"} Available Conversions\texttt{"}
         section). This array is ignored
         and a NULL pointer may be supplied
         if no arguments are needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When assembling a multi-stage conversion, it can sometimes be
         difficult to determine the most economical conversion path. For
         example, when converting between reference frames, converting first
         to the heliographic reference frame as an intermediate stage is often
         sensible in formulating the problem, but may introduce unnecessary
         extra conversion steps. A solution to this is to include all the steps
         which are (logically) necessary, but then to use
         \htmlref{astSimplify}{astSimplify} to simplify the resulting
         SpecMap. The simplification process will eliminate any steps
         which turn out not to be needed.

         \sstitem
         This function does not check to ensure that the sequence of
         coordinate conversions added to a SpecMap is physically
         meaningful.
      }
   }
   \sstdiytopic{
      Available Conversions
   }{
      The following strings (which are case-insensitive) may be supplied
      via the \texttt{"} cvt\texttt{"}  parameter to indicate which spectral coordinate
      conversion is to be added to the SpecMap. Where arguments are needed by
      the conversion, they are listed in parentheses. Values for
      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
      order indicated. Units and argument names are described at the end of
      the list of conversions.

      \sstitemlist{

         \sstitem
         \texttt{"} FRTOVL\texttt{"}  (RF): Convert frequency to relativistic velocity.

         \sstitem
         \texttt{"} VLTOFR\texttt{"}  (RF): Convert relativistic velocity to Frequency.

         \sstitem
         \texttt{"} ENTOFR\texttt{"} : Convert energy to frequency.

         \sstitem
         \texttt{"} FRTOEN\texttt{"} : Convert frequency to energy.

         \sstitem
         \texttt{"} WNTOFR\texttt{"} : Convert wave number to frequency.

         \sstitem
         \texttt{"} FRTOWN\texttt{"} : Convert frequency to wave number.

         \sstitem
         \texttt{"} WVTOFR\texttt{"} : Convert wavelength (vacuum) to frequency.

         \sstitem
         \texttt{"} FRTOWV\texttt{"} : Convert frequency to wavelength (vacuum).

         \sstitem
         \texttt{"} AWTOFR\texttt{"} : Convert wavelength (air) to frequency.

         \sstitem
         \texttt{"} FRTOAW\texttt{"} : Convert frequency to wavelength (air).

         \sstitem
         \texttt{"} VRTOVL\texttt{"} : Convert radio to relativistic velocity.

         \sstitem
         \texttt{"} VLTOVR\texttt{"} : Convert relativistic to radio velocity.

         \sstitem
         \texttt{"} VOTOVL\texttt{"} : Convert optical to relativistic velocity.

         \sstitem
         \texttt{"} VLTOVO\texttt{"} : Convert relativistic to optical velocity.

         \sstitem
         \texttt{"} ZOTOVL\texttt{"} : Convert redshift to relativistic velocity.

         \sstitem
         \texttt{"} VLTOZO\texttt{"} : Convert relativistic velocity to redshift.

         \sstitem
         \texttt{"} BTTOVL\texttt{"} : Convert beta factor to relativistic velocity.

         \sstitem
         \texttt{"} VLTOBT\texttt{"} : Convert relativistic velocity to beta factor.

         \sstitem
         \texttt{"} USF2HL\texttt{"}  (VOFF,RA,DEC): Convert frequency from a user-defined
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2US\texttt{"}  (VOFF,RA,DEC): Convert frequency from heliocentric
         reference frame to user-defined.

         \sstitem
         \texttt{"} TPF2HL\texttt{"}  (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from
         topocentric reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2TP\texttt{"}  (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from
         heliocentric reference frame to topocentric.

         \sstitem
         \texttt{"} GEF2HL\texttt{"}  (EPOCH,RA,DEC): Convert frequency from geocentric
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2GE\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
         heliocentric reference frame to geocentric.

         \sstitem
         \texttt{"} BYF2HL\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
         barycentric reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2BY\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
         heliocentric reference frame to barycentric.

         \sstitem
         \texttt{"} LKF2HL\texttt{"}  (RA,DEC): Convert frequency from kinematic LSR
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2LK\texttt{"}  (RA,DEC): Convert frequency from heliocentric
         reference frame to kinematic LSR.

         \sstitem
         \texttt{"} LDF2HL\texttt{"}  (RA,DEC): Convert frequency from dynamical LSR
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2LD\texttt{"}  (RA,DEC): Convert frequency from heliocentric
         reference frame to dynamical LSR.

         \sstitem
         \texttt{"} LGF2HL\texttt{"}  (RA,DEC): Convert frequency from local group
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2LG\texttt{"}  (RA,DEC): Convert frequency from heliocentric
         reference frame to local group.

         \sstitem
         \texttt{"} GLF2HL\texttt{"}  (RA,DEC): Convert frequency from galactic
         reference frame to heliocentric.

         \sstitem
         \texttt{"} HLF2GL\texttt{"}  (RA,DEC): Convert frequency from heliocentric
         reference frame to galactic.

      }
      The units for the values processed by the above conversions are as
      follows:

      \sstitemlist{

         \sstitem
         all velocities: metres per second (positive if the source receeds from
           the observer).

         \sstitem
         frequency: Hertz.

         \sstitem
         all wavelengths: metres.

         \sstitem
         energy: Joules.

         \sstitem
         wave number: cycles per metre.

      }
      The arguments used in the above conversions are as follows:

      \sstitemlist{

         \sstitem
         RF: Rest frequency (Hz).

         \sstitem
         OBSALT: Geodetic altitude of observer (IAU 1975, metres).

         \sstitem
         OBSLAT: Geodetic latitude of observer (IAU 1975, radians).

         \sstitem
         OBSLON: Longitude of observer (radians - positive eastwards).

         \sstitem
         EPOCH: \htmlref{Epoch}{Epoch} of observation (UT1 expressed as a Modified Julian Date).

         \sstitem
         RA: Right Ascension of source (radians, FK5 J2000).

         \sstitem
         DEC: Declination of source (radians, FK5 J2000).

         \sstitem
         VOFF: Velocity of the user-defined reference frame, towards the
         position given by RA and DEC, measured in the heliocentric
         reference frame.

      }
      If the SpecMap is 3-dimensional, source positions are provided by the
      values supplied to inputs 2 and 3 of the SpecMap (which are simply
      copied to outputs 2 and 3). Note, usable values are still required
      for the RA and DEC arguments in order to define the \texttt{"} user-defined\texttt{"}
      reference frame used by USF2HL and HLF2US. However, AST\_\_BAD can be
      supplied for RA and DEC if the user-defined reference frame is not
      required.
   }
}
\sstroutine{
   astSpecFluxFrame
}{
   Create a SpecFluxFrame
}{
   \sstdescription{
      This function creates a new \htmlref{SpecFluxFrame}{SpecFluxFrame} and optionally initialises
      its attributes.

      A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single
      2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used
      to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents
      spectral position and the second axis represents flux.
   }
   \sstsynopsis{
      AstSpecFluxFrame $*$astSpecFluxFrame( AstSpecFrame $*$frame1, AstFluxFrame $*$frame2,
                                          const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         frame1
      }{
         Pointer to the SpecFrame. This will form the first axis in the
         new SpecFluxFrame.
      }
      \sstsubsection{
         frame2
      }{
         Pointer to the FluxFrame. This will form the second axis in the
         new SpecFluxFrame. The \texttt{"} \htmlref{SpecVal}{SpecVal}\texttt{"}  attribute of this FluxFrame is
         not used by the SpecFluxFrame class and so may be set to AST\_\_BAD
         when the FluxFrame is created.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SpecFluxFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSpecFluxFrame()
      }{
         A pointer to the new SpecFluxFrame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The supplied Frame pointers are stored directly, rather than
         being used to create deep copies of the supplied Frames. This means
         that any subsequent changes made to the Frames via the supplied
         pointers will result in equivalent changes being visible in the
         SpecFluxFrame.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astSpecFrame
}{
   Create a SpecFrame
}{
   \sstdescription{
      This function creates a new \htmlref{SpecFrame}{SpecFrame} and optionally initialises
      its attributes.

      A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various coordinate systems used to describe positions within
      an electro-magnetic spectrum. The particular coordinate system to be
      used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the
      default is wavelength) qualified, as necessary, by other attributes
      such as the rest frequency, the standard of rest, the epoch of
      observation, etc (see the description of the System attribute for
      details).

      By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made
      to represent offsets from a given spectral position, rather than absolute
   }
   \sstsynopsis{
      AstSpecFrame $*$astSpecFrame( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SpecFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSpecFrame()
      }{
         A pointer to the new SpecFrame.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         frame = astSpecFrame( \texttt{"} \texttt{"}  );
      }{
         Creates a SpecFrame to describe the default wavelength spectral
         coordinate system. The \htmlref{RestFreq}{RestFreq} attribute (rest frequency) is
         unspecified, so it will not be possible to align this SpecFrame
         with another SpecFrame on the basis of a velocity-based system. The
         standard of rest is also unspecified. This means that alignment
         will be possible with other SpecFrames, but no correction will be
         made for Doppler shift caused by change of rest frame during the
         alignment.
      }
      \sstexamplesubsection{
         frame = astSpecFrame( \texttt{"} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{"}  );
      }{
         Creates a SpecFrame describing a apparent radial velocity (\texttt{"} VELO\texttt{"} ) axis
         with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured
         in the kinematic Local Standard of Rest (\texttt{"} LSRK\texttt{"} ). Since the
         source position has not been specified (using attributes \htmlref{RefRA}{RefRA} and
         \htmlref{RefDec}{RefDec}), it will only be possible to align this SpecFrame with
         other SpecFrames which are also measured in the LSRK standard of
         rest.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When conversion between two SpecFrames is requested (as when
         supplying SpecFrames to \htmlref{astConvert}{astConvert}),
         account will be taken of the nature of the spectral coordinate systems
         they represent, together with any qualifying rest frequency, standard
         of rest, epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}
         attributes will also be taken into account. The results will therefore
         fully reflect the relationship between positions measured in the two
         systems. In addition, any difference in the Unit attributes of the two
         systems will also be taken into account.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSpecMap
}{
   Create a SpecMap
}{
   \sstdescription{
      This function creates a new \htmlref{SpecMap}{SpecMap} and optionally initialises
      its attributes.

      An SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
      represent a sequence of conversions between standard spectral
      coordinate systems. This includes conversions between frequency,
      wavelength, and various forms of velocity, as well as conversions
      between different standards of rest.

      When a SpecMap is first created, it simply performs a unit
      (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} function,
      a series of coordinate conversion steps may then be added, selected
      from the list of supported conversions. This allows multi-step
      conversions between a variety of spectral coordinate systems to
      be assembled out of the building blocks provided by this class.

      For details of the individual coordinate conversions available,
      see the description of the astSpecAdd function.

      Conversions are available to transform between standards of rest.
      Such conversions need to know the source position as an RA and DEC.
      This information can be supplied in the form of parameters for
      the relevant conversions, in which case the SpecMap is 1-dimensional,
      simply transforming the spectral axis values. This means that the
      same source position will always be used by the SpecMap. However, this
      may not be appropriate for an accurate description of a 3-D spectral
      cube, where changes of spatial position can produce significant
      changes in the Doppler shift introduced when transforming between
      standards of rest. For this situation, a 3-dimensional SpecMap can
      be created in which axes 2 and 3 correspond to the source RA and DEC
      The SpecMap simply copies values for axes 2 and 3 from input to
      output).
   }
   \sstsynopsis{
      AstSpecMap $*$astSpecMap( int nin, int flags, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         nin
      }{
         The number of inputs to the Mapping (this will also equal the
         number of outputs). This value must be either 1 or 3. In either
         case, the first input and output correspoindis the spectral axis.
         For a 3-axis SpecMap, the second and third axes give the RA and
         DEC (J2000 FK5) of the source. This positional information is
         used by conversions which transform between standards of rest,
         and replaces the \texttt{"} RA\texttt{"}  and \texttt{"} DEC\texttt{"}  arguments for the individual
         conversions listed in description of the \texttt{"} SpecAdd\texttt{"}
         function.
      }
      \sstsubsection{
         flags
      }{
         This parameter is reserved for future use and should currently
         always be set to zero.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SpecMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSpecMap()
      }{
         A pointer to the new SpecMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The nature and units of the coordinate values supplied for the
         first input (i.e. the spectral input) of a SpecMap must be appropriate
         to the first conversion step applied by the SpecMap. For instance, if
         the first conversion step is \texttt{"} FRTOVL\texttt{"}  (frequency to relativistic
         velocity), then the coordinate values for the first input should
         be frequency in units of Hz. Similarly, the nature and units of the
         coordinate values returned by a SpecMap will be determined by the
         last conversion step applied by the SpecMap. For instance, if the
         last conversion step is \texttt{"} VLTOVO\texttt{"}  (relativistic velocity to optical
         velocity), then the coordinate values for the first output will be optical
         velocity in units of metres per second. See the description of the
         astSpecAdd function for the units expected and returned by each
         conversion.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astSphMap
}{
   Create a SphMap
}{
   \sstdescription{
      This function creates a new \htmlref{SphMap}{SphMap} and optionally initialises
      its attributes.

      A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a
      3-dimensional Cartesian coordinate system into a 2-dimensional
      spherical coordinate system (longitude and latitude on a unit
      sphere centred at the origin). It works by regarding the input
      coordinates as position vectors and finding their intersection
      with the sphere surface. The inverse transformation always
      produces points which are a unit distance from the origin
      (i.e. unit vectors).
   }
   \sstsynopsis{
      AstSphMap $*$astSphMap( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SphMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSphMap()
      }{
         A pointer to the new SphMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The spherical coordinates are longitude (positive
         anti-clockwise looking from the positive latitude pole) and
         latitude. The Cartesian coordinates are right-handed, with the x
         axis (axis 1) at zero longitude and latitude, and the z axis
         (axis 3) at the positive latitude pole.

         \sstitem
         At either pole, the longitude is set to the value of the
         \htmlref{PolarLong}{PolarLong} attribute.

         \sstitem
         If the Cartesian coordinates are all zero, then the longitude
         and latitude are set to the value AST\_\_BAD.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astStatus
}{
   Obtain the current AST error status value
}{
   \sstdescription{
      This function returns the current value of the AST error status.
   }
   \sstsynopsis{
      int astStatus
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStatus
      }{
         The AST error status value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the AST error status is set to an error value (after an
         error), most AST functions will not execute and will simply
         return without action. To clear the error status and restore
         normal behaviour, use \htmlref{astClearStatus}{astClearStatus}.
      }
   }
}
\sstroutine{
   astStcCatalogEntryLocation
}{
   Create a StcCatalogEntryLocation
}{
   \sstdescription{
      This function creates a new \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} and optionally initialises its
      attributes.

      The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of the datasets contained in some VO resource.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstsynopsis{
      AstStcCatalogEntryLocation $*$astStcCatalogEntryLocation( AstRegion $*$region,
                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region
      }{
         Pointer to the encapsulated \htmlref{Region}{Region}.
      }
      \sstsubsection{
         ncoords
      }{
         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
      }
      \sstsubsection{
         coords
      }{
         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
         describes the contents of a single STC $<$AstroCoords$>$ element, and
         should have elements with keys given by constants AST\_\_STCNAME,
         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
         elements should be included. If supplied, the AST\_\_STCNAME element
         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
         item for each axis in the coordinate system represented by
         \texttt{"} region\texttt{"} .
         Any other supplied elements should be scalar elements, each  holding
         a pointer to a Region describing the associated item of ancillary
         information (error, resolution, size, pixel size or value). These
         Regions should describe a volume within the coordinate system
         represented by \texttt{"} region\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new StcCatalogEntryLocation. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStcCatalogEntryLocation()
      }{
         A pointer to the new StcCatalogEntryLocation.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A deep copy is taken of the supplied Region. This means that
         any subsequent changes made to the encapsulated Region using the
         supplied pointer will have no effect on the Stc.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astStcObsDataLocation
}{
   Create a StcObsDataLocation
}{
   \sstdescription{
      This function creates a new \htmlref{StcObsDataLocation}{StcObsDataLocation} and optionally initialises its
      attributes.

      The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of the datasets contained in some VO resource.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstsynopsis{
      AstStcObsDataLocation $*$astStcObsDataLocation( AstRegion $*$region,
                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region
      }{
         Pointer to the encapsulated \htmlref{Region}{Region}.
      }
      \sstsubsection{
         ncoords
      }{
         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
      }
      \sstsubsection{
         coords
      }{
         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
         describes the contents of a single STC $<$AstroCoords$>$ element, and
         should have elements with keys given by constants AST\_\_STCNAME,
         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
         elements should be included. If supplied, the AST\_\_STCNAME element
         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
         item for each axis in the coordinate system represented by
         \texttt{"} region\texttt{"} .
         Any other supplied elements should be scalar elements, each  holding
         a pointer to a Region describing the associated item of ancillary
         information (error, resolution, size, pixel size or value). These
         Regions should describe a volume within the coordinate system
         represented by \texttt{"} region\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new StcObsDataLocation. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStcObsDataLocation()
      }{
         A pointer to the new StcObsDataLocation.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A deep copy is taken of the supplied Region. This means that
         any subsequent changes made to the encapsulated Region using the
         supplied pointer will have no effect on the Stc.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astStcResourceProfile
}{
   Create a StcResourceProfile
}{
   \sstdescription{
      This function creates a new \htmlref{StcResourceProfile}{StcResourceProfile} and optionally initialises its
      attributes.

      The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of the datasets contained in some VO resource.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstsynopsis{
      AstStcResourceProfile $*$astStcResourceProfile( AstRegion $*$region,
                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region
      }{
         Pointer to the encapsulated \htmlref{Region}{Region}.
      }
      \sstsubsection{
         ncoords
      }{
         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
      }
      \sstsubsection{
         coords
      }{
         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
         describes the contents of a single STC $<$AstroCoords$>$ element, and
         should have elements with keys given by constants AST\_\_STCNAME,
         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
         elements should be included. If supplied, the AST\_\_STCNAME element
         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
         item for each axis in the coordinate system represented by
         \texttt{"} region\texttt{"} .
         Any other supplied elements should be scalar elements, each  holding
         a pointer to a Region describing the associated item of ancillary
         information (error, resolution, size, pixel size or value). These
         Regions should describe a volume within the coordinate system
         represented by \texttt{"} region\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new StcResourceProfile. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStcResourceProfile()
      }{
         A pointer to the new StcResourceProfile.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A deep copy is taken of the supplied Region. This means that
         any subsequent changes made to the encapsulated Region using the
         supplied pointer will have no effect on the Stc.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astStcSearchLocation
}{
   Create a StcSearchLocation
}{
   \sstdescription{
      This function creates a new \htmlref{StcSearchLocation}{StcSearchLocation} and optionally initialises its
      attributes.

      The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of a VO query.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstsynopsis{
      AstStcResourceProfile $*$astStcSearchLocation( AstRegion $*$region,
                    int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         region
      }{
         Pointer to the encapsulated \htmlref{Region}{Region}.
      }
      \sstsubsection{
         ncoords
      }{
         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
      }
      \sstsubsection{
         coords
      }{
         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
         describes the contents of a single STC $<$AstroCoords$>$ element, and
         should have elements with keys given by constants AST\_\_STCNAME,
         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
         elements should be included. If supplied, the AST\_\_STCNAME element
         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
         item for each axis in the coordinate system represented by
         \texttt{"} region\texttt{"} .
         Any other supplied elements should be scalar elements, each  holding
         a pointer to a Region describing the associated item of ancillary
         information (error, resolution, size, pixel size or value). These
         Regions should describe a volume within the coordinate system
         represented by \texttt{"} region\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new StcSearchLocation. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStcSearchLocation()
      }{
         A pointer to the new StcSearchLocation.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A deep copy is taken of the supplied Region. This means that
         any subsequent changes made to the encapsulated Region using the
         supplied pointer will have no effect on the Stc.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astStcsChan
}{
   Create an StcsChan
}{
   \sstdescription{
      This function creates a new \htmlref{StcsChan}{StcsChan} and optionally initialises
      its attributes.

      A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S
      I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
      STC-S description of that Object, and reading from an StcsChan will
      create a new Object from its STC-S description.

      Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting text. These functions
      should perform any conversions needed between external character
      encodings and the internal ASCII encoding. If no such functions
      are supplied, a Channel will read from standard input and write
      to standard output.

      Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.
   }
   \sstsynopsis{
      AstStcsChan $*$astStcsChan( const char $*$($*$ source)( void ),
                                void ($*$ sink)( const char $*$ ),
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         source
      }{
         Pointer to a source function that takes no arguments and
         returns a pointer to a null-terminated string.  If no value
         has been set for the SourceFile attribute, this function
         will be used by the StcsChan to obtain lines of input text. On
         each invocation, it should return a pointer to the next input
         line read from some external data store, and a NULL pointer
         when there are no more lines to read.

         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
         attribute, the StcsChan will read from standard input instead.
      }
      \sstsubsection{
         sink
      }{
         Pointer to a sink function that takes a pointer to a
         null-terminated string as an argument and returns void.
         If no value has been set for the SinkFile attribute, this
         function will be used by the StcsChan to deliver lines of
         output text. On each invocation, it should deliver the
         contents of the string supplied to some external data store.

         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
         attribute, the StcsChan will write to standard output instead.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new StcsChan. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStcsChan()
      }{
         A pointer to the new StcsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the external data source or sink uses a character encoding
         other than ASCII, the supplied source and sink functions should
         translate between the external character encoding and the internal
         ASCII encoding used by AST.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astStripEscapes
}{
   Remove AST escape sequences from a string
}{
   \sstdescription{
      This function removes AST escape sequences from a supplied string,
      returning the resulting text as the function value. The behaviour
      of this function can be controlled by invoking the
      \htmlref{astEscapes}{astEscapes} function,
      which can be used to supress or enable the removal of escape
      sequences by this function.

      AST escape sequences are used by the \htmlref{Plot}{Plot} class to modify the
      appearance and position of sub-strings within a plotted text string.
      See the \texttt{"} \htmlref{Escape}{Escape}\texttt{"}  attribute for further information.
   }
   \sstsynopsis{
      const char $*$astStripEscapes( const char $*$text )
   }
   \sstparameters{
      \sstsubsection{
         text
      }{
         Pointer to the string to be checked.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStripEscapes()
      }{
         Pointer to the modified string. If no escape sequences were found
         in the supplied string, then a copy of the supplied pointer is
         returned. Otherwise, the pointer will point to a static buffer
         holding the modified text. This text will be over-written by
         subsequent invocations of this function. If the astEscapes function
         has been called indicating that escape sequences should not be
         stripped, then the supplied string is returned without change.
      }
   }
}
\sstroutine{
   astSwitchMap
}{
   Create a SwitchMap
}{
   \sstdescription{
      This function creates a new \htmlref{SwitchMap}{SwitchMap} and optionally initialises
      its attributes.

      A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate
      Mappings, each of which is used to transform positions within a
      particular region of the input or output coordinate system of the
      SwitchMap.

      A SwitchMap can encapsulate any number of Mappings, but they must
      all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the
      same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself
      inherits these same values for its Nin and Nout attributes. Each of
      these Mappings represents a \texttt{"} route\texttt{"}  through the switch, and are
      referred to as \texttt{"} route\texttt{"}  Mappings below. Each route Mapping transforms
      positions between the input and output coordinate space of the entire
      SwitchMap, but only one Mapping will be used to transform any given
      position. The selection of the appropriate route Mapping to use with
      any given input position is made by another Mapping, called the
      \texttt{"} selector\texttt{"}  Mapping. Each SwitchMap encapsulates two selector
      Mappings in addition to its route Mappings; one for use with the
      SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector
      Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation
      (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping
      must have the same number of inputs as the route Mappings, but
      should have only one output. Likewise, the inverse selector Mapping
      must have the same number of outputs as the route Mappings, but
      should have only one input.

      When the SwitchMap is used to transform a position in the forward
      direction (from input to output), each supplied input position is
      first transformed by the forward transformation of the forward selector
      Mapping. This produces a single output value for each input position
      referred to as the selector value. The nearest integer to the selector
      value is found, and is used to index the array of route Mappings (the
      first supplied route Mapping has index 1, the second route Mapping has
      index 2, etc). If the nearest integer to the selector value is less
      than 1 or greater than the number of route Mappings, then the SwitchMap
      output position is set to a value of AST\_\_BAD on every axis. Otherwise,
      the forward transformation of the selected route Mapping is used to
      transform the supplied input position to produce the SwitchMap output
      position.

      When the SwitchMap is used to transform a position in the inverse
      direction (from \texttt{"} output\texttt{"}  to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"}  position
      is first transformed by the inverse transformation of the inverse
      selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"}
      position. Again, the nearest integer to the selector value is found,
      and is used to index the array of route Mappings. If this selector
      index value is within the bounds of the array of route Mappings, then
      the inverse transformation of the selected route Mapping is used to
      transform the supplied \texttt{"} output\texttt{"}  position to produce the SwitchMap
      \texttt{"} input\texttt{"}  position. If the selector index value is outside the bounds
      of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"}  position is
      set to a value of AST\_\_BAD on every axis.

      In practice, appropriate selector Mappings should be chosen to
      associate a different route Mapping with each region of coordinate
      space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly
      appropriate for this purpose.

      If a compound Mapping contains a SwitchMap in series with its own
      inverse, the combination of the two adjacent SwitchMaps will be
      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
      \htmlref{astSimplify}{astSimplify}.
   }
   \sstsynopsis{
      AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap,
                                  int nroute, AstMapping $*$routemaps[],
                                  const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         fsmap
      }{
         Pointer to the forward selector Mapping. This must have a
         defined forward transformation, but need not have a defined
         inverse transformation. It must have one output, and the number of
         inputs must match the number of inputs of each of the supplied
         route Mappings.
         NULL
         may be supplied, in which case the SwitchMap will have an undefined
         forward Mapping.
      }
      \sstsubsection{
         ismap
      }{
         Pointer to the inverse selector Mapping. This must have a
         defined inverse transformation, but need not have a defined
         forward transformation. It must have one input, and the number of
         outputs must match the number of outputs of each of the supplied
         route Mappings.
         NULL
         may be supplied, in which case the SwitchMap will have an undefined
         inverse Mapping.
      }
      \sstsubsection{
         nroute
      }{
         The number of supplied route Mappings.
      }
      \sstsubsection{
         routemaps
      }{
         An array of pointers to the route Mappings. All the supplied
         route Mappings must have common values for the Nin and Nout
         attributes, and these values define the number of inputs and
         outputs of the SwitchMap.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new SwitchMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSwitchMap()
      }{
         A pointer to the new SwitchMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Note that the component Mappings supplied are not copied by
         astSwitchMap (the new SwitchMap simply retains a reference to
         them). They may continue to be used for other purposes, but
         should not be deleted. If a SwitchMap containing a copy of its
         component Mappings is required, then a copy of the SwitchMap should
         be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astTable
}{
   Create a Table
}{
   \sstdescription{
      This function creates a new empty \htmlref{Table}{Table} and optionally initialises
      its attributes.

      The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional
      table of values. The
      astMapGet... and astMapPut...
      methods provided by the KeyMap class should be used for storing and
      retrieving values from individual cells within a Table. Each entry
      in the KeyMap represents a single cell of the table and has an
      associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"}  where \texttt{"} $<$COL$>$\texttt{"}  is the name of a
      table column and \texttt{"} i\texttt{"}  is the row index (the first row is row 1). Keys
      of this form should always be used when using KeyMap methods to access
      entries within a Table.

      Columns must be declared using the
      \htmlref{astAddColumn}{astAddColumn}
      method before values can be stored within them. This also fixes the
      type and shape of the values that may be stored in any cell of the
      column. Cells may contain scalar or vector values of any data type
      supported by the KeyMap class. Multi-dimensional arrays may also be
      stored, but these must be vectorised when storing and retrieving
      them within a table cell. All cells within a single column must
      have the same type and shape (specified when the column is declared).

      Tables may have parameters that describe global properties of the
      entire table. These are stored as entries in the parent KeyMap and
      can be access using the get and set method of the KeyMap class.
      However, parameters must be declared using the
      \htmlref{astAddParameter}{astAddParameter}
      method before being accessed.

      Note - since accessing entries within a KeyMap is a relatively slow
      process, it is not recommended to use the Table class to store
      very large tables.
   }
   \sstsynopsis{
      AstTable $*$astTable( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new Table. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTable()
      }{
         A pointer to the new Table.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list described above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astTableSource
}{
   Register a source function for accessing tables in FITS files
}{
   \sstdescription{
      This function can be used to register a call-back function
      with a \htmlref{FitsChan}{FitsChan}. The registered
      function
      is called when-ever the FitsChan needs to read information from a
      binary table contained within a FITS file. This occurs if the
      \htmlref{astRead}{astRead}
      function is invoked to read a \htmlref{FrameSet}{FrameSet} from a set of FITS headers
      that use the \texttt{"} -TAB\texttt{"}  algorithm to describe one or more axes. Such
      axes use a FITS binary table to store a look-up table of axis values.
      The FitsChan will fail to read such axes unless the \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"}  attribute
      is set to a non-zero positive integer value. The table containing the
      axis values must be made available to the FitsChan either by storing
      the table contents in the FitsChan (using
      \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) prior to invoking astRead
      or by registering a call-back
      function using astTableSource.
      The first method is possibly simpler, but requires that the name of
      the extension containing the table be known in advance. Since the
      table name is embedded in the FITS headers, the name is often not
      known in advance. If a call-back is registered, the FitsChan will
      determine the name of the required table and invoke the call-back
      function
      to supply the table at the point where it is needed (i.e. within
      the astRead method).
   }
   \sstsynopsis{
      void astTableSource( AstFitsChan $*$this,
                           void ($*$ tabsource)( AstFitsChan $*$, const char $*$,
                                               int, int, int $*$ ) )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         tabsource
      }{
         Pointer to the table source function to use.
         It takes five arguments - the first is a pointer to the
         FitsChan, the second is a string holding the name of the
         FITS extension containing the required binary table (\texttt{"} EXTNAME\texttt{"} ),
         the third is the integer FITS \texttt{"} EXTVER\texttt{"}  header value for the
         required extension, the fourth is the integer FITS \texttt{"} EXTLEVEL\texttt{"}
         header value for the required extension, and the fifth is
         a pointer to
         the inherited integer status value.

         The call-back should read the entire contents (header and data)
         of the binary table in the named extension of the external FITS
         file, storing the contents in a newly created \htmlref{FitsTable}{FitsTable} object. It
         should then store this FitsTable in the FitsChan using the
         astPutTables or astPutTable
         method, and finally annull its local copy of the FitsTable pointer.
         If the table cannot be read for any reason, or if any other
         error occurs, it should return a non-zero integer for the final
         (third) argument.

         If \texttt{"} tabsource\texttt{"}  is NULL,
         any registered call-back function will be removed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Application code can pass arbitrary data (such as file
         descriptors, etc) to the table source function using the
         \htmlref{astPutChannelData}{astPutChannelData} function. The source function should use
         the \htmlref{astChannelData}{astChannelData} macro to retrieve this data.
      }
   }
}
\sstroutine{
   astTest
}{
   Test if an Object attribute value is set
}{
   \sstdescription{
      This function returns a boolean result (0 or 1) to indicate
      whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s
      attributes.
   }
   \sstsynopsis{
      int astTest( AstObject $*$this, const char $*$attrib )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object.
      }
      \sstsubsection{
         attrib
      }{
         Pointer to a null-terminated character string containing
         the name of the attribute to be tested.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTest()
      }{
         One if a value has previously been explicitly set for the attribute
         (and hasn\texttt{'} t been cleared), otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Attribute names are not case sensitive and may be surrounded
         by white space.

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any reason.

         \sstitem
         A value of zero will also be returned if this function is used
         to test a read-only attribute, although no error will result.
      }
   }
}
\sstroutine{
   astTestFits
}{
   See if a named keyword has a defined value in a FitsChan
}{
   \sstdescription{
      This function serches for a named keyword in a \htmlref{FitsChan}{FitsChan}. If found,
      and if the keyword has a value associated with it, a
      non-zero
      value is returned. If the keyword is not found, or if it does not
      have an associated value, a
      zero
      value is returned.
   }
   \sstsynopsis{
      int astTestFits( AstFitsChan $*$this, const char $*$name, int $*$there )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
      \sstsubsection{
         name
      }{
         Pointer to a null-terminated character string
         containing the FITS keyword name. This may be a complete FITS
         header card, in which case the keyword to use is extracted from
         it. No more than 80 characters are read from this string.
      }
      \sstsubsection{
         there
      }{
         Pointer to an integer which will be returned holding a non-zero
         value if the keyword was found in the header, and zero otherwise.
         This parameter allows a distinction to be made between the case
         where a keyword is not present, and the case where a keyword is
         present but has no associated value.
         A NULL pointer may be supplied if this information is not
         required.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTestFits()
      }{
         A value of zero
         is returned if the keyword was not found in the FitsChan or has
         no associated value. Otherwise, a value of
         one
         is returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The current card is left unchanged by this function.

         \sstitem
         The card following the current card is checked first. If this is
         not the required card, then the rest of the FitsChan is searched,
         starting with the first card added to the FitsChan. Therefore cards
         should be accessed in the order they are stored in the FitsChan (if
         possible) as this will minimise the time spent searching for cards.

         \sstitem
         An error will be reported if the keyword name does not conform
         to FITS requirements.

         \sstitem
         Zero
         is returned as the function value if an error has already occurred,
         or if this function should fail for any reason.
      }
   }
}
\sstroutine{
   astText
}{
   Draw a text string for a Plot
}{
   \sstdescription{
      This function draws a string of text at a position specified in
      the physical coordinate system of a \htmlref{Plot}{Plot}. The physical position
      is transformed into graphical coordinates to determine where the
      text should appear within the plotting area.
   }
   \sstsynopsis{
      void astText( AstPlot $*$this, const char $*$text, const double pos[],
                    const float up[], const char $*$just )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Plot.
      }
      \sstsubsection{
         text
      }{
         Pointer to a null-terminated character string containing the
         text to be drawn. Trailing white space is ignored.
      }
      \sstsubsection{
         pos
      }{
         An array, with one element for each axis of the Plot, giving
         the physical coordinates of the point where the reference
         position of the text string is to be placed.
      }
      \sstsubsection{
         up
      }{
         An array holding the components of a vector in the \texttt{"} up\texttt{"}
         direction of the text (in graphical coordinates). For
         example, to get horizontal text, the vector \{0.0f,1.0f\} should
         be supplied. For a basic Plot, 2 values should be supplied. For
         a \htmlref{Plot3D}{Plot3D}, 3 values should be supplied, and the actual up vector
         used is the projection of the supplied up vector onto the text plane
         specified by the current value of the Plot3D\texttt{'} s Norm attribute.
      }
      \sstsubsection{
         just
      }{
         Pointer to a null-terminated character string identifying the
         reference point for the text being drawn. The first character in
         this string identifies the reference position in the \texttt{"} up\texttt{"}  direction
         and may be \texttt{"} B\texttt{"}  (baseline), \texttt{"} C\texttt{"}  (centre), \texttt{"} T\texttt{"}  (top) or \texttt{"} M\texttt{"}  (bottom).
         The second character identifies the side-to-side reference position
         and may be \texttt{"} L\texttt{"}  (left), \texttt{"} C\texttt{"}  (centre) or \texttt{"} R\texttt{"}  (right ). The string is
         case-insensitive, and only the first two characters are significant.

         For example, a value of \texttt{"} BL\texttt{"}  means that the left end of the
         baseline of the original (un-rotated) text is to be drawn at the
         position given by \texttt{"} pos\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Plot3D class currently does not interpret graphical escape
         sequences contained within text displayed using this method.

         \sstitem
         Text is not drawn at positions which have any coordinate equal
         to the value AST\_\_BAD (or where the transformation into
         graphical coordinates yields coordinates containing the value
         AST\_\_BAD).

         \sstitem
         If the plotting position is clipped (see \htmlref{astClip}{astClip}), then no
         text is drawn.

         \sstitem
         An error results if the base \htmlref{Frame}{Frame} of the Plot is not
         2-dimensional or (for a Plot3D) 3-dimensional.

         \sstitem
         An error also results if the transformation between the
         current and base Frames of the Plot is not defined (i.e. the
         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
      }
   }
}
\sstroutine{
   astThread
}{
   Determine the thread that owns an Object
}{
   \sstdescription{
      Returns an integer that indicates whether the supplied \htmlref{Object}{Object} (or
      Object pointer) is currently unlocked, or is currently locked by
      the running thread, or another thread.
   }
   \sstsynopsis{
      int astThread( AstObject $*$this, int ptr )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be checked.
      }
      \sstsubsection{
         ptr
      }{
         If non-zero, returns information about the supplied Object
         pointer, rather than the Object structure itself. See \texttt{"} Object
         Pointers and Structures\texttt{"}  below.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astThread()
      }{
         A value of AST\_\_UNLOCKED is returned if the Object (or pointer)
         is currently unlocked (i.e. has been unlocked using \htmlref{astUnlock}{astUnlock}
         but has not yet been locked using \htmlref{astLock}{astLock}). A value of
         AST\_\_RUNNING is returned if the Object (or pointer) is currently
         locked by the running thread. A value of AST\_\_OTHER is returned
         if the Object (or pointer) is currently locked by the another
         thread.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to execute even if the global error
         status is set, but no further error report will be made if it
         subsequently fails under these circumstances.

         \sstitem
         This function is only available in the C interface.

         \sstitem
         This function always returns AST\_\_RUNNING if the AST library has
         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
         option was not specified when running the \texttt{"} configure\texttt{"}  script).
      }
   }
   \sstdiytopic{
      Object Pointers and Structures
   }{
      At any one time, an AST Object can have several distinct pointers,
      any one of which can be used to access the Object structure. For
      instance, the \htmlref{astClone}{astClone} function will produce a new distinct pointer
      for a given Object. In fact, an AST \texttt{"} pointer\texttt{"}  is not a real pointer
      at all - it is an identifier for a \texttt{"} handle\texttt{"}  structure, encoded to
      make it look like a pointer. Each handle contains (amongst othere
      things) a \texttt{"} real\texttt{"}  pointer to the Object structure. This allows more
      than one handle to refer to the same Object structure. So when you
      call astClone (for instance) you get back an identifier for a new
      handle that refers to the same Object as the supplied handle.

      In order to use an Object for anything useful, it must be locked
      for use by the running thread (either implicitly at creation or
      explicitly using astLock). The identity of the thread is stored in
      both the Object structure, and in the handle that was passed to
      astLock (or returned by the constructor function). Thus it is
      possible for a thread to have active pointers for Objects that are
      currently locked by another thread. In general, if such a pointer is
      passed to an AST function an error will be reported indicating that
      the Object is currently locked by another thread. The two exceptions
      to this is that \htmlref{astAnnul}{astAnnul} can be used to annull such a pointer, and
      this function can be used to return information about the pointer.

      The other practical consequence of this is that when \htmlref{astEnd}{astEnd} is
      called, all active pointers currently owned by the running thread
      (at the current context level) are annulled. This includes pointers
      for Objects that are currently locked by other threads.

      If the \texttt{"} ptr\texttt{"}  parameter is zero, then the returned value describes
      the Object structure itself. If \texttt{"} ptr\texttt{"}  is non-zero, then the returned
      value describes the supplied Object pointer (i.e. handle), rather
      than the Object structure.
   }
}
\sstroutine{
   astTimeAdd
}{
   Add a time coordinate conversion to a TimeMap
}{
   \sstdescription{
      This function adds one of the standard time coordinate
      system conversions listed below to an existing \htmlref{TimeMap}{TimeMap}.

      When a TimeMap is first created (using \htmlref{astTimeMap}{astTimeMap}), it simply
      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astTimeAdd (repeatedly
      if necessary), one or more coordinate conversion steps may then
      be added, which the TimeMap will perform in sequence. This allows
      multi-step conversions between a variety of time coordinate
      systems to be assembled out of the building blocks provided by
      this class.

      Normally, if a TimeMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
      then its forward transformation is performed by carrying out
      each of the individual coordinate conversions specified by
      astTimeAdd in the order given (i.e. with the most recently added
      conversion applied last).

      This order is reversed if the TimeMap\texttt{'} s Invert attribute is
      non-zero (or if the inverse transformation is requested by any
      other means) and each individual coordinate conversion is also
      replaced by its own inverse. This process inverts the overall
      effect of the TimeMap. In this case, the first conversion to be
      applied would be the inverse of the one most recently added.
   }
   \sstsynopsis{
      void astTimeAdd( AstTimeMap $*$this, const char $*$cvt, const double args[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the TimeMap.
      }
      \sstsubsection{
         cvt
      }{
         Pointer to a null-terminated string which identifies the
         time coordinate conversion to be added to the
         TimeMap. See the \texttt{"} Available Conversions\texttt{"}  section for details of
         those available.
      }
      \sstsubsection{
         args
      }{
         An array containing argument values for the time
         coordinate conversion. The number of arguments required, and
         hence the number of array elements used, depends on the
         conversion specified (see the \texttt{"} Available Conversions\texttt{"}
         section). This array is ignored
         and a NULL pointer may be supplied
         if no arguments are needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When assembling a multi-stage conversion, it can sometimes be
         difficult to determine the most economical conversion path. A solution
         to this is to include all the steps which are (logically) necessary,
         but then to use
         \htmlref{astSimplify}{astSimplify} to simplify the resulting
         TimeMap. The simplification process will eliminate any steps
         which turn out not to be needed.

         \sstitem
         This function does not check to ensure that the sequence of
         coordinate conversions added to a TimeMap is physically
         meaningful.
      }
   }
   \sstdiytopic{
      Available Conversions
   }{
      The following strings (which are case-insensitive) may be supplied
      via the \texttt{"} cvt\texttt{"}  parameter to indicate which time coordinate
      conversion is to be added to the TimeMap. Where arguments are needed by
      the conversion, they are listed in parentheses. Values for
      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
      order indicated. Units and argument names are described at the end of
      the list of conversions, and \texttt{"} MJD\texttt{"}  means Modified Julian Date.

      \sstitemlist{

         \sstitem
         \texttt{"} MJDTOMJD\texttt{"}   (MJDOFF1,MJDOFF2): Convert MJD from one offset to another.

         \sstitem
         \texttt{"} MJDTOJD\texttt{"}   (MJDOFF,JDOFF): Convert MJD to Julian Date.

         \sstitem
         \texttt{"} JDTOMJD\texttt{"}   (JDOFF,MJDOFF): Convert Julian Date to MJD.

         \sstitem
         \texttt{"} MJDTOBEP\texttt{"}  (MJDOFF,BEPOFF): Convert MJD to Besselian epoch.

         \sstitem
         \texttt{"} BEPTOMJD\texttt{"}  (BEPOFF,MJDOFF): Convert Besselian epoch to MJD.

         \sstitem
         \texttt{"} MJDTOJEP\texttt{"}  (MJDOFF,JEPOFF): Convert MJD to Julian epoch.

         \sstitem
         \texttt{"} JEPTOMJD\texttt{"}  (JEPOFF,MJDOFF): Convert Julian epoch to MJD.

         \sstitem
         \texttt{"} TAITOUTC\texttt{"}  (MJDOFF): Convert a TAI MJD to a UTC MJD.

         \sstitem
         \texttt{"} UTCTOTAI\texttt{"}  (MJDOFF): Convert a UTC MJD to a TAI MJD.

         \sstitem
         \texttt{"} TAITOTT\texttt{"}   (MJDOFF): Convert a TAI MJD to a TT MJD.

         \sstitem
         \texttt{"} TTTOTAI\texttt{"}   (MJDOFF): Convert a TT MJD to a TAI MJD.

         \sstitem
         \texttt{"} TTTOTDB\texttt{"}   (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD.

         \sstitem
         \texttt{"} TDBTOTT\texttt{"}   (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD.

         \sstitem
         \texttt{"} TTTOTCG\texttt{"}   (MJDOFF): Convert a TT MJD to a TCG MJD.

         \sstitem
         \texttt{"} TCGTOTT\texttt{"}   (MJDOFF): Convert a TCG MJD to a TT MJD.

         \sstitem
         \texttt{"} TDBTOTCB\texttt{"}  (MJDOFF): Convert a TDB MJD to a TCB MJD.

         \sstitem
         \texttt{"} TCBTOTDB\texttt{"}  (MJDOFF): Convert a TCB MJD to a TDB MJD.

         \sstitem
         \texttt{"} UTTOGMST\texttt{"}  (MJDOFF): Convert a UT MJD to a GMST MJD.

         \sstitem
         \texttt{"} GMSTTOUT\texttt{"}  (MJDOFF): Convert a GMST MJD to a UT MJD.

         \sstitem
         \texttt{"} GMSTTOLMST\texttt{"}  (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD.

         \sstitem
         \texttt{"} LMSTTOGMST\texttt{"}  (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD.

         \sstitem
         \texttt{"} LASTTOLMST\texttt{"}  (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD.

         \sstitem
         \texttt{"} LMSTTOLAST\texttt{"}  (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD.

         \sstitem
         \texttt{"} UTTOUTC\texttt{"}  (DUT1): Convert a UT1 MJD to a UTC MJD.

         \sstitem
         \texttt{"} UTCTOUT\texttt{"}  (DUT1): Convert a UTC MJD to a UT1 MJD.

         \sstitem
         \texttt{"} LTTOUTC\texttt{"}  (LTOFF): Convert a Local Time MJD to a UTC MJD.

         \sstitem
         \texttt{"} UTCTOLT\texttt{"}  (LTOFF): Convert a UTC MJD to a Local Time MJD.

      }
      The units for the values processed by the above conversions are as
      follows:

      \sstitemlist{

         \sstitem
         Julian epochs and offsets: Julian years

         \sstitem
         Besselian epochs and offsets: Tropical years

         \sstitem
         Modified Julian Dates and offsets: days

         \sstitem
         Julian Dates and offsets: days

      }
      The arguments used in the above conversions are the zero-points
      used by the
      astTransform function.
      The axis values supplied and returned by
      astTransform
      are offsets away from these zero-points:

      \sstitemlist{

         \sstitem
         MJDOFF: The zero-point being used with MJD values.

         \sstitem
         JDOFF: The zero-point being used with Julian Date values.

         \sstitem
         BEPOFF: The zero-point being used with Besselian epoch values.

         \sstitem
         JEPOFF: The zero-point being used with Julian epoch values.

         \sstitem
         OBSLON: Observer longitude in radians ($+$ve westwards).

         \sstitem
         OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards).

         \sstitem
         OBSALT: Observer geodetic altitude (IAU 1975) in metres.

         \sstitem
         DUT1: The UT1-UTC value to use.

         \sstitem
         LTOFF: The offset between Local Time and UTC (in hours, positive
         for time zones east of Greenwich).
      }
   }
}
\sstroutine{
   astTimeFrame
}{
   Create a TimeFrame
}{
   \sstdescription{
      This function creates a new \htmlref{TimeFrame}{TimeFrame} and optionally initialises
      its attributes.

      A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various coordinate systems used to describe positions in
      time.

      A TimeFrame represents a moment in time as either an Modified Julian
      Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch,
      as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be
      specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame
      representing time offsets from the specified zero point.

      Even though JD and MJD are defined as being in units of days, the
      TimeFrame class allows other units to be used (via the Unit attribute)
      on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1
      hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs
      can be described in units other than the usual years. Besselian epoch
      are always represented in units of (tropical) years.

      The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that
      is, the physical proces used to define the rate of flow of time).
      MJD, JD and Julian epoch can be used to represent a time in any
      supported time scale. However, Besselian epoch may only be used with the
      \texttt{"} TT\texttt{"}  (Terrestrial Time) time scale. The list of supported time scales
      includes universal time and siderial time. Strictly, these represent
      angles rather than time scales, but are included in the list since
      they are in common use and are often thought of as time scales.

      When a time value is formatted it can be formated either as a simple
      floating point value, or as a Gregorian date (see the Format
      attribute).
   }
   \sstsynopsis{
      AstTimeFrame $*$astTimeFrame( const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new TimeFrame. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTimeFrame()
      }{
         A pointer to the new TimeFrame.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When conversion between two TimeFrames is requested (as when
         supplying TimeFrames to \htmlref{astConvert}{astConvert}),
         account will be taken of the nature of the time coordinate systems
         they represent, together with any qualifying time scale, offset,
         unit, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignTimeScale}{AlignTimeScale} attributes will also be
         taken into account.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astTimeMap
}{
   Create a TimeMap
}{
   \sstdescription{
      This function creates a new \htmlref{TimeMap}{TimeMap} and optionally initialises
      its attributes.

      A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be
      used to represent a sequence of conversions between standard time
      coordinate systems.

      When a TimeMap is first created, it simply performs a unit
      (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd}
      function, a series of coordinate conversion steps may then be
      added. This allows multi-step conversions between a variety of
      time coordinate systems to be assembled out of a set of building
      blocks.

      For details of the individual coordinate conversions available,
      see the description of the astTimeAdd function.
   }
   \sstsynopsis{
      AstTimeMap $*$astTimeMap( int flags, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         flags
      }{
         This parameter is reserved for future use and should currently
         always be set to zero.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new TimeMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
         If no initialisation is required, a zero-length string may be
         supplied.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTimeMap()
      }{
         A pointer to the new TimeMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The nature and units of the coordinate values supplied for the
         first input (i.e. the time input) of a TimeMap must be appropriate
         to the first conversion step applied by the TimeMap. For instance, if
         the first conversion step is \texttt{"} MJDTOBEP\texttt{"}  (Modified Julian Date to
         Besselian epoch) then the coordinate values for the first input should
         be date in units of days. Similarly, the nature and units of the
         coordinate values returned by a TimeMap will be determined by the
         last conversion step applied by the TimeMap.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astToString
}{
   Create an in-memory serialisation of an Object
}{
   \sstdescription{
      This function returns a string holding a minimal textual
      serialisation of the supplied AST \htmlref{Object}{Object}. The Object can re
      re-created from the serialisation using \htmlref{astFromString}{astFromString}.
   }
   \sstsynopsis{
      char $*$astToString( AstObject $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be serialised.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astToString()
      }{
         Pointer to dynamically allocated memory holding the
         serialisation, or NULL if an error occurs. The pointer
         should be freed when no longer needed using \htmlref{astFree}{astFree}.
      }
   }
}
\sstroutine{
   astTran1
}{
   Transform 1-dimensional coordinates
}{
   \sstdescription{
      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
      a set of points in one dimension.
   }
   \sstsynopsis{
      void astTran1( AstMapping $*$this, int npoint, const double xin[],
                     int forward, double xout[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         npoint
      }{
         The number of points to be transformed.
      }
      \sstsubsection{
         xin
      }{
         An array of \texttt{"} npoint\texttt{"}  coordinate values for the input
         (untransformed) points.
      }
      \sstsubsection{
         forward
      }{
         A non-zero value indicates that the Mapping\texttt{'} s forward
         coordinate transformation is to be applied, while a zero
         value indicates that the inverse transformation should be
         used.
      }
      \sstsubsection{
         xout
      }{
         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
         coordinates of the output (transformed) points will be written.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin}
         and \htmlref{Nout}{Nout} attributes.
      }
   }
}
\sstroutine{
   astTran2
}{
   Transform 2-dimensional coordinates
}{
   \sstdescription{
      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
      a set of points in two dimensions.
   }
   \sstsynopsis{
      void astTran2( AstMapping $*$this,
                     int npoint, const double xin[], const double yin[],
                     int forward, double xout[], double yout[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         npoint
      }{
         The number of points to be transformed.
      }
      \sstsubsection{
         xin
      }{
         An array of \texttt{"} npoint\texttt{"}  X-coordinate values for the input
         (untransformed) points.
      }
      \sstsubsection{
         yin
      }{
         An array of \texttt{"} npoint\texttt{"}  Y-coordinate values for the input
         (untransformed) points.
      }
      \sstsubsection{
         forward
      }{
         A non-zero value indicates that the Mapping\texttt{'} s forward
         coordinate transformation is to be applied, while a zero
         value indicates that the inverse transformation should be
         used.
      }
      \sstsubsection{
         xout
      }{
         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
         X-coordinates of the output (transformed) points will be written.
      }
      \sstsubsection{
         yout
      }{
         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
         Y-coordinates of the output (transformed) points will be written.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin}
         and \htmlref{Nout}{Nout} attributes.
      }
   }
}
\sstroutine{
   astTranGrid
}{
   Transform a grid of positions
}{
   \sstdescription{
      This function uses the supplied \htmlref{Mapping}{Mapping} to transforms a regular square
      grid of points covering a specified box. It attempts to do this
      quickly by first approximating the Mapping with a linear transformation
      applied over the whole region of the input grid which is being used.
      If this proves to be insufficiently accurate, the input region is
      sub-divided into two along its largest dimension and the process is
      repeated within each of the resulting sub-regions. This process of
      sub-division continues until a sufficiently good linear approximation
      is found, or the region to which it is being applied becomes too small
      (in which case the original Mapping is used directly).
   }
   \sstsynopsis{
      void astTranGrid( AstMapping $*$this, int ncoord\_in,
                        const int lbnd[], const int ubnd[],
                        double tol, int maxpix, int forward,
                        int ncoord\_out, int outdim, double $*$out );
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         ncoord\_in
      }{
         The number of coordinates being supplied for each box corner
         (i.e. the number of dimensions of the space in which the
         input points reside).
      }
      \sstsubsection{
         lbnd
      }{
         Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd
      }{
         Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
         and size of the input grid, its extent along a particular
         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
         index \texttt{"} j\texttt{"}  to be zero-based). They also define
         the input grid\texttt{'} s coordinate system, each pixel having unit
         extent along each dimension with integral coordinate values
         at its centre.
      }
      \sstsubsection{
         tol
      }{
         The maximum tolerable geometrical distortion which may be
         introduced as a result of approximating non-linear Mappings
         by a set of piece-wise linear transformations. This should be
         expressed as a displacement within the output coordinate system
         of the Mapping.

         If piece-wise linear approximation is not required, a value
         of zero may be given. This will ensure that the Mapping is
         used without any approximation, but may increase execution
         time.

         If the value is too high, discontinuities between the linear
         approximations used in adjacent panel will be higher. If this
         is a problem, reduce the tolerance value used.
      }
      \sstsubsection{
         maxpix
      }{
         A value which specifies an initial scale size (in input grid points)
         for the adaptive algorithm which approximates non-linear Mappings
         with piece-wise linear transformations. Normally, this should
         be a large value (larger than any dimension of the region of
         the input grid being used). In this case, a first attempt to
         approximate the Mapping by a linear transformation will be
         made over the entire input region.

         If a smaller value is used, the input region will first be
         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
         grid points in any dimension. Only at this point will attempts
         at approximation commence.

         This value may occasionally be useful in preventing false
         convergence of the adaptive algorithm in cases where the
         Mapping appears approximately linear on large scales, but has
         irregularities (e.g. holes) on smaller scales. A value of,
         say, 50 to 100 grid points can also be employed as a safeguard
         in general-purpose software, since the effect on performance is
         minimal.

         If too small a value is given, it will have the effect of
         inhibiting linear approximation altogether (equivalent to
         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
         performance, accurate results will still be obtained.
      }
      \sstsubsection{
         forward
      }{
         A non-zero value indicates that the Mapping\texttt{'} s forward
         coordinate transformation is to be applied, while a zero
         value indicates that the inverse transformation should be
         used.
      }
      \sstsubsection{
         ncoord\_out
      }{
         The number of coordinates being generated by the Mapping for
         each output point (i.e. the number of dimensions of the
         space in which the output points reside). This need not be
         the same as \texttt{"} ncoord\_in\texttt{"} .
      }
      \sstsubsection{
         outdim
      }{
         The number of elements along the second dimension of the \texttt{"} out\texttt{"}
         array (which will contain the output coordinates). The value
         given should not be less than the number of points in the grid.
      }
      \sstsubsection{
         out
      }{
         The address of the first element in a 2-dimensional array of
         shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into
         which the coordinates of the output (transformed) points will
         be written. These will be stored such that the value of
         coordinate number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}
         will be found in element \texttt{"} out[coord][point]\texttt{"} .
         The points are ordered such that the first axis of the input
         grid changes most rapidly. For example, if the input grid is
         2-dimensional and extends from (2,-1) to (3,1), the output
         points will be stored in the order (2,-1), (3, -1), (2,0), (3,0),
         (2,1), (3,1).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the forward coordinate transformation is being applied, the
         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout} attribute. If
         the inverse transformation is being applied, these values should
         be reversed.
      }
   }
}
\sstroutine{
   astTranMap
}{
   Create a TranMap
}{
   \sstdescription{
      This function creates a new \htmlref{TranMap}{TranMap} and optionally initialises
      its attributes.

      A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of
      a supplied Mapping with the inverse transformation of another
      supplied Mapping, ignoring the un-used transformation in each
      Mapping (indeed the un-used transformation need not exist).

      When the forward transformation of the TranMap is referred to, the
      transformation actually used is the forward transformation of the
      first Mapping supplied when the TranMap was constructed. Likewise,
      when the inverse transformation of the TranMap is referred to, the
      transformation actually used is the inverse transformation of the
      second Mapping supplied when the TranMap was constructed.
   }
   \sstsynopsis{
      AstTranMap $*$astTranMap( AstMapping $*$map1, AstMapping $*$map2,
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         map1
      }{
         Pointer to the first component Mapping, which defines the
         forward transformation.
      }
      \sstsubsection{
         map2
      }{
         Pointer to the second component Mapping, which defines the
         inverse transformation.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new TranMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTranMap()
      }{
         A pointer to the new TranMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The number of output coordinates generated by the two Mappings
         (their \htmlref{Nout}{Nout} attribute) must be equal, as must the number of input
         coordinates accepted by each Mapping (their \htmlref{Nin}{Nin} attribute).

         \sstitem
         The forward transformation of the first Mapping must exist.

         \sstitem
         The inverse transformation of the second Mapping must exist.

         \sstitem
         Note that the component Mappings supplied are not copied by
         astTranMap (the new TranMap simply retains a reference to
         them). They may continue to be used for other purposes, but
         should not be deleted. If a TranMap containing a copy of its
         component Mappings is required, then a copy of the TranMap should
         be made using \htmlref{astCopy}{astCopy}.

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astTranN
}{
   Transform N-dimensional coordinates
}{
   \sstdescription{
      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
      a set of points in an arbitrary number of dimensions. It is the
      appropriate routine to use if the coordinates are not purely 1-
      or 2-dimensional and are stored in a single array (which they
      need not fill completely).

      If the coordinates are not stored in a single array, then the
      \htmlref{astTranP}{astTranP} function might be more suitable.
   }
   \sstsynopsis{
      void astTranN( AstMapping $*$this, int npoint,
                     int ncoord\_in, int indim, const double $*$in,
                     int forward,
                     int ncoord\_out, int outdim, double $*$out )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         npoint
      }{
         The number of points to be transformed.
      }
      \sstsubsection{
         ncoord\_in
      }{
         The number of coordinates being supplied for each input point
         (i.e. the number of dimensions of the space in which the
         input points reside).
      }
      \sstsubsection{
         indim
      }{
         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
         array (which contains the input coordinates). This value is
         required so that the coordinate values can be correctly
         located if they do not entirely fill this array. The value
         given should not be less than \texttt{"} npoint\texttt{"} .
      }
      \sstsubsection{
         in
      }{
         The address of the first element in a 2-dimensional array of
         shape \texttt{"} [ncoord\_in][indim]\texttt{"} ,
         containing the coordinates of the input (untransformed)
         points. These should be stored such that the value of
         coordinate number \texttt{"} coord\texttt{"}  for input point number \texttt{"} point\texttt{"}  is
         found in element \texttt{"} in[coord][point]\texttt{"} .
      }
      \sstsubsection{
         forward
      }{
         A non-zero value indicates that the Mapping\texttt{'} s forward
         coordinate transformation is to be applied, while a zero
         value indicates that the inverse transformation should be
         used.
      }
      \sstsubsection{
         ncoord\_out
      }{
         The number of coordinates being generated by the Mapping for
         each output point (i.e. the number of dimensions of the
         space in which the output points reside). This need not be
         the same as \texttt{"} ncoord\_in\texttt{"} .
      }
      \sstsubsection{
         outdim
      }{
         The number of elements along the second dimension of the \texttt{"} out\texttt{"}
         array (which will contain the output coordinates). This value
         is required so that the coordinate values can be correctly
         located if they will not entirely fill this array. The value
         given should not be less than \texttt{"} npoint\texttt{"} .
      }
      \sstsubsection{
         out
      }{
         The address of the first element in a 2-dimensional array of
         shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into
         which the coordinates of the output (transformed) points will
         be written. These will be stored such that the value of
         coordinate number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}
         will be found in element \texttt{"} out[coord][point]\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the forward coordinate transformation is being applied, the
         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout} attribute. If
         the inverse transformation is being applied, these values should
         be reversed.
      }
   }
}
\sstroutine{
   astTranP
}{
   Transform N-dimensional coordinates held in separate arrays
}{
   \sstdescription{
      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
      a set of points in an arbitrary number of dimensions. It is the
      appropriate routine to use if the coordinates are not purely 1-
      or 2-dimensional and are stored in separate arrays, since each
      coordinate array is located by supplying a separate pointer to
      it.

      If the coordinates are stored in a single (2-dimensional) array,
      then the \htmlref{astTranN}{astTranN} function might be more suitable.
   }
   \sstsynopsis{
      void astTranP( AstMapping $*$this, int npoint,
                     int ncoord\_in, const double $*$ptr\_in[],
                     int forward, int ncoord\_out, double $*$ptr\_out[] )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Mapping to be applied.
      }
      \sstsubsection{
         npoint
      }{
         The number of points to be transformed.
      }
      \sstsubsection{
         ncoord\_in
      }{
         The number of coordinates being supplied for each input point
         (i.e. the number of dimensions of the space in which the
         input points reside).
      }
      \sstsubsection{
         ptr\_in
      }{
         An array of pointers to double, with \texttt{"} ncoord\_in\texttt{"}
         elements. Element \texttt{"} ptr\_in[coord]\texttt{"}  should point at the first
         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) which
         contain the values of coordinate number \texttt{"} coord\texttt{"}  for each
         input (untransformed) point. The value of coordinate number
         \texttt{"} coord\texttt{"}  for input point number \texttt{"} point\texttt{"}  is therefore given by
         \texttt{"} ptr\_in[coord][point]\texttt{"}  (assuming both indices are
         zero-based).
      }
      \sstsubsection{
         forward
      }{
         A non-zero value indicates that the Mapping\texttt{'} s forward
         coordinate transformation is to be applied, while a zero
         value indicates that the inverse transformation should be
         used.
      }
      \sstsubsection{
         ncoord\_out
      }{
         The number of coordinates being generated by the Mapping for
         each output point (i.e. the number of dimensions of the space
         in which the output points reside). This need not be the same
         as \texttt{"} ncoord\_in\texttt{"} .
      }
      \sstsubsection{
         ptr\_out
      }{
         An array of pointers to double, with \texttt{"} ncoord\_out\texttt{"}
         elements. Element \texttt{"} ptr\_out[coord]\texttt{"}  should point at the first
         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) into
         which the values of coordinate number \texttt{"} coord\texttt{"}  for each output
         (transformed) point will be written.  The value of coordinate
         number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}  will therefore
         be found in \texttt{"} ptr\_out[coord][point]\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the forward coordinate transformation is being applied, the
         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout}
         attribute. If the inverse transformation is being applied, these
         values should be reversed.

         \sstitem
         This routine is not available in the Fortran 77 interface to
         the AST library.
      }
   }
}
\sstroutine{
   astTune
}{
   Set or get an integer-valued AST global tuning parameter
}{
   \sstdescription{
      This function returns the current value of an integer-valued AST
      global tuning parameter, optionally storing a new value for the
      parameter. For character-valued tuning parameters, see
      \htmlref{astTuneC}{astTuneC}.
   }
   \sstsynopsis{
      int astTune( const char $*$name, int value )
   }
   \sstparameters{
      \sstsubsection{
         name
      }{
         The name of the tuning parameter (case-insensitive).
      }
      \sstsubsection{
         value
      }{
         The new value for the tuning parameter. If this is AST\_\_TUNULL,
         the existing current value will be retained.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astTune()
      }{
         The original value of the tuning parameter. A default value will
         be returned if no value has been set for the parameter.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to execute even if the AST error
         status is set
         on entry, although no further error report will be
         made if it subsequently fails under these circumstances.

         \sstitem
         All threads in a process share the same AST tuning parameters
         values.
      }
   }
   \sstdiylist{
      Tuning Parameters
   }{
      \sstsubsection{
         ObjectCaching
      }{
         A boolean flag which indicates what should happen
         to the memory occupied by an AST \htmlref{Object}{Object} when the Object is deleted
         (i.e. when its reference count falls to zero or it is deleted using
         \htmlref{astDelete}{astDelete}).
         If this is zero, the memory is simply freed using the systems \texttt{"} free\texttt{"}
         function. If it is non-zero, the memory is not freed. Instead a
         pointer to it is stored in a pool of such pointers, all of which
         refer to allocated but currently unused blocks of memory. This allows
         AST to speed up subsequent Object creation by re-using previously
         allocated memory blocks rather than allocating new memory using the
         systems malloc function. The default value for this parameter is
         zero. Setting it to a non-zero value will result in Object memory
         being cached in future. Setting it back to zero causes any memory
         blocks currently in the pool to be freed. Note, this tuning parameter
         only controls the caching of memory used to store AST Objects. To
         cache other memory blocks allocated by AST, use MemoryCaching.
      }
      \sstsubsection{
         MemoryCaching
      }{
         A boolean flag similar to ObjectCaching except
         that it controls caching of all memory blocks of less than 300 bytes
         allocated by AST (whether for internal or external use), not just
         memory used to store AST Objects.
      }
   }
}
\sstroutine{
   astTuneC
}{
   Set or get a character-valued AST global tuning parameter
}{
   \sstdescription{
      This function returns the current value of a character-valued
      AST global tuning parameter, optionally storing a new value
      for the parameter. For integer-valued tuning parameters, see
      \htmlref{astTune}{astTune}.
   }
   \sstsynopsis{
      void astTuneC( const char $*$name, const char $*$value, char $*$buff,
                     int bufflen )
   }
   \sstparameters{
      \sstsubsection{
         name
      }{
         The name of the tuning parameter (case-insensitive).
      }
      \sstsubsection{
         value
      }{
         The new value for the tuning parameter. If this is
         NULL,
         the existing current value will be retained.
      }
      \sstsubsection{
         buff
      }{
         A character string in which to return the original value of
         the tuning parameter. An error will be reported if the buffer
         is too small to hold the value.
         NULL may be supplied if the old value is not required.
      }
      \sstsubsection{
         bufflen
      }{
         The size of the supplied \texttt{"} buff\texttt{"}  array. Ignored if \texttt{"} buff\texttt{"}  is NULL.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to execute even if the AST error
         status is set
         on entry, although no further error report will be
         made if it subsequently fails under these circumstances.

         \sstitem
         All threads in a process share the same AST tuning parameters
         values.
      }
   }
   \sstdiylist{
      Tuning Parameters
   }{
      \sstsubsection{
         HRDel
      }{
         A string to be drawn following the hours field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use (see the Format
         attribute). This string may include escape sequences to produce
         super-scripts, etc. (see the Escapes attribute for details
         of the escape sequences allowed). The default value is
         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$h\%$+$\texttt{"}  which produces a super-script \texttt{"} h\texttt{"} .
      }
      \sstsubsection{
         MNDel
      }{
         A string to be drawn following the minutes field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$m\%$+$\texttt{"}  which produces a super-script \texttt{"} m\texttt{"} .
      }
      \sstsubsection{
         SCDel
      }{
         A string to be drawn following the seconds field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$s\%$+$\texttt{"}  which produces a super-script \texttt{"} s\texttt{"} .
      }
      \sstsubsection{
         DGDel
      }{
         A string to be drawn following the degrees field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
         \texttt{"} \%-\%$\wedge$53$+$\%s60$+$o\%$+$\texttt{"}  which produces a super-script \texttt{"} o\texttt{"} .
      }
      \sstsubsection{
         AMDel
      }{
         A string to be drawn following the arc-minutes field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
         \texttt{"} \%-\%$\wedge$20$+$\%s85$+$\texttt{'} \%$+$\texttt{"}  which produces a super-script \texttt{"} \texttt{'} \texttt{"}  (single quote).
      }
      \sstsubsection{
         ASDel
      }{
         A string to be drawn following the arc-seconds field in a formatted
         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
         \texttt{"} \%-\%$\wedge$20$+$\%s85$+$$\backslash$\texttt{"} \%$+$\texttt{"}  which produces a super-script \texttt{"} \texttt{"} \texttt{"}  (double quote).
      }
      \sstsubsection{
         EXDel
      }{
         A string to be drawn to introduce the exponent in a value when \texttt{"} g\texttt{"}
         format is in use. The default value is \texttt{"} 10\%-\%$\wedge$50$+$\%s70$+$\texttt{"}  which
         produces \texttt{"} 10\texttt{"}  followed by the exponent as a super-script.
      }
   }
}
\sstroutine{
   astUinterp
}{
   Perform sub-pixel interpolation on a grid of data
}{
   \sstdescription{
      This is a fictitious function which does not actually
      exist. Instead, this description constitutes a template so that
      you may implement a function with this interface for yourself
      (and give it any name you wish). A pointer to such a function
      may be passed via the \texttt{"} finterp\texttt{"}  parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$}
      functions (q.v.) in order to perform sub-pixel interpolation
      during resampling of gridded data (you must also set the
      \texttt{"} interp\texttt{"}  parameter of astResample$<$X$>$ to the value
      AST\_\_UINTERP). This allows you to use your own interpolation
      algorithm in addition to those which are pre-defined.

      The function interpolates an input grid of data (and,
      optionally, processes associated statistical variance estimates)
      at a specified set of points.
   }
   \sstsynopsis{
      void astUinterp( int ndim\_in, const int lbnd\_in[], const int ubnd\_in[],
                       const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
                       int npoint, const int offset[],
                       const double $*$const coords[], const double params[],
                       int flags, $<$Xtype$>$ badval,
                       $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], int $*$nbad )
   }
   \sstparameters{
      \sstsubsection{
         ndim\_in
      }{
         The number of dimensions in the input grid. This will be at
         least one.
      }
      \sstsubsection{
         lbnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the first pixel
         in the input grid along each dimension.
      }
      \sstsubsection{
         ubnd\_in
      }{
         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
         containing the coordinates of the centre of the last pixel in
         the input grid along each dimension.

         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape,
         size and coordinate system of the input grid in the same
         way as they do in astResample$<$X$>$.
      }
      \sstsubsection{
         in
      }{
         Pointer to an array, with one element for each pixel in the
         input grid, containing the input data. This will be the same
         array as was passed to astResample$<$X$>$ via the \texttt{"} in\texttt{"}  parameter.
         The numerical type of this array should match that of the
         data being processed.
      }
      \sstsubsection{
         in\_var
      }{
         Pointer to an optional second array with the same size and
         type as the \texttt{"} in\texttt{"}  array. If given, this will contain the set
         of variance values associated with the input data and will be
         the same array as was passed to astResample$<$X$>$ via the
         \texttt{"} in\_var\texttt{"}  parameter.

         If no variance values are being processed, this will be a
         NULL pointer.
      }
      \sstsubsection{
         npoint
      }{
         The number of points at which the input grid is to be
         interpolated. This will be at least one.
      }
      \sstsubsection{
         offset
      }{
         Pointer to an array of integers with \texttt{"} npoint\texttt{"}  elements. For
         each interpolation point, this will contain the zero-based
         index in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) at which the
         interpolated value (and its variance, if required) should be
         stored. For example, the interpolated value for point number
         \texttt{"} point\texttt{"}  should be stored in \texttt{"} out[offset[point]]\texttt{"}  (assuming
         the index \texttt{"} point\texttt{"}  is zero-based).
      }
      \sstsubsection{
         coords
      }{
         An array of pointers to double, with \texttt{"} ndim\_in\texttt{"}
         elements. Element \texttt{"} coords[coord]\texttt{"}  will point at the first
         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) which
         contains the values of coordinate number \texttt{"} coord\texttt{"}  for each
         interpolation point. The value of coordinate number \texttt{"} coord\texttt{"}
         for interpolation point number \texttt{"} point\texttt{"}  is therefore given by
         \texttt{"} coords[coord][point]\texttt{"}  (assuming both indices are
         zero-based).

         If any interpolation point has any of its coordinates equal
         to the value AST\_\_BAD (as defined in the \texttt{"} ast.h\texttt{"}  header
         file), then the corresponding output data (and variance)
         should either be set to the value given by \texttt{"} badval\texttt{"} ,
         or left unchanged, depending on whether the AST\_\_NOBAD flag is
         specified by \texttt{"} flags\texttt{"} .
      }
      \sstsubsection{
         params
      }{
         This will be a pointer to the same array as was given via the
         \texttt{"} params\texttt{"}  parameter of astResample$<$X$>$. You may use this to
         pass any additional parameter values required by your
         interpolation algorithm.
      }
      \sstsubsection{
         flags
      }{
         This will be the same value as was given via the \texttt{"} flags\texttt{"}
         parameter of astResample$<$X$>$. You may test this value to
         provide additional control over the operation of your
         resampling algorithm. Note that the special flag values
         AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your
         own purposes and will not clash with other pre-defined flag
         values (see astResample$<$X$>$).
      }
      \sstsubsection{
         badval
      }{
         This will be the same value as was given via the \texttt{"} badval\texttt{"}
         parameter of astResample$<$X$>$, and will have the same numerical
         type as the data being processed (i.e. as elements of the
         \texttt{"} in\texttt{"}  array).  It should be used to test for bad pixels in the
         input grid (but only if the AST\_\_USEBAD flag is set via the
         \texttt{"} flags\texttt{"}  parameter) and (unless the AST\_\_NOBAD flag is set in
         \texttt{"} flags\texttt{"} ) for identifying bad output values in
         the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s).
      }
      \sstsubsection{
         out
      }{
         Pointer to an array with the same numerical type as the \texttt{"} in\texttt{"}
         array, into which the interpolated data values should be
         returned.  Note that details of the storage order and number
         of dimensions of this array are not required, since the
         \texttt{"} offset\texttt{"}  array contains all necessary information about where
         each returned value should be stored.

         In general, not all elements of this array (or the \texttt{"} out\_var\texttt{"}
         array below) may be used in any particular invocation of the
         function. Those which are not used should be returned
         unchanged.
      }
      \sstsubsection{
         out\_var
      }{
         Pointer to an optional array with the same type and size as
         the \texttt{"} out\texttt{"}  array, into which variance estimates for the
         resampled values should be returned.  This array will only be
         given if the \texttt{"} in\_var\texttt{"}  array has also been given.

         If given, it is addressed in exactly the same way (via the
         \texttt{"} offset\texttt{"}  array) as the \texttt{"} out\texttt{"}  array. The values returned
         should be estimates of the statistical variance of the
         corresponding values in the \texttt{"} out\texttt{"}  array, on the assumption
         that all errors in input data values are statistically
         independent and that their variance estimates may simply be
         summed (with appropriate weighting factors).

         If no output variance estimates are required, a NULL pointer
         will be given.
      }
      \sstsubsection{
         nbad
      }{
         Pointer to an int in which to return the number of interpolation
         points at
         which no valid interpolated value could be obtained.  The maximum
         value that should be returned is \texttt{"} npoint\texttt{"} , and the minimum is
         zero (indicating that all output values were successfully
         obtained).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The data type $<$Xtype$>$ indicates the numerical type of the data
         being processed, as for astResample$<$X$>$.

         \sstitem
         This function will typically be invoked more than once for each
         invocation of astResample$<$X$>$.

         \sstitem
         If an error occurs within this function, it should use
         \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value.
         This will cause an immediate return from astResample$<$X$>$. The error
         value AST\_\_UINER is available for this purpose, but other values may
         also be used (e.g. if you wish to distinguish different types of
         error).
      }
   }
}
\sstroutine{
   astUkern1
}{
   1-dimensional sub-pixel interpolation kernel
}{
   \sstdescription{
      This is a fictitious function which does not actually
      exist. Instead, this description constitutes a template so that
      you may implement a function with this interface for yourself
      (and give it any name you wish). A pointer to such a function
      may be passed via the \texttt{"} finterp\texttt{"}  parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$}
      functions (q.v.) in order to supply a 1-dimensional
      interpolation kernel to the algorithm which performs sub-pixel
      interpolation during resampling of gridded data (you must also
      set the \texttt{"} interp\texttt{"}  parameter of astResample$<$X$>$ to the value
      AST\_\_UKERN1). This allows you to use your own interpolation
      kernel in addition to those which are pre-defined.

      The function calculates the value of a 1-dimensional sub-pixel
      interpolation kernel. This determines how the weight given to
      neighbouring pixels in calculating an interpolated value depends
      on the pixel\texttt{'} s offset from the interpolation point. In more than
      one dimension, the weight assigned to a pixel is formed by
      evaluating this 1-dimensional kernel using the offset along each
      dimension in turn. The product of the returned values is then
      used as the pixel weight.
   }
   \sstsynopsis{
      void astUkern1( double offset, const double params[], int flags,
                      double $*$value )
   }
   \sstparameters{
      \sstsubsection{
         offset
      }{
         This will be the offset of the pixel from the interpolation
         point, measured in pixels. This value may be positive or
         negative, but for most practical interpolation schemes its
         sign should be ignored.
      }
      \sstsubsection{
         params
      }{
         This will be a pointer to the same array as was given via the
         \texttt{"} params\texttt{"}  parameter of astResample$<$X$>$. You may use this to
         pass any additional parameter values required by your kernel,
         but note that \texttt{"} params[0]\texttt{"}  will already have been used to specify
         the number of neighbouring pixels which contribute to the
         interpolated value.
      }
      \sstsubsection{
         flags
      }{
         This will be the same value as was given via the \texttt{"} flags\texttt{"}
         parameter of astResample$<$X$>$. You may test this value to
         provide additional control over the operation of your
         function. Note that the special flag values AST\_\_URESAMP1, 2,
         3 \& 4 are reserved for you to use for your own purposes and
         will not clash with other pre-defined flag
         values (see astResample$<$X$>$).
      }
      \sstsubsection{
         value
      }{
         Pointer to a double to receive the calculated kernel value,
         which may be positive or negative.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Not all functions make good interpolation kernels. In general,
         acceptable kernels tend to be symmetrical about zero, to have a
         positive peak (usually unity) at zero, and to evaluate to zero
         whenever the pixel offset has any other integral value (this
         ensures that the interpolated values pass through the original
         data). An interpolation kernel may or may not have regions with
         negative values. You should consult a good book on image
         processing for more details.

         \sstitem
         If an error occurs within this function, it should use
         \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value.
         This will cause an immediate return from astResample$<$X$>$. The error
         value AST\_\_UK1ER is available for this purpose, but other values may
         also be used (e.g. if you wish to distinguish different types of
         error).
      }
   }
}
\sstroutine{
   astUnformat
}{
   Read a formatted coordinate value for a Frame axis
}{
   \sstdescription{
      This function reads a formatted coordinate value (given as a
      character string) for a \htmlref{Frame}{Frame} axis and returns the equivalent
      numerical (double) value. It also returns the number of
      characters read from the string.

      The principle use of this function is in decoding user-supplied
      input which contains formatted coordinate values. Free-format
      input is supported as far as possible. If input is ambiguous, it
      is interpreted with reference to the Frame\texttt{'} s attributes (in
      particular, the Format string associated with the Frame\texttt{'} s
      axis). This function is, in essence, the inverse of \htmlref{astFormat}{astFormat}.
   }
   \sstsynopsis{
      int astUnformat( AstFrame $*$this, int axis, const char $*$string,
                       double $*$value )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Frame.
      }
      \sstsubsection{
         axis
      }{
         The number of the Frame axis for which a coordinate value is to
         be read (axis numbering starts at 1 for the first axis).
      }
      \sstsubsection{
         string
      }{
         Pointer to a null-terminated character string containing the
         formatted coordinate value.
         This string may contain additional information following the
         value to be read, in which case reading stops at the first
         character which cannot be interpreted as part of the value.
         Any white space before or after the value is discarded.
      }
      \sstsubsection{
         value
      }{
         Pointer to a double in which the coordinate value read will be
         returned.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         This function applies to all Frames. See the \texttt{"} Frame Input
         Format\texttt{"}  section below for details of the input formats
         accepted by a basic Frame.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the input format to be suitable
         for representing angles and times, with the resulting
         coordinate value returned in radians.  See the \texttt{"} SkyFrame
         Input Format\texttt{"}  section below for details of the formats
         accepted.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The input formats accepted by a FrameSet are determined by
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astUnformat()
      }{
         The number of characters read from the string in order to
         obtain the coordinate value. This will include any white
         space which occurs before or after the value.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A function value of zero (and no coordinate value) will be
         returned, without error, if the string supplied does not contain
         a suitably formatted value.

         \sstitem
         Beware that it is possible for a formatting error part-way
         through an input string to terminate input before it has been
         completely read, but to yield a coordinate value that appears
         valid. For example, if a user types \texttt{"} 1.5r6\texttt{"}  instead of \texttt{"} 1.5e6\texttt{"} ,
         the \texttt{"} r\texttt{"}  will terminate input, giving an incorrect coordinate
         value of 1.5. It is therefore most important to check the return
         value of this function to ensure that the correct number of
         characters have been read.

         \sstitem
         An error will result if a value is read which appears to have
         the correct format, but which cannot be converted into a valid
         coordinate value (for instance, because the value of one or more
         of its fields is invalid).

         \sstitem
         The string \texttt{"} $<$bad$>$\texttt{"}  is recognised as a special case and will
         yield the coordinate value AST\_\_BAD without error. The test for
         this string is case-insensitive and also permits embedded white
         space.

         \sstitem
         A function result of zero will be returned and no coordinate
         value will be returned via the \texttt{"} value\texttt{"}  pointer if this function
         is invoked with the AST error status set, or if it should fail
         for any reason.
      }
   }
   \sstdiytopic{
      Frame Input Format
   }{
      The input format accepted for a basic Frame axis is as follows:
      \sstitemlist{

         \sstitem
         An optional sign, followed by:

         \sstitem
         A sequence of one or more digits possibly containing a decimal point,
         followed by:

         \sstitem
         An optional exponent field.

         \sstitem
         The exponent field, if present, consists of \texttt{"} E\texttt{"}  or \texttt{"} e\texttt{"}
         followed by a possibly signed integer.

      }
      Examples of acceptable Frame input formats include:
      \sstitemlist{

         \sstitem
         99

         \sstitem
         1.25

         \sstitem
         -1.6

         \sstitem
         1E8

         \sstitem
         -.99e-17

         \sstitem
         $<$bad$>$
      }
   }
   \sstdiytopic{
      SkyFrame Input Format
   }{
      The input format accepted for a SkyFrame axis is as follows:
      \sstitemlist{

         \sstitem
         An optional sign, followed by between one and three fields
         representing either degrees, arc-minutes, arc-seconds or hours,
         minutes, seconds (e.g. \texttt{"} -12 42 03\texttt{"} ).

         \sstitem
         Each field should consist of a sequence of one or more digits,
         which may include leading zeros. At most one field may contain a
         decimal point, in which case it is taken to be the final field
         (e.g. decimal degrees might be given as \texttt{"} 124.707\texttt{"} , while degrees
         and decimal arc-minutes might be given as \texttt{"} -13 33.8\texttt{"} ).

         \sstitem
         The first field given may take any value, allowing angles and
         times outside the conventional ranges to be
         represented. However, subsequent fields must have values of less
         than 60 (e.g. \texttt{"} 720 45 31\texttt{"}  is valid, whereas \texttt{"} 11 45 61\texttt{"}  is not).

         \sstitem
         Fields may be separated by white space or by \texttt{"} :\texttt{"}  (colon), but
         the choice of separator must be used consistently throughout the
         value. Additional white space may be present around fields and
         separators (e.g. \texttt{"} - 2: 04 : 7.1\texttt{"} ).

         \sstitem
         The following field identification characters may be used as
         separators to replace either of those above (or may be appended
         to the final field), in order to identify the field to which
         they are appended: \texttt{"} d\texttt{"} ---degrees; \texttt{"} h\texttt{"} ---hours; \texttt{"} m\texttt{"} ---minutes of
         arc or time; \texttt{"} s\texttt{"} ---seconds of arc or time; \texttt{"} \texttt{'} \texttt{"}  (single
         quote)---minutes of arc; \texttt{"} \texttt{"} \texttt{"}  (double quote)---seconds of arc.
         Either lower or upper case may be used.  Fields must be given in
         order of decreasing significance (e.g. \texttt{"} -11D 3\texttt{'}  14.4\texttt{"} \texttt{"}  or
         \texttt{"} 22h14m11.2s\texttt{"} ).

         \sstitem
         The presence of any of the field identification characters
         \texttt{"} d\texttt{"} , \texttt{"} \texttt{'} \texttt{"}  (single quote) or \texttt{"} \texttt{"} \texttt{"}  (double quote) indicates that the
         value is to be interpreted as an angle. Conversely, the presence
         of \texttt{"} h\texttt{"}  indicates that it is to be interpreted as a time (with 24
         hours corresponding to 360 degrees). Incompatible angle/time
         identification characters may not be mixed (e.g. \texttt{"} 10h14\texttt{'} 3\texttt{"} \texttt{"}  is
         not valid).  The remaining field identification characters and
         separators do not specify a preference for an angle or a time
         and may be used with either.

         \sstitem
         If no preference for an angle or a time is expressed anywhere
         within the value, it is interpreted as an angle if the Format
         attribute string associated with the SkyFrame axis generates an
         angle and as a time otherwise. This ensures that values produced
         by astFormat are correctly interpreted by astUnformat.

         \sstitem
         Fields may be omitted, in which case they default to zero. The
         remaining fields may be identified by using appropriate field
         identification characters (see above) and/or by adding extra
         colon separators (e.g. \texttt{"} -05m13s\texttt{"}  is equivalent to \texttt{"} -:05:13\texttt{"} ). If
         a field is not identified explicitly, it is assumed that
         adjacent fields have been given, after taking account of any
         extra separator characters (e.g. \texttt{"} 14:25.4s\texttt{"}  specifies minutes
         and seconds, while \texttt{"} 14::25.4s\texttt{"}  specifies degrees and seconds).

         \sstitem
         If fields are omitted in such a way that the remaining ones
         cannot be identified uniquely (e.g. \texttt{"} 01:02\texttt{"} ), then the first
         field (either given explicitly or implied by an extra leading
         colon separator) is taken to be the most significant field that
         astFormat would produce when formatting a value (using the
         Format attribute associated with the SkyFrame axis).  By
         default, this means that the first field will normally be
         interpreted as degrees or hours. However, if this does not
         result in consistent field identification, then the last field
         (either given explicitly or implied by an extra trailing colon
         separator) is taken to to be the least significant field that
         astFormat would produce.

      }
      This final convention is intended to ensure that values formatted
      by astFormat which contain less than three fields will be
      correctly interpreted if read back using astUnformat, even if
      they do not contain field identification characters.

      Examples of acceptable SkyFrame input formats (with
      interpretation in parentheses) include:
      \sstitemlist{

         \sstitem
         -14d 13m 22.2s (-14d 13\texttt{'}  22.2\texttt{"} )

         \sstitem
         $+$ 12:34:56.7 (12d 34\texttt{'}  56.7\texttt{"}  or 12h 34m 56.7s)

         \sstitem
         001 : 02 : 03.4 (1d 02\texttt{'}  03.4\texttt{"}  or 1h 02m 03.4s)

         \sstitem
         22h 30 (22h 30m 00s)

         \sstitem
         136::10\texttt{"}  (136d 00\texttt{'}  10\texttt{"}  or 136h 00m 10s)

         \sstitem
         -14M 27S (-0d 14\texttt{'}  27\texttt{"}  or -0h 14m 27s)

         \sstitem
         -:14: (-0d 14\texttt{'}  00\texttt{"}  or -0h 14m 00s)

         \sstitem
         -::4.1 (-0d 00\texttt{'}  04.1\texttt{"}  or -0h 00m 04.1s)

         \sstitem
         .9\texttt{"}  (0d 00\texttt{'}  00.9\texttt{"} )

         \sstitem
         d12m (0d 12\texttt{'}  00\texttt{"} )

         \sstitem
         H 12:22.3s (0h 12m 22.3s)

         \sstitem
         $<$bad$>$ (AST\_\_BAD)

      }
      Where alternative interpretations are shown, the choice of angle or
      time depends on the associated \htmlref{Format(axis)}{Format(axis)} attribute.
   }
}
\sstroutine{
   astUnitMap
}{
   Create a UnitMap
}{
   \sstdescription{
      This function creates a new \htmlref{UnitMap}{UnitMap} and optionally initialises
      its attributes.

      A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the
      coordinates supplied to it. They are simply copied. This can be
      useful if a Mapping is required (e.g. to pass to another
      function) but you do not want it to have any effect.
   }
   \sstsynopsis{
      AstUnitMap $*$astUnitMap( int ncoord, const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of input and output coordinates (these numbers are
         necessarily the same).
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new UnitMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astUnitMap()
      }{
         A pointer to the new UnitMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astUnitNormMap
}{
   Create a UnitNormMap
}{
   \sstdescription{
      This function creates a new \htmlref{UnitNormMap}{UnitNormMap} and optionally initialises its
      attributes.

      The forward transformation of a UnitNormMap subtracts the specified centre
      and then transforms the resulting vector to a unit vector and the vector norm.
      The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs
      are in the same order as the input; the final output is the norm.

      The inverse transformation of a UnitNormMap multiplies each component
      of the provided vector by the provided norm and adds the specified centre.
      The output contains one fewer coordinate than the input: the initial Nin inputs
      are in the same order as the output; the final input is the norm.

      UnitNormMap enables radially symmetric transformations, as follows:
      \sstitemlist{

         \sstitem
         apply a UnitNormMap to produce a unit vector and norm (radius)

         \sstitem
         apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged

         \sstitem
         apply the same UnitNormMap in the inverse direction to produce the result
      }
   }
   \sstsynopsis{
      AstUnitNormMap $*$astUnitNormMap( int ncoord, const double centre[],
                                const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of coordinate values for each point to be
         transformed (i.e. the number of dimensions of the space in
         which the points will reside). Output will include one additional coordinate.
      }
      \sstsubsection{
         centre
      }{
         An array containing the values to be subtracted from the input
         coordinates before computing unit vector and norm. A separate
         value must be supplied for each coordinate.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new UnitNormMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astUnitNormMap()
      }{
         A pointer to the new UnitNormMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astUnlock
}{
   Unlock an Object for use by other threads
}{
   \sstdescription{
      Unlocks an \htmlref{Object}{Object} previously locked using \htmlref{astLock}{astLock}, so that other
      threads can use the Object. See astLock for further details.
   }
   \sstsynopsis{
      void astUnlock( AstObject $*$this, int report )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Object to be unlocked.
      }
      \sstsubsection{
         report
      }{
         If non-zero, an error will be reported if the supplied Object,
         or any Object contained within the supplied Object, is not
         currently locked by the running thread. If zero, such Objects
         will be left unchanged, and no error will be reported.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         This function applies to all Objects.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function attempts to execute even if the global error
         status is set, but no further error report will be made if it
         subsequently fails under these circumstances.

         \sstitem
         All unlocked Objects are excluded from AST context handling until
         they are re-locked using astLock.

         \sstitem
         This function is only available in the C interface.

         \sstitem
         This function returns without action if the Object is not currently
         locked by any thread. If it is locked by the running thread, it is
         unlocked. If it is locked by another thread, an error will be reported
         if \texttt{"} error\texttt{"}  is non-zero.

         \sstitem
         This function returns without action if the AST library has
         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
         option was not specified when running the \texttt{"} configure\texttt{"}  script).
      }
   }
}
\sstroutine{
   astVersion
}{
   Return the version of the AST library being used
}{
   \sstdescription{
      This macro invokes a function which
      returns an integer representing the version of the AST library
      being used. The library version is formatted as a string such as
      \texttt{"} 2.0-7\texttt{"}  which contains integers representing the \texttt{"} major version\texttt{"}  (2),
      the \texttt{"} minor version\texttt{"}  (0) and the \texttt{"} release\texttt{"}  (7). The integer returned
      by this function combines all three integers together into a single
      integer using the expresion:

      (major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release)
   }
   \sstsynopsis{
      int astVersion
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Object}{Object}
      }{
         This macro applies to all Objects.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astVersion
      }{
         The major version, minor version and release numbers for the AST
         library, encoded as a single integer.
      }
   }
}
\sstroutine{
   astWarnings
}{
   Returns any warnings issued by the previous read or write operation
}{
   \sstdescription{
      This function returns an AST \htmlref{KeyMap}{KeyMap} object holding the text of any
      warnings issued as a result of the previous invocation of the
      \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite}
      function on the \htmlref{Channel}{Channel}. If no warnings were issued, a
      a NULL value
      will be returned.

      Such warnings are non-fatal and will not prevent the
      read or write operation succeeding. However, the converted object
      may not be identical to the original object in all respects.
      Differences which would usually be deemed as insignificant in most
      usual cases will generate a warning, whereas more significant
      differences will generate an error.

      The \texttt{"} \htmlref{Strict}{Strict}\texttt{"}  attribute allows this warning facility to be switched
      off, so that a fatal error is always reported for any conversion
      error.
   }
   \sstsynopsis{
      AstKeyMap $*$astWarnings( AstChannel $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Channel.
      }
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         The basic Channel class generates a warning when ever an
         un-recognised item is encountered whilst reading an \htmlref{Object}{Object} from
         an external data source. If Strict is zero (the default), then
         unexpected items in the Object description are simply ignored,
         and any remaining items are used to construct the returned
         Object. If Strict is non-zero, an error will be reported and a
         NULL Object pointer returned if any unexpected items are
         encountered.

         As AST continues to be developed, new attributes are added
         occasionally to selected classes. If an older version of AST is
         used to read external Object descriptions created by a more
         recent version of AST, then the Channel class will, by default,
         ignore the new attributes, using the remaining attributes to
         construct the Object. This is usually a good thing. However,
         since external Object descriptions are often stored in plain
         text, it is possible to edit them using a text editor. This
         gives rise to the possibility of genuine errors in the
         description due to finger-slips, typos, or simple
         mis-understanding. Such inappropriate attributes will be ignored
         if Strict is left at its default zero value. This will cause the
         mis-spelled attribute to revert to its default value,
         potentially causing subtle changes in the behaviour of
         application software. If such an effect is suspected, the Strict
         attribute can be set non-zero, resulting in the erroneous
         attribute being identified in an error message.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         The returned KeyMap will contain warnings for all conditions
         listed in the \htmlref{Warnings}{Warnings} attribute.
      }
      \sstsubsection{
         \htmlref{XmlChan}{XmlChan}
      }{
         Reports conversion errors that result in what are usally
         insignificant  changes.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astWarnings()
      }{
         A pointer to the KeyMap holding the warning messages, or
         NULL
         if no warnings were issued during the previous read operation.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The returned KeyMap uses keys of the form \texttt{"} Warning\_1\texttt{"} ,
         \texttt{"} Warning\_2\texttt{"} , etc.

         \sstitem
         A value of
         NULL will be returned if this function is invoked with the AST
         error status set,
         or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astWatch
}{
   Identify a new error status variable for the AST library
}{
   \sstdescription{
      This function allows a new error status variable to be accessed
      by the AST library when checking for and reporting error
      conditions.

      By default, the library uses an internal integer error status
      which is set to an error value if an error occurs. Use of
      astWatch allows the internal error status to be replaced by an
      integer variable of your choosing, so that the AST library can
      share its error status directly with other code which uses the
      same error detection convention.

      If an alternative error status variable is supplied, it is used
      by all related AST functions and macros (e.g. \htmlref{astOK}{astOK}, \htmlref{astStatus}{astStatus}
      and \htmlref{astClearStatus}{astClearStatus}).
   }
   \sstsynopsis{
      int $*$astWatch( int $*$status\_ptr )
   }
   \sstparameters{
      \sstsubsection{
         status\_ptr
      }{
         Pointer to an int whose value is to be used subsequently as
         the AST inherited status value. If a NULL pointer is supplied,
         the AST library will revert to using its own internal error status.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astWatch()
      }{
         Address of the previous error status variable. This may later
         be passed back to astWatch to restore the previous behaviour
         of the library. (Note that on the first invocation of
         astWatch the returned value will be the address of the
         internal error status variable.)
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This function is not available in the FORTRAN 77 interface to
         the AST library.
      }
   }
}
\sstroutine{
   astWcsMap
}{
   Create a WcsMap
}{
   \sstdescription{
      This function creates a new \htmlref{WcsMap}{WcsMap} and optionally initialises its
      attributes.

      A WcsMap is used to represent sky coordinate projections as
      described in the (draft) FITS world coordinate system (FITS-WCS)
      paper by E.W. Griesen and M. Calabretta (A \& A, in preparation).
      This paper defines a set of functions, or sky projections, which
      transform longitude-latitude pairs representing spherical
      celestial coordinates into corresponding pairs of Cartesian
      coordinates (and vice versa).

      A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these
      sky projections and applies them to a specified pair of coordinates.
      All the projections in the FITS-WCS paper are supported, plus the now
      deprecated \texttt{"} TAN with polynomial correction terms\texttt{"}  projection which
      is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology,
      the transformation is between \texttt{"} native spherical\texttt{"}  and \texttt{"} projection
      plane\texttt{"}  coordinates.  These coordinates may, optionally, be embedded in
      a space with more than two dimensions, the remaining coordinates being
      copied unchanged. Note, however, that for consistency with other AST
      facilities, a WcsMap handles coordinates that represent angles
      in radians (rather than the degrees used by FITS-WCS).

      The type of FITS-WCS projection to be used and the coordinates
      (axes) to which it applies are specified when a WcsMap is first
      created. The projection type may subsequently be determined
      using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts
      may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute.

      Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"}  to be
      associated with each axis. These specify the precise form of the
      projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"}  is
      the integer axis index (starting at 1), and m is an integer
      \texttt{"} parameter index\texttt{"}  in the range 0 to 99. The number of projection
      parameters required by each projection, and their meanings, are
      dependent upon the projection type (most projections either do not
      use any projection parameters, or use parameters 1 and 2 associated
      with the latitude axis). Before creating a WcsMap you should consult
      the FITS-WCS paper for details of which projection parameters are
      required, and which have defaults. When creating the WcsMap, you must
      explicitly set values for all those required projection parameters
      which do not have defaults defined in this paper.
   }
   \sstsynopsis{
      AstWcsMap $*$astWcsMap( int ncoord, int type, int lonax, int latax,
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of coordinate values for each point to be
         transformed (i.e. the number of dimensions of the space in
         which the points will reside). This must be at least 2. The
         same number is applicable to both input and output points.
      }
      \sstsubsection{
         type
      }{
         The type of FITS-WCS projection to apply. This should be
         given using a macro value such as AST\_\_TAN (for a tangent
         plane projection), where the characters following the double
         underscore give the projection type code (in upper case) as
         used in the FITS-WCS \texttt{"} CTYPEi\texttt{"}  keyword. You should consult the
         FITS-WCS paper for a list of the available projections. The
         additional code of AST\_\_TPN can be supplied which represents a
         TAN projection with polynomial correction terms as defined in an
         early draft of the FITS-WCS paper.
      }
      \sstsubsection{
         lonax
      }{
         The index of the longitude axis. This should lie in the range
         1 to \texttt{"} ncoord\texttt{"} .
      }
      \sstsubsection{
         latax
      }{
         The index of the latitude axis. This should lie in the range
         1 to \texttt{"} ncoord\texttt{"}  and be distinct from \texttt{"} lonax\texttt{"} .
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new WcsMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.

         If the sky projection to be implemented requires projection
         parameter values to be set, then this should normally be done
         here via the PVi\_m attribute (see the \texttt{"} Examples\texttt{"}
         section). Setting values for these parameters is mandatory if
         they do not have default values (as defined in the FITS-WCS
         paper).
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astWcsMap()
      }{
         A pointer to the new WcsMap.
      }
   }
   \sstexamples{
      \sstexamplesubsection{
         wcsmap = astWcsMap( 2, AST\_\_MER, 1, 2, \texttt{"} \texttt{"}  );
      }{
         Creates a WcsMap that implements a FITS-WCS Mercator
         projection on pairs of coordinates, with coordinates 1 and 2
         representing the longitude and latitude respectively. Note
         that the FITS-WCS Mercator projection does not require any
         projection parameters.
      }
      \sstexamplesubsection{
         wcsmap = astWcsMap( 3, AST\_\_COE, 2, 3, \texttt{"} PV3\_1=40.0\texttt{"}  );
      }{
         Creates a WcsMap that implements a FITS-WCS conical equal
         area projection. The WcsMap acts on points in a 3-dimensional
         space; coordinates 2 and 3 represent longitude and latitude
         respectively, while the values of coordinate 1 are copied
         unchanged.  \htmlref{Projection}{Projection} parameter 1 associatyed with the latitude
         axis (corresponding to FITS keyword \texttt{"} PV3\_1\texttt{"} ) is required and has
         no default, so is set explicitly to 40.0 degrees. Projection
         parameter 2 (corresponding to FITS keyword \texttt{"} PV3\_2\texttt{"} ) is required
         but has a default of zero, so need not be specified.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The forward transformation of a WcsMap converts between
         FITS-WCS \texttt{"} native spherical\texttt{"}  and \texttt{"} relative physical\texttt{"}  coordinates,
         while the inverse transformation converts in the opposite
         direction. This arrangement may be reversed, if required, by
         using \htmlref{astInvert}{astInvert} or by setting the \htmlref{Invert}{Invert} attribute to a non-zero
         value.

         \sstitem
         If any set of coordinates cannot be transformed (for example,
         many projections do not cover the entire celestial sphere), then
         a WcsMap will yield coordinate values of AST\_\_BAD.

         \sstitem
         The validity of any projection parameters given via the PVi\_m
         parameter in the \texttt{"} options\texttt{"}  string is not checked by this
         function. However, their validity is checked when the resulting
         WcsMap is used to transform coordinates, and an error will
         result if the projection parameters do not satisfy all the
         required constraints (as defined in the FITS-WCS paper).

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astWinMap
}{
   Create a WinMap
}{
   \sstdescription{
      This function creates a new \htmlref{WinMap}{WinMap} and optionally initialises its
      attributes.

      A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular
      window in one coordinate system into a similar window in another
      coordinate system by scaling and shifting each axis (the window
      edges being parallel to the coordinate axes).

      A WinMap is specified by giving the coordinates of two opposite
      corners (A and B) of the window in both the input and output
      coordinate systems.
   }
   \sstsynopsis{
      AstWinMap $*$astWinMap( int ncoord,
                            const double ina[],  const double inb[],
                            const double outa[], const double outb[],
                            const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of coordinate values for each point to be
         transformed (i.e. the number of dimensions of the space in
         which the points will reside). The same number is applicable
         to both input and output points.
      }
      \sstsubsection{
         ina
      }{
         An array containing the \texttt{"} ncoord\texttt{"}
         coordinates of corner A of the window in the input coordinate
         system.
      }
      \sstsubsection{
         inb
      }{
         An array containing the \texttt{"} ncoord\texttt{"}
         coordinates of corner B of the window in the input coordinate
         system.
      }
      \sstsubsection{
         outa
      }{
         An array containing the \texttt{"} ncoord\texttt{"}
         coordinates of corner A of the window in the output coordinate
         system.
      }
      \sstsubsection{
         outb
      }{
         An array containing the \texttt{"} ncoord\texttt{"}
         coordinates of corner B of the window in the output coordinate
         system.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new WinMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astWinMap()
      }{
         A pointer to the new WinMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\sstroutine{
   astWrite
}{
   Write an Object to a Channel
}{
   \sstdescription{
      This function writes an \htmlref{Object}{Object} to a \htmlref{Channel}{Channel}, appending it to any
      previous Objects written to that Channel.
   }
   \sstsynopsis{
      int astWrite( AstChannel $*$this, AstObject $*$object )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the Channel.
      }
      \sstsubsection{
         object
      }{
         Pointer to the Object which is to be written.
      }
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather
         than the native AST encoding, then storing values in the
         FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking
         astWrite
         can help to produce a successful write.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astWrite()
      }{
         The number of Objects written to the Channel by this
         invocation of astWrite (normally, this will be one).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero will be returned if this function is invoked
         with the AST error status set, or if it should fail for any
         reason.

         \sstitem
         Invoking this function will usually cause the sink function
         associated with the channel to be called in order to transfer a
         textual description of the supplied object to some external data
         store. However, the FitsChan class behaves differently. Invoking
         this function on a FitsChan causes new FITS header cards to be
         added to an internal buffer (the sink function is not invoked).
         This buffer is written out through the sink function only when the
         FitsChan is deleted.
      }
   }
}
\sstroutine{
   astWriteFits
}{
   Write out all cards in a FitsChan to the sink function
}{
   \sstdescription{
      This function
      writes out all cards currently in the \htmlref{FitsChan}{FitsChan}. If the \htmlref{SinkFile}{SinkFile}
      attribute is set, they will be written out to the specified sink file.
      Otherwise, they will be written out using the sink function specified
      when the FitsChan was created. All cards are then deleted from the
      FitsChan.
   }
   \sstsynopsis{
      void astWriteFits( AstFitsChan $*$this )
   }
   \sstparameters{
      \sstsubsection{
         this
      }{
         Pointer to the FitsChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the SinkFile is unset, and no sink function is available, this
         method simply empties the FitsChan, and is then equivalent to
         \htmlref{astEmptyFits}{astEmptyFits}.

         \sstitem
         This method attempt to execute even if an error has occurred
         previously.
      }
   }
}
\sstroutine{
   astXmlChan
}{
   Create an XmlChan
}{
   \sstdescription{
      This function creates a new \htmlref{XmlChan}{XmlChan} and optionally initialises
      its attributes.

      A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O
      operations. Writing an \htmlref{Object}{Object} to an XmlChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
      XML description of that Object, and reading from an XmlChan will
      create a new Object from its XML description.

      Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting XML text. By default, however,
      an XmlChan will read from standard input and write to standard
      output.

      Alternatively, an XmlChan can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.
   }
   \sstsynopsis{
      AstXmlChan $*$astXmlChan( const char $*$($*$ source)( void ),
                              void ($*$ sink)( const char $*$ ),
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         source
      }{
         Pointer to a source function that takes no arguments and
         returns a pointer to a null-terminated string.  If no value
         has been set for the SourceFile attribute, this function
         will be used by the XmlChan to obtain lines of input text. On
         each invocation, it should return a pointer to the next input
         line read from some external data store, and a NULL pointer
         when there are no more lines to read.

         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
         attribute, the XmlChan will read from standard input instead.
      }
      \sstsubsection{
         sink
      }{
         Pointer to a sink function that takes a pointer to a
         null-terminated string as an argument and returns void.
         If no value has been set for the SinkFile attribute, this
         function will be used by the XmlChan to deliver lines of
         output text. On each invocation, it should deliver the
         contents of the string supplied to some external data store.

         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
         attribute, the XmlChan will write to standard output instead.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new XmlChan. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astXmlChan()
      }{
         A pointer to the new XmlChan.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the external data source or sink uses a character encoding
         other than ASCII, the supplied source and sink functions should
         translate between the external character encoding and the internal
         ASCII encoding used by AST.

         \sstitem
         A null Object pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
}
\sstroutine{
   astZoomMap
}{
   Create a ZoomMap
}{
   \sstdescription{
      This function creates a new \htmlref{ZoomMap}{ZoomMap} and optionally initialises its
      attributes.

      A ZoomMap is a \htmlref{Mapping}{Mapping} which \texttt{"} zooms\texttt{"}  a set of points about the
      origin by multiplying all coordinate values by the same scale
      factor (the inverse transformation is performed by dividing by
      this scale factor).
   }
   \sstsynopsis{
      AstZoomMap $*$astZoomMap( int ncoord, double zoom,
                              const char $*$options, ... )
   }
   \sstparameters{
      \sstsubsection{
         ncoord
      }{
         The number of coordinate values for each point to be
         transformed (i.e. the number of dimensions of the space in
         which the points will reside). The same number is applicable
         to both input and output points.
      }
      \sstsubsection{
         zoom
      }{
         Initial scale factor by which coordinate values should be
         multiplied (by the forward transformation) or divided (by the
         inverse transformation). This factor may subsequently be
         changed via the ZoomMap\texttt{'} s \htmlref{Zoom}{Zoom} attribute. It may be positive
         or negative, but should not be zero.
      }
      \sstsubsection{
         options
      }{
         Pointer to a null-terminated string containing an optional
         comma-separated list of attribute assignments to be used for
         initialising the new ZoomMap. The syntax used is identical to
         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
      }
      \sstsubsection{
         ...
      }{
         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
         an optional list of additional arguments may follow it in
         order to supply values to be substituted for these
         specifiers. The rules for supplying these are identical to
         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
         function).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astZoomMap()
      }{
         A pointer to the new ZoomMap.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
         function is invoked with the AST error status set, or if it
         should fail for any reason.
      }
   }
   \sstdiytopic{
      Status Handling
   }{
      The protected interface to this function includes an extra
      parameter at the end of the parameter list descirbed above. This
      parameter is a pointer to the integer inherited status
      variable: \texttt{"} int $*$status\texttt{"} .
   }
}
\normalsize

\cleardoublepage
\section{\label{ss:attributedescriptions}AST Attribute Descriptions}
\small
\sstroutine{
   Abbrev(axis)
}{
   Abbreviate leading fields within numerical axis labels?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether matching leading fields should be removed from adjacent
      numerical axis labels. It takes a separate value for each physical
      axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} Abbrev(2)=0\texttt{"}
      specifies that matching leading fields should not be removed on
      the second axis.

      If the Abbrev value of a Plot is non-zero (the default), then
      leading fields will be removed from adjacent axis labels if they
      are equal.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} Abbrev\texttt{"}  instead of
         \texttt{"} Abbrev(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the Abbrev(1) value.
      }
   }
}
\sstroutine{
   Adaptive
}{
   Should the area adapt to changes in the coordinate system?
}{
   \sstdescription{
      The coordinate system represented by a \htmlref{Region}{Region} may be changed by
      assigning new values to attributes such as \htmlref{System}{System}, Unit, etc.
      For instance, a Region representing an area on the sky in ICRS
      coordinates may have its System attribute changed so that it
      represents (say) Galactic coordinates instead of ICRS. This
      attribute controls what happens when the coordinate system
      represented by a Region is changed in this way.

      If Adaptive is non-zero (the default), then area represented by the
      Region adapts to the new coordinate system. That is, the numerical
      values which define the area represented by the Region are changed
      by mapping them from the old coordinate system into the new coordinate
      system. Thus the Region continues to represent the same physical
      area.

      If Adaptive is zero, then area represented by the Region does not adapt
      to the new coordinate system. That is, the numerical values which
      define the area represented by the Region are left unchanged. Thus
      the physical area represented by the Region will usually change.

      As an example, consider a Region describe a range of wavelength from
      2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region
      is changed from Angstrom to \texttt{"} nm\texttt{"}  (nanometre), what happens depends
      on the setting of Adaptive. If Adaptive is non-zero, the \htmlref{Mapping}{Mapping}
      from the old to the new coordinate system is found. In this case it
      is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm).
      This Mapping is then used to modify the numerical values within the
      Region, changing 2000 to 200 and 4000 to 400. Thus the modified
      region represents 200 nm to 400 nm, the same physical space as
      the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive
      had been zero, then the numerical values would not have been changed,
      resulting in the final Region representing 2000 nm to 4000 nm.

      Setting Adaptive to zero can be necessary if you want correct
      inaccurate attribute settings in an existing Region. For instance,
      when creating a Region you may not know what \htmlref{Epoch}{Epoch} value to use, so
      you would leave Epoch unset resulting in some default value being used.
      If at some later point in the application, the correct Epoch value
      is determined, you could assign the correct value to the Epoch
      attribute. However, you would first need to set Adaptive temporarily
      to zero, because otherwise the area represented by the Region would
      be Mapped from the spurious default Epoch to the new correct Epoch,
      which is not what is required.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
   }
}
\sstroutine{
   AlignOffset
}{
   Align SkyFrames using the offset coordinate system?
}{
   \sstdescription{
      This attribute is a boolean value which controls how a \htmlref{SkyFrame}{SkyFrame}
      behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
      SkyFrame. It determines the coordinate system in which the two
      SkyFrames are aligned if a match occurs.

      If the template and target SkyFrames both have defined offset coordinate
      systems (i.e. the \htmlref{SkyRefIs}{SkyRefIs} attribute is set to either \texttt{"} Origin\texttt{"}  or \texttt{"}
      Pole\texttt{"} ), and they both have a non-zero value for AlignOffset, then
      alignment occurs within the offset coordinate systems (that is, a
      \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). If either
      the template or target SkyFrame has zero (the default value) for
      AlignOffset, or if either SkyFrame has SkyRefIs set to \texttt{"} Ignored\texttt{"} , then
      alignment occurring within the coordinate system specified by the
      \htmlref{AlignSystem}{AlignSystem} attribute.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   AlignSideBand
}{
   Should the SideBand attribute be taken into account when aligning
   this \htmlref{DSBSpecFrame}{DSBSpecFrame} with another DSBSpecFrame?
}{
   \sstdescription{
      This attribute controls how a DSBSpecFrame behaves when an attempt
      is made to align it with another DSBSpecFrame using
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}.
      If both DSBSpecFrames have a non-zero value for AlignSideBand, the
      value of the \htmlref{SideBand}{SideBand} attribute in each DSBSpecFrame is used so that
      alignment occurs between sidebands. That is, if one DSBSpecFrame
      represents USB and the other represents LSB then
      astFindFrame and astConvert
      will recognise that the DSBSpecFrames represent different sidebands
      and will take this into account when constructing the \htmlref{Mapping}{Mapping} that
      maps positions in one DSBSpecFrame into the other. If AlignSideBand
      in either DSBSpecFrame is set to zero, then the values of the SideBand
      attributes are ignored. In the above example, this would result in a
      frequency in the first DSBSpecFrame being mapped onto the same
      frequency in the second DSBSpecFrame, even though those frequencies
      refer to different sidebands. In other words, if either AlignSideBand
      attribute is zero, then the two DSBSpecFrames aligns like basic
      SpecFrames. The default value for AlignSideBand is zero.

      When astFindFrame or astConvert
      is used on two DSBSpecFrames (potentially describing different spectral
      coordinate systems and/or sidebands), it returns a Mapping which can be
      used to transform a position in one DSBSpecFrame into the corresponding
      position in the other. The Mapping is made up of the following steps in
      the indicated order:

      \sstitemlist{

         \sstitem
         If both DSBSpecFrames have a value of 1 for the AlignSideBand
         attribute, map values from the target\texttt{'} s current sideband (given by its
         SideBand attribute) to the observed sideband (whether USB or LSB). If
         the target already represents the observed sideband, this step will
         leave the values unchanged. If either of the two DSBSpecFrames have a
         value of zero for its AlignSideBand attribute, then this step is omitted.

         \sstitem
         Map the values from the spectral system of the target to the spectral
         system of the template. This Mapping takes into account all the
         inherited \htmlref{SpecFrame}{SpecFrame} attributes such as \htmlref{System}{System}, \htmlref{StdOfRest}{StdOfRest}, Unit, etc.

         \sstitem
         If both DSBSpecFrames have a value of 1 for the AlignSideBand
         attribute, map values from the result\texttt{'} s observed sideband to the
         result\texttt{'} s current sideband (given by its SideBand attribute). If the
         result already represents the observed sideband, this step will leave
         the values unchanged. If either of the two DSBSpecFrames have a value
         of zero for its AlignSideBand attribute, then this step is omitted.
      }
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         DSBSpecFrame
      }{
         All DSBSpecFrames have this attribute.
      }
   }
}
\sstroutine{
   AlignSpecOffset
}{
   Align SpecFrames using the offset coordinate system?
}{
   \sstdescription{
      This attribute is a boolean value which controls how a \htmlref{SpecFrame}{SpecFrame}
      behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
      SpecFrame. It determines whether alignment occurs between the offset
      values defined by the current value of the SpecOffset attribute, or
      between the corresponding absolute spectral values.

      The default value of zero results in the two SpecFrames being aligned
      so that a given absolute spectral value in one is mapped to the same
      absolute value in the other. A non-zero value results in the SpecFrames
      being aligned so that a given offset value in one is mapped to the same
      offset value in the other.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         SpecFrame
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   AlignStdOfRest
}{
   Standard of rest to use when aligning SpecFrames
}{
   \sstdescription{
      This attribute controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
      SpecFrame. It identifies the standard of rest in which alignment is
      to occur. See the \htmlref{StdOfRest}{StdOfRest} attribute for a desription of the values
      which may be assigned to this attribute. The default AlignStdOfRest
      value is \texttt{"} Helio\texttt{"}  (heliographic).

      When astFindFrame or astConvert is used on two SpecFrames (potentially
      describing different spectral coordinate systems), it returns a \htmlref{Mapping}{Mapping}
      which can be used to transform a position in one SpecFrame into the
      corresponding position in the other. The Mapping is made up of the
      following steps in the indicated order:

      \sstitemlist{

         \sstitem
         Map values from the system used by the target (wavelength,
         apparent radial velocity, etc) to the system specified by the
         \htmlref{AlignSystem}{AlignSystem} attribute, using the target\texttt{'} s rest frequency if necessary.

         \sstitem
         Map these values from the target\texttt{'} s standard of rest to the standard of
         rest specified by the AlignStdOfRest attribute, using the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat},
         \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{RefDec}{RefDec} and \htmlref{RefRA}{RefRA} attributes of the target to define the
         two standards of rest.

         \sstitem
         Map these values from the standard of rest specified by the
         AlignStdOfRest attribute, to the template\texttt{'} s standard of rest, using the
         Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the
         template to define the two standards of rest.

         \sstitem
         Map these values from the system specified by the AlignSystem
         attribute, to the system used by the template, using the template\texttt{'} s
         rest frequency if necessary.
      }
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         SpecFrame
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   AlignSystem
}{
   Coordinate system in which to align the Frame
}{
   \sstdescription{
      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
      Frame. It identifies the coordinate system in which the two Frames
      will be aligned by the match.

      The values which may be assigned to this attribute, and its default
      value, depend on the class of Frame and are described in the
      \texttt{"} Applicability\texttt{"}  section below. In general, the AlignSystem attribute
      will accept any of the values which may be assigned to the \htmlref{System}{System}
      attribute.

      The \htmlref{Mapping}{Mapping} returned by AST\_FINDFRAME or AST\_CONVERT will use the
      coordinate system specified by the AlignSystem attribute as an
      intermediate coordinate system. The total returned Mapping will first
      map positions from the first Frame into this intermediate coordinate
      system, using the attributes of the first Frame. It will then map
      these positions from the intermediate coordinate system into the
      second Frame, using the attributes of the second Frame.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The AlignSystem attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} ,
         and may not be altered.
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The AlignSystem attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} ,
         and may not be altered.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The AlignSystem attribute of a FrameSet is the same as that of its
         current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The default AlignSystem attribute for a SkyFrame is \texttt{"} ICRS\texttt{"} .
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         The default AlignSystem attribute for a SpecFrame is \texttt{"} Wave\texttt{"}
         (wavelength).
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The default AlignSystem attribute for a TimeFrame is \texttt{"} MJD\texttt{"} .
      }
   }
}
\sstroutine{
   AlignTimeScale
}{
   Time scale to use when aligning TimeFrames
}{
   \sstdescription{
      This attribute controls how a \htmlref{TimeFrame}{TimeFrame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
      TimeFrame. It identifies the time scale in which alignment is
      to occur. See the \htmlref{TimeScale}{TimeScale} attribute for a desription of the values
      which may be assigned to this attribute. The default AlignTimeScale
      value depends on the current value of TimeScale: if TimeScale is
      UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all
      other TimeScales the default is TAI.

      When astFindFrame or astConvert is used on two TimeFrames (potentially
      describing different time coordinate systems), it returns a \htmlref{Mapping}{Mapping}
      which can be used to transform a position in one TimeFrame into the
      corresponding position in the other. The Mapping is made up of the
      following steps in the indicated order:

      \sstitemlist{

         \sstitem
         Map values from the system used by the target (MJD, JD, etc) to the
         system specified by the \htmlref{AlignSystem}{AlignSystem} attribute.

         \sstitem
         Map these values from the target\texttt{'} s time scale to the time scale
         specified by the AlignTimeScale attribute.

         \sstitem
         Map these values from the time scale specified by the AlignTimeScale
         attribute, to the template\texttt{'} s time scale.

         \sstitem
         Map these values from the system specified by the AlignSystem
         attribute, to the system used by the template.
      }
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         TimeFrame
      }{
         All TimeFrames have this attribute.
      }
   }
}
\sstroutine{
   AllVariants
}{
   A list of the variant Mappings associated with the current Frame
}{
   \sstdescription{
      This attrbute gives a space separated list of the names of all the
      variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute
      \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the
      list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the
      current Frame.
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         All FrameSets have this attribute.
      }
   }
}
\sstroutine{
   AllWarnings
}{
   A list of all currently available condition names
}{
   \sstdescription{
      This read-only attribute is a space separated list of all the conditions
      names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed
      below.
   }
   \sstattributetype{
      String, read-only
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         All FitsChans have this attribute.
      }
   }
   \sstdiytopic{
      Conditions
   }{
      The following conditions are currently recognised (all are
      case-insensitive):

      \sstitemlist{

         \sstitem
         \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a
         non-Native encoded FitsChan if an unknown celestial co-ordinate
         system is specified by the CTYPE keywords.

         \sstitem
         \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a
         non-Native encoded FitsChan if an illegal algorithm code is specified
         by a CTYPE keyword, and the illegal code can be converted to an
         equivalent legal code.

         \sstitem
         \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is
         encountered that contains an illegal character (i.e. one not allowed
         by the FITS standard).

         \sstitem
         \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword
         cannot be determined from the content of the header card.

         \sstitem
         \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a
         non-Native encoded FitsChan if the latitude of the reference point
         has an absolute value greater than 90 degrees. The actual absolute
         value used is set to exactly 90 degrees in these cases.

         \sstitem
         \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the
         transformation from pixel offsets to intermediate world coordinates
         cannot be inverted. This matrix describes the scaling, rotation, shear,
         etc., applied to the pixel axes, and is specified by keywords such as
         PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable
         if any rows or columns consist entirely of zeros. The FITS-WCS Paper I
         \texttt{"} Representation of World Coordinates in FITS\texttt{"}  by Greisen \& Calabretta
         requires that this matrix be invertable. Many operations (such as
         grid plotting) will not be possible if the matrix cannot be inverted.

         \sstitem
         \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a
         non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found
         that refers to a projection parameter that is not used by the
         projection type specified by CTYPE, or the PV values are otherwise
         inappropriate for the projection type.

         \sstitem
         \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a
         non-Native encoded FitsChan if it is not possible to convert the
         value of a FITS keywords to the expected type. For instance, this
         can occur if the FITS header contains a string value for a keyword
         which should have a floating point value, or if the keyword has no
         value at all (i.e. is a comment card).

         \sstitem
         \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a
         non-Native encoded FitsChan if any of the CTYPE keywords specify an
         unsupported distortion code using the \texttt{"} 4-3-3\texttt{"}  format specified in
         FITS-WCS paper IV. Such distortion codes are ignored.

         \sstitem
         \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used
         within \htmlref{astRead}{astRead}, due to no value being present in the supplied FitsChan.
         This condition is only tested for when using non-Native encodings.

         \sstitem
         \texttt{"} NoEquinox\texttt{"} : This condition arises if a default equinox value is used
         within astRead, due to no value being present in the supplied FitsChan.
         This condition is only tested for when using non-Native encodings.

         \sstitem
         \texttt{"} NoRadesys\texttt{"} : This condition arises if a default reference frame is
         used for an equatorial co-ordinate system within astRead, due to no
         value being present in the supplied FitsChan. This condition is only
         tested for when using non-Native encodings.

         \sstitem
         \texttt{"} NoLonpole\texttt{"} : This condition arises if a default value is used for
         the LONPOLE keyword within astRead, due to no value being present
         in the supplied FitsChan. This condition is only tested for when
         using non-Native encodings.

         \sstitem
         \texttt{"} NoLatpole\texttt{"} : This condition arises if a default value is used for
         the LATPOLE keyword within astRead, due to no value being present
         in the supplied FitsChan. This condition is only tested for when
         using non-Native encodings.

         \sstitem
         \texttt{"} NoMjd-obs\texttt{"} : This condition arises if a default value is used for
         the date of observation within astRead, due to no value being present
         in the supplied FitsChan. This condition is only tested for when using
         non-Native encodings.

         \sstitem
         \texttt{"} Tnx\texttt{"} : This condition arises if a FrameSet is read from a FITS
         header containing an IRAF \texttt{"} TNX\texttt{"}  projection which includes terms
         not supproted by AST. Such terms are ignored and so the resulting
         FrameSet may be inaccurate.

         \sstitem
         \texttt{"} Zpx\texttt{"} : This condition arises if a FrameSet is read from a FITS
         header containing an IRAF \texttt{"} ZPX\texttt{"}  projection which includes \texttt{"} lngcor\texttt{"}
         or \texttt{"} latcor\texttt{"}  correction terms. These terms are not supported by AST
         and are ignored. The resulting FrameSet may therefore be inaccurate.
      }
   }
}
\sstroutine{
   AsTime(axis)
}{
   Format celestal coordinates as times?
}{
   \sstdescription{
      This attribute specifies the default style of formatting to be
      used (e.g. by \htmlref{astFormat}{astFormat}) for the celestial coordinate values
      described by a \htmlref{SkyFrame}{SkyFrame}. It takes a separate boolean value for
      each SkyFrame axis so that, for instance, the setting
      \texttt{"} AsTime(2)=0\texttt{"}  specifies the default formatting style for
      celestial latitude values.

      If the AsTime attribute for a SkyFrame axis is zero, then
      coordinates on that axis will be formatted as angles by default
      (using degrees, minutes and seconds), otherwise they will be
      formatted as times (using hours, minutes and seconds).

      The default value of AsTime is chosen according to the sky
      coordinate system being represented, as determined by the
      SkyFrame\texttt{'} s \htmlref{System}{System} attribute. This ensures, for example, that
      right ascension values will be formatted as times by default,
      following normal conventions.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The AsTime attribute operates by changing the default value of
         the corresponding \htmlref{Format(axis)}{Format(axis)} attribute. This, in turn, may
         also affect the value of the \htmlref{Unit(axis)}{Unit(axis)} attribute.

         \sstitem
         Only the default style of formatting is affected by the AsTime
         value. If an explicit Format(axis) value is set, it will
         over-ride any effect from the AsTime attribute.
      }
   }
}
\sstroutine{
   Base
}{
   FrameSet base Frame index
}{
   \sstdescription{
      This attribute gives the index of the \htmlref{Frame}{Frame} which is to be
      regarded as the \texttt{"} base\texttt{"}  Frame within a \htmlref{FrameSet}{FrameSet}. The default is
      the first Frame added to the FrameSet when it is created (this
      Frame always has an index of 1).

      When setting a new value for this attribute, a string may be
      supplied instead of an integer index. In this case a search
      is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain}
      attribute value equal to the supplied string (the comparison is
      case-insensitive). If found, the Frame is made the base Frame.
      Otherwise an error is reported.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FrameSet
      }{
         All FrameSets have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Inverting a FrameSet (inverting the boolean sense of its
         \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will
         interchange the values of its Base and \htmlref{Current}{Current} attributes.
      }
   }
}
\sstroutine{
   Border
}{
   Draw a border around valid regions of a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether a border is drawn around regions corresponding to the
      valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{astBorder}{astBorder}).

      If the Border value of a Plot is non-zero, then this border will
      be drawn as part of the grid. Otherwise, the border is not drawn
      (although axis labels and tick marks will still appear, unless
      other relevant Plot attributes indicate that they should
      not). The default behaviour is to draw the border if tick marks
      and numerical labels will be drawn around the edges of the
      plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit it
      otherwise.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
}
\sstroutine{
   Bottom(axis)
}{
   Lowest axis value to display
}{
   \sstdescription{
      This attribute gives the lowest axis value to be displayed (for
      instance, by the \htmlref{astGrid}{astGrid} method).
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         The default supplied by the Frame class is to display all axis
         values, without any limit.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Bottom value to -90 degrees
         for latitude axes, and 0 degrees for co-latitude axes. The
         default for longitude axes is to display all axis values.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   Bounded
}{
   Is the Region bounded?
}{
   \sstdescription{
      This is a read-only attribute indicating if the \htmlref{Region}{Region} is bounded.
      A Region is bounded if it is contained entirely within some
      finite-size bounding box.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
   }
}
\sstroutine{
   CDMatrix
}{
   Use CDi\_j keywords to represent pixel scaling, rotation, etc?
}{
   \sstdescription{
      This attribute is a boolean value which specifies how the linear
      transformation from pixel coordinates to intermediate world
      coordinates should be represented within a \htmlref{FitsChan}{FitsChan} when using
      FITS-WCS encoding. This transformation describes the scaling,
      rotation, shear, etc., of the pixel axes.

      If the attribute has a non-zero value then the transformation is
      represented by a set of CDi\_j keywords representing a square matrix
      (where \texttt{"} i\texttt{"}  is the index of an intermediate world coordinate axis
      and \texttt{"} j\texttt{"}  is the index of a pixel axis). If the attribute has a zero
      value the transformation is represented by a set of PCi\_j keywords
      (which also represent a square matrix) together with a corresponding
      set of CDELTi keywords representing the axis scalings. See FITS-WCS
      paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"}  by
      M. Calabretta \& E.W. Greisen, for a complete description of these two
      schemes.

      The default value of the CDMatrix attribute is determined by the
      contents of the FitsChan at the time the attribute is accessed. If
      the FitsChan contains any CDi\_j keywords then the default value is
      non-zero. Otherwise it is zero. Note, reading a \htmlref{FrameSet}{FrameSet} from a
      FitsChan will in general consume any CDi\_j keywords present in the
      FitsChan. Thus the default value for CDMatrix following a read will
      usually be zero, even if the FitsChan originally contained some
      CDi\_j keywords. This behaviour is similar to that of the \htmlref{Encoding}{Encoding}
      attribute, the default value for which is determined by the contents
      of the FitsChan at the time the attribute is accessed. If you wish
      to retain the original value of the CDMatrix attribute (that is,
      the value before reading the FrameSet) then you should enquire the
      default value before doing the read, and then set that value
      explicitly.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   CarLin
}{
   Ignore spherical rotations on CAR projections?
}{
   \sstdescription{
      This attribute is a boolean value which specifies how FITS \texttt{"} CAR\texttt{"}
      (plate carree, or \texttt{"} Cartesian\texttt{"} ) projections should be treated when
      reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero (the
      default), it is assumed that the CAR projection conforms to the
      conventions described in the FITS world coordinate system (FITS-WCS)
      paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"}  by
      M. Calabretta \& E.W. Greisen. If CarLin is non-zero, then these
      conventions are ignored, and it is assumed that the mapping from pixel
      coordinates to celestial coordinates is a simple linear transformation
      (hence the attribute name \texttt{"} CarLin\texttt{"} ). This is appropriate for some older
      FITS data which claims to have a \texttt{"} CAR\texttt{"}  projection, but which in fact do
      not conform to the conventions of the FITS-WCS paper.

      The FITS-WCS paper specifies that headers which include a CAR projection
      represent a linear mapping from pixel coordinates to \texttt{"} native spherical
      coordinates\texttt{"} , NOT celestial coordinates. An extra mapping is then
      required from native spherical to celestial. This mapping is a 3D
      rotation and so the overall \htmlref{Mapping}{Mapping} from pixel to celestial coordinates
      is NOT linear. See the FITS-WCS papers for further details.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Card
}{
   Index of current FITS card in a FitsChan
}{
   \sstdescription{
      This attribute gives the index of the \texttt{"} current\texttt{"}  FITS header card
      within a \htmlref{FitsChan}{FitsChan}, the first card having an index of 1. The
      choice of current card affects the behaviour of functions that
      access the contents of the FitsChan, such as \htmlref{astDelFits}{astDelFits},
      \htmlref{astFindFits}{astFindFits} and \htmlref{astPutFits}{astPutFits}.

      A value assigned to Card will position the FitsChan at any
      desired point, so that a particular card within it can be
      accessed. Alternatively, the value of Card may be enquired in
      order to determine the current position of a FitsChan.

      The default value of Card is 1. This means that clearing
      this attribute (using \htmlref{astClear}{astClear}) effectively \texttt{"} rewinds\texttt{"}  the
      FitsChan, so that the first card is accessed next.  If Card is
      set to a value which exceeds the total number of cards in the
      FitsChan (as given by its \htmlref{Ncard}{Ncard} attribute), it is regarded as
      pointing at the \texttt{"} end-of-file\texttt{"} . In this case, the value returned
      in response to an enquiry is always one more than the number of
      cards in the FitsChan.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   CardComm
}{
   The comment for the current card in a FitsChan
}{
   \sstdescription{
      This attribute gives the comment for the current card of the
      \htmlref{FitsChan}{FitsChan}. A zero-length string is returned if the card has no comment.
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   CardName
}{
   The keyword name of the current card in a FitsChan
}{
   \sstdescription{
      This attribute gives the name of the keyword for the
      current card of the \htmlref{FitsChan}{FitsChan}.
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   CardType
}{
   The data type of the current card in a FitsChan
}{
   \sstdescription{
      This attribute gives the data type of the keyword value for the
      current card of the \htmlref{FitsChan}{FitsChan}. It will be one of the following
      integer constants: AST\_\_NOTYPE, AST\_\_COMMENT, AST\_\_INT, AST\_\_FLOAT,
      AST\_\_STRING, AST\_\_COMPLEXF, AST\_\_COMPLEXI, AST\_\_LOGICAL,
      AST\_\_CONTINUE, AST\_\_UNDEF.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Class
}{
   Object class name
}{
   \sstdescription{
      This attribute gives the name of the class to which an \htmlref{Object}{Object}
      belongs.
   }
   \sstattributetype{
      Character string, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   Clean
}{
   Remove cards used whilst reading even if an error occurs?
}{
   \sstdescription{
      This attribute indicates whether or not cards should be removed from
      the \htmlref{FitsChan}{FitsChan} if an error occurs within
      \htmlref{astRead}{astRead}.
      A succesful read on a FitsChan always results in the removal of
      the cards which were involved in the description of the returned
      \htmlref{Object}{Object}. However, in the event of an error during the read (for instance
      if the cards in the FitsChan have illegal values, or if some required
      cards are missing) no cards will be removed from the FitsChan if
      the Clean attribute is zero (the default). If Clean is non-zero then
      any cards which were used in the aborted attempt to read an object
      will be removed.

      This provides a means of \texttt{"} cleaning\texttt{"}  a FitsChan of WCS related cards
      which works even in the event of the cards not forming a legal WCS
      description.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Clip
}{
   Clip lines and/or markers at the Plot boundary?
}{
   \sstdescription{
      This attribute controls whether curves and markers are clipped at the
      boundary of the graphics box specified when the \htmlref{Plot}{Plot} was created. A
      value of 3 implies both markers and curves are clipped at the Plot
      boundary. A value of 2 implies markers are clipped, but not curves. A
      value of 1 implies curves are clipped, but not markers. A value of
      zero implies neither curves nor markers are clipped. The default
      value is 1. Note, this attributes controls only the clipping
      performed internally within AST. The underlying graphics system may
      also apply clipping. In such cases, removing clipping using this
      attribute does not guarantee that no clipping will be visible in the
      final plot.

      The \htmlref{astClip}{astClip} function
      can be used to establish generalised clipping within arbitrary
      regions of the Plot.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
}
\sstroutine{
   ClipOp
}{
   Combine Plot clipping limits using a boolean OR?
}{
   \sstdescription{
      This attribute controls how the clipping limits specified for
      each axis of a \htmlref{Plot}{Plot} (using the \htmlref{astClip}{astClip} function) are
      combined. This, in turn, determines which parts of the graphical
      output will be visible.

      If the ClipOp attribute of a Plot is zero (the default),
      graphical output is visible only if it satisfies the clipping
      limits on all the axes of the clipping \htmlref{Frame}{Frame} (a boolean
      AND). Otherwise, if ClipOp is non-zero, output is visible if it
      satisfies the clipping limits on one or more axes (a boolean
      OR).

      An important use of this attribute is to allow areas of a Plot
      to be left clear (e.g. as a background for some text). To
      achieve this, the lower and upper clipping bounds supplied to
      astClip should be reversed, and the ClipOp attribute of the
      Plot should be set to a non-zero value.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
}
\sstroutine{
   Closed
}{
   Should the boundary be considered to be inside the region?
}{
   \sstdescription{
      This attribute controls whether points on the boundary of a \htmlref{Region}{Region}
      are considered to be inside or outside the region. If the attribute
      value is non-zero (the default), points on the boundary are considered
      to be inside the region (that is, the Region is \texttt{"} closed\texttt{"} ). However,
      if the attribute value is zero, points on the bounary are considered
      to be outside the region.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
      \sstsubsection{
         \htmlref{PointList}{PointList}
      }{
         The value of the Closed attribute is ignored by PointList regions.
         If the PointList region has not been negated, then it is always
         assumed to be closed. If the PointList region has been negated, then
         it is always assumed to be open. This is required since points
         have zero volume and therefore consist entirely of boundary.
      }
      \sstsubsection{
         \htmlref{CmpRegion}{CmpRegion}
      }{
         The default Closed value for a CmpRegion is the Closed value of its
         first component Region.
      }
      \sstsubsection{
         \htmlref{Stc}{Stc}
      }{
         The default Closed value for an Stc is the Closed value of its
         encapsulated Region.
      }
   }
}
\sstroutine{
   Colour(element)
}{
   Colour index for a Plot element
}{
   \sstdescription{
      This attribute determines the colour index used when drawing
      each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
      separate value for each graphical element so that, for instance,
      the setting \texttt{"} Colour(title)=2\texttt{"}  causes the Plot title to be drawn
      using colour index 2. The synonym \texttt{"} Color\texttt{"}  may also be used.

      The range of integer colour indices available and their
      appearance is determined by the underlying graphics system. The
      default behaviour is for all graphical elements to be drawn
      using the default colour index supplied by this graphics system
      (normally, this is likely to result in white plotting on a black
      background, or vice versa).
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of the graphical elements available, see the
         description of the Plot class.

         \sstitem
         If no graphical element is specified, (e.g. \texttt{"} Colour\texttt{"}  instead
         of \texttt{"} Colour(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
         affect the attribute value of all graphical elements, while a
         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Colour(TextLab)
         value.
      }
   }
}
\sstroutine{
   ColumnLenC(column)
}{
   The largest string length of any value in a column
}{
   \sstdescription{
      This attribute holds the minimum length which a character variable
      must have in order to be able to store the longest value currently
      present (at any row) in a specified column of the supplied \htmlref{Table}{Table}.
      This does not include room for a trailing null character.
      The required column name should be placed inside the parentheses in
      the attribute name. If the named column holds vector values, then
      the attribute value is the length of the longest element of the
      vector value.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Table
      }{
         All Tables have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the named column holds numerical values, the length returned
         is the length of the largest string that would be generated if the
         column values were accessed as strings.
      }
   }
}
\sstroutine{
   ColumnLength(column)
}{
   The number of elements in each value in a column
}{
   \sstdescription{
      This attribute holds the number of elements in each value stored
      in a named column. Each value can be a scalar (in which case the
      ColumnLength attribute has a value of 1), or a multi-dimensional
      array ( in which case the ColumnLength value is equal to the
      product of the array dimensions).
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   ColumnNdim(column)
}{
   The number of axes spanned by each value in a column
}{
   \sstdescription{
      This attribute holds the number of axes spanned by each value in a
      column. If each cell in the column is a scalar, ColumnNdim will be
      zero. If each cell in the column is a 1D spectrum, ColumnNdim will
      be one. If each cell in the column is a 2D image, ColumnNdim will be
      two, etc. The required column name should be placed inside the
      parentheses in the attribute name.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   ColumnType(column)
}{
   The data type of each value in a column
}{
   \sstdescription{
      This attribute holds a integer value indicating the data type of
      a named column in a \htmlref{Table}{Table}. This is the data type which was used
      when the column was added to the Table using \htmlref{astAddColumn}{astAddColumn}. The
      required column name should be placed inside the parentheses in
      the attribute name.

      The attribute value will be one of AST\_\_INTTYPE (for integer),
      AST\_\_SINTTYPE (for
      short int),
      AST\_\_BYTETYPE (for
      unsigned bytes - i.e. unsigned chars),
      AST\_\_DOUBLETYPE (for double
      precision floating point), AST\_\_FLOATTYPE (for single
      precision floating point), AST\_\_STRINGTYPE (for character string),
      AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
      arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
      created by
      \htmlref{astMapPutU}{astMapPutU}).
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Table
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   Comment
}{
   Include textual comments in output?
}{
   \sstdescription{
      This is a boolean attribute which controls whether textual
      comments are to be included in the output generated by a
      \htmlref{Channel}{Channel}. If included, they will describe what each item of
      output represents.

      If Comment is non-zero, then comments will be included. If
      it is zero, comments will be omitted.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         The default value is non-zero for a normal Channel.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         The default value is non-zero for a FitsChan.
      }
      \sstsubsection{
         \htmlref{XmlChan}{XmlChan}
      }{
         The default value is zero for an XmlChan.
      }
   }
}
\sstroutine{
   Current
}{
   FrameSet current Frame index
}{
   \sstdescription{
      This attribute gives the index of the \htmlref{Frame}{Frame} which is to be
      regarded as the \texttt{"} current\texttt{"}  Frame within a \htmlref{FrameSet}{FrameSet}. The default
      is the most recent Frame added to the FrameSet (this Frame
      always has an index equal to the FrameSet\texttt{'} s \htmlref{Nframe}{Nframe} attribute).

      When setting a new value for this attribute, a string may be
      supplied instead of an integer index. In this case a search
      is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain}
      attribute value equal to the supplied string (the comparison is
      case-insensitive). If found, the Frame is made the current Frame.
      Otherwise an error is reported.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FrameSet
      }{
         All FrameSets have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Inverting a FrameSet (inverting the boolean sense of its
         \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will
         interchange the values of its \htmlref{Base}{Base} and Current attributes.
      }
   }
}
\sstroutine{
   DSBCentre
}{
   The central position of interest in a dual sideband spectrum
}{
   \sstdescription{
      This attribute specifies the central position of interest in a dual
      sideband spectrum. Its sole use is to determine the local oscillator
      frequency (the frequency which marks the boundary between the lower
      and upper sidebands). See the description of the \htmlref{IF}{IF} (intermediate
      frequency) attribute for details of how the local oscillator frequency
      is calculated. The sideband containing this central position is
      referred to as the \texttt{"} observed\texttt{"}  sideband, and the other sideband as
      the \texttt{"} image\texttt{"}  sideband.

      The value is accessed as a position in the spectral system
      represented by the \htmlref{SpecFrame}{SpecFrame} attributes inherited by this class, but
      is stored internally as topocentric frequency. Thus, if the \htmlref{System}{System}
      attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} is set to \texttt{"} VRAD\texttt{"} , the Unit attribute
      set to \texttt{"} m/s\texttt{"}  and the \htmlref{StdOfRest}{StdOfRest} attribute set to \texttt{"} LSRK\texttt{"} , then values
      for the DSBCentre attribute should be supplied as radio velocity in
      units of \texttt{"} m/s\texttt{"}  relative to the kinematic LSR (alternative units may
      be used by appending a suitable units string to the end of the value).
      This value is then converted to topocentric frequency and stored. If
      (say) the Unit attribute is subsequently changed to \texttt{"} km/s\texttt{"}  before
      retrieving the current value of the DSBCentre attribute, the stored
      topocentric frequency will be converted back to LSRK radio velocity,
      this time in units of \texttt{"} km/s\texttt{"} , before being returned.

      The default value for this attribute is 30 GHz.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         DSBSpecFrame
      }{
         All DSBSpecFrames have this attribute.
      }
   }
   \sstdiytopic{
      Note
   }{
      \sstitemlist{

         \sstitem
         The attributes which define the transformation to or from topocentric
         frequency should be assigned their correct values before accessing
         this attribute. These potentially include System, Unit, StdOfRest,
         \htmlref{ObsLon}{ObsLon}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec} and \htmlref{RestFreq}{RestFreq}.
      }
   }
}
\sstroutine{
   DefB1950
}{
   Use FK4 B1950 as defaults?
}{
   \sstdescription{
      This attribute is a boolean value which specifies a default equinox
      and reference frame to use when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}
      with a foreign (i.e. non-native) encoding. It is only used if the FITS
      header contains RA and DEC axes but contains no information about the
      reference frame or equinox. If this is the case, then values of FK4 and
      B1950 are assumed if the DefB1950 attribute has a non-zero value and
      ICRS is assumed if DefB1950 is zero. The default value for DefB1950
      depends on the value of the \htmlref{Encoding}{Encoding} attribute: for FITS-WCS encoding
      the default is zero, and for all other encodings it is one.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Digits/Digits(axis)
}{
   Number of digits of precision
}{
   \sstdescription{
      This attribute specifies how many digits of precision are
      required by default when a coordinate value is formatted for a
      \htmlref{Frame}{Frame} axis (e.g. using \htmlref{astFormat}{astFormat}). Its value may be set either
      for a Frame as a whole, or (by subscripting the attribute name
      with the number of an axis) for each axis individually. Any
      value set for an individual axis will over-ride the value for
      the Frame as a whole.

      Note that the Digits value acts only as a means of determining a
      default Format string. Its effects are over-ridden if a Format
      string is set explicitly for an axis. However, if the Format
      attribute specifies the precision using the string \texttt{"} .$*$\texttt{"} , then
      the Digits attribute is used to determine the number of decimal
      places to produce.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default Digits value supplied by the Frame class is 7. If
         a value less than 1 is supplied, then 1 is used instead.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Digits attribute of a FrameSet (or one of its axes) is
         the same as that of its current Frame (as specified by the
         \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         \htmlref{Plot}{Plot}
      }{
         The default Digits value used by the Plot class when drawing
         annotated axis labels is the smallest value which results in all
         adjacent labels being distinct.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The Digits attribute is ignored when a TimeFrame formats a value
         as a date and time string (see the Format attribute).
      }
   }
}
\sstroutine{
   Direction(axis)
}{
   Display axis in conventional direction?
}{
   \sstdescription{
      This attribute is a boolean value which suggests how the axes of
      a \htmlref{Frame}{Frame} should be displayed (e.g.) in graphical output. By
      default, it has the value one, indicating that they should be
      shown in the conventional sense (increasing left to right for an
      abscissa, and bottom to top for an ordinate). If set to zero,
      this attribute indicates that the direction should be reversed,
      as would often be done for an astronomical magnitude or a right
      ascension axis.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default Direction value supplied by the Frame class is 1,
         indicating that all axes should be displayed in the
         conventional direction.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Direction value to
         suggest that certain axes (e.g. right ascension) should be
         plotted in reverse when appropriate.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Direction attribute of a FrameSet axis is the same as
         that of its current Frame (as specified by the \htmlref{Current}{Current}
         attribute).
      }
      \sstsubsection{
         \htmlref{Plot}{Plot}
      }{
         The Direction attribute of the base Frame in a Plot is set to
         indicate the sense of the two graphics axes, as implied by the
         graphics bounding box supplied when the Plot was created.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.

         \sstitem
         The Direction attribute does not directly affect the behaviour
         of the AST library. Instead, it serves as a hint to applications
         programs about the orientation in which they may wish to display
         any data associated with the Frame. Applications are free to
         ignore this hint if they wish.
      }
   }
}
\sstroutine{
   Disco
}{
   PcdMap pincushion/barrel distortion coefficient
}{
   \sstdescription{
      This attribute specifies the pincushion/barrel distortion coefficient
      used by a \htmlref{PcdMap}{PcdMap}. This coefficient is set when the PcdMap is created,
      but may later be modified. If the attribute is cleared, its default
      value is zero, which gives no distortion. For pincushion distortion,
      the value should be positive. For barrel distortion, it should be
      negative.

      Note that the forward transformation of a PcdMap applies the
      distortion specified by this attribute and the inverse
      transformation removes this distortion. If the PcdMap is inverted
      (e.g. using \htmlref{astInvert}{astInvert}), then the forward transformation will
      remove the distortion and the inverse transformation will apply
      it. The distortion itself will still be given by the same value of
      Disco.

      Note, the value of this attribute may changed only if the PcdMap
      has no more than one reference. That is, an error is reported if the
      PcdMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         PcdMap
      }{
         All PcdMaps have this attribute.
      }
   }
}
\sstroutine{
   Domain
}{
   Coordinate system domain
}{
   \sstdescription{
      This attribute contains a string which identifies the physical
      domain of the coordinate system that a \htmlref{Frame}{Frame} describes.

      The Domain attribute also controls how a Frame behaves when it is
      used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target)
      Frame. It does this by specifying the Domain that the target
      Frame should have in order to match the template. If the Domain
      value in the template Frame is set, then only targets with the
      same Domain value will be matched. If the template\texttt{'} s Domain
      value is not set, however, then the target\texttt{'} s Domain will be
      ignored.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default Domain value supplied by the Frame class is an
         empty string.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Domain value to be
         \texttt{"} SKY\texttt{"} .
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The CmpFrame class re-defines the default Domain value to be
         of the form \texttt{"} $<$dom1$>$-$<$dom2$>$\texttt{"} , where $<$dom1$>$ and $<$dom2$>$ are the
         Domains of the two component Frames. If both these Domains are
         blank, then the string \texttt{"} CMP\texttt{"}  is used as the default Domain name.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Domain attribute of a FrameSet is the same as that of its
         current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         The SpecFrame class re-defines the default Domain value to be
         \texttt{"} SPECTRUM\texttt{"} .
      }
      \sstsubsection{
         \htmlref{DSBSpecFrame}{DSBSpecFrame}
      }{
         The DSBSpecFrame class re-defines the default Domain value to be
         \texttt{"} DSBSPECTRUM\texttt{"} .
      }
      \sstsubsection{
         \htmlref{FluxFrame}{FluxFrame}
      }{
         The FluxFrame class re-defines the default Domain value to be
         \texttt{"} FLUX\texttt{"} .
      }
      \sstsubsection{
         \htmlref{SpecFluxFrame}{SpecFluxFrame}
      }{
         The FluxFrame class re-defines the default Domain value to be
         \texttt{"} SPECTRUM-FLUX\texttt{"} .
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class re-defines the default Domain value to be
         \texttt{"} TIME\texttt{"} .
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         All Domain values are converted to upper case and white space
         is removed before use.
      }
   }
}
\sstroutine{
   DrawAxes(axis)
}{
   Draw axes for a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether curves representing coordinate axes should be drawn.
      It takes a separate value for each physical axis of a
      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} DrawAxes(2)=0\texttt{"}
      specifies that no axis should be drawn for the second axis.

      If drawn, these axis lines will pass through any tick marks
      associated with numerical labels drawn to mark values on the
      axes. The location of these tick marks and labels (and hence the
      axis lines) is determined by the Plot\texttt{'} s \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute.

      If the DrawAxes value of a Plot is non-zero (the default), then
      axis lines will be drawn, otherwise they will be omitted.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         \htmlref{Axis}{Axis} lines are drawn independently of any coordinate grid
         lines (see the \htmlref{Grid}{Grid} attribute) so grid lines may be used to
         substitute for axis lines if required.

         \sstitem
         In some circumstances, numerical labels and tick marks are
         drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling}
         attribute).  In this case, the value of the DrawAxes attribute
         is ignored.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} DrawAxes\texttt{"}  instead of
         \texttt{"} DrawAxes(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the DrawAxes(1) value.
      }
   }
}
\sstroutine{
   DrawTitle
}{
   Draw a title for a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether a title is drawn.

      If the DrawTitle value of a \htmlref{Plot}{Plot} is non-zero (the default), then
      the title will be drawn, otherwise it will be omitted.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
      \sstsubsection{
         \htmlref{Plot3D}{Plot3D}
      }{
         The Plot3D class ignores this attributes, assuming a value of
         zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The text used for the title is obtained from the Plot\texttt{'} s \htmlref{Title}{Title}
         attribute.

         \sstitem
         The vertical placement of the title can be controlled using
         the \htmlref{TitleGap}{TitleGap} attribute.
      }
   }
}
\sstroutine{
   Dut1
}{
   The UT1-UTC correction
}{
   \sstdescription{
      This attribute is used when calculating the Local Apparent Sidereal
      Time corresponding to \htmlref{SkyFrame}{SkyFrame}\texttt{'} s \htmlref{Epoch}{Epoch} value (used when converting
      positions to or from the \texttt{"} AzEl\texttt{"}  system). It should be set to the
      difference, in seconds, between the UT1 and UTC timescales at the
      moment in time represented by the SkyFrame\texttt{'} s Epoch attribute. The
      value to use is unpredictable and depends on changes in the earth\texttt{'} s
      rotation speed. Values for UT1-UTC can be obtained from the
      International Earth Rotation and Reference Systems Service
      (IERS) at http://www.iers.org/.

      Currently, the correction is always less than 1 second. This is
      ensured by the occasional introduction of leap seconds into the UTC
      timescale. Therefore no great error will usually result if no value
      is assigned to this attribute (in which case a default value of
      zero is used). However, it is possible that a decision may be taken
      at some time in the future to abandon the introduction of leap
      seconds, in which case the DUT correction could grow to significant
      sizes.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         All Frames have this attribute.
      }
   }
}
\sstroutine{
   Edge(axis)
}{
   Which edges to label in a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      which edges of a \htmlref{Plot}{Plot} are used for displaying numerical and
      descriptive axis labels. It takes a separate value for each
      physical axis of the Plot so that, for instance, the setting
      \texttt{"} Edge(2)=left\texttt{"}  specifies which edge to use to display labels for
      the second axis.

      The values \texttt{"} left\texttt{"} , \texttt{"} top\texttt{"} , \texttt{"} right\texttt{"}  and \texttt{"} bottom\texttt{"}  (or any
      abbreviation) can be supplied for this attribute. The default is
      usually \texttt{"} bottom\texttt{"}  for the first axis and \texttt{"} left\texttt{"}  for the second
      axis. However, if exterior labelling was requested (see the
      \htmlref{Labelling}{Labelling} attribute) but cannot be produced using these default
      Edge values, then the default values will be swapped if this
      enables exterior labelling to be produced.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
      \sstsubsection{
         \htmlref{Plot3D}{Plot3D}
      }{
         The Plot3D class ignores this attributes. Instead it uses its
         own \htmlref{RootCorner}{RootCorner} attribute to determine which edges of the 3D plot
         to label.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         In some circumstances, numerical labels will be drawn along
         internal grid lines instead of at the edges of the plotting area
         (see the Labelling attribute). In this case, the Edge attribute
         only affects the placement of the descriptive labels (these are
         drawn at the edges of the plotting area, rather than along the
         axis lines).
      }
   }
}
\sstroutine{
   Encoding
}{
   System for encoding Objects as FITS headers
}{
   \sstdescription{
      This attribute specifies the encoding system to use when AST
      Objects are stored as FITS header cards in a \htmlref{FitsChan}{FitsChan}. It
      affects the behaviour of the \htmlref{astWrite}{astWrite} and \htmlref{astRead}{astRead} functions when
      they are used to transfer any AST \htmlref{Object}{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
      \htmlref{Channel}{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
      \texttt{"} Encodings Available\texttt{"}  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 \texttt{"} Choice of Default Encoding\texttt{"}
      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.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
   \sstdiytopic{
      Encodings Available
   }{
      The Encoding attribute can take any of the following (case
      insensitive) string values to select the corresponding encoding

      system:

      \sstitemlist{

         \sstitem
         \texttt{"} DSS\texttt{"} : 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 \texttt{"} The DSS Encoding\texttt{"}  below.

         \sstitem
         \texttt{"} FITS-WCS\texttt{"} : 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 \texttt{"} The FITS-WCS Encoding\texttt{"}  below.

         \sstitem
         \texttt{"} FITS-PC\texttt{"} : 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 \texttt{"} FITS-WCS\texttt{"}  encoding (which uses CDi\_j or PCi\_j keywords to
         describe the scale and rotation) should be used in preference to
         \texttt{"} FITS-PC\texttt{"} .

         \sstitem
         \texttt{"} FITS-IRAF\texttt{"} : Encodes coordinate system information in FITS
         header cards using the conventions described in the document
         \texttt{"} World Coordinate Systems Representations Within the FITS
         Format\texttt{"}  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.

         \sstitem
         \texttt{"} FITS-AIPS\texttt{"} : 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.

         \sstitem
         \texttt{"} FITS-AIPS$+$$+$\texttt{"} : 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.

         \sstitem
         \texttt{"} FITS-CLASS\texttt{"} : 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 \texttt{"} CLASS FITS format\texttt{"}  at
         http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.

         \sstitem
         \texttt{"} NATIVE\texttt{"} : 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 \texttt{"} The NATIVE Encoding\texttt{"}  below.
      }
   }
   \sstdiytopic{
      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:

      \sstitemlist{

         \sstitem
         If the FitsChan contains any keywords beginning with the
         string \texttt{"} BEGAST\texttt{"} , then NATIVE encoding is used,

         \sstitem
         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. \texttt{"} VELO-LSR\texttt{"} ), or \texttt{"} VLSR\texttt{"} .

         \sstitem
         Otherwise, if the FitsChan contains a CTYPE keyword which
         represents a spectral axis using the conventions of the AIPS and
         AIPS$+$$+$ projects (e.g. \texttt{"} FELO-LSR\texttt{"} , 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.

         \sstitem
         Otherwise, if the FitsChan contains a keyword of the form
         \texttt{"} PCiiijjj\texttt{"} , where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then
         FITS-PC encoding is used,

         \sstitem
         Otherwise, if the FitsChan contains a keyword of the form
         \texttt{"} CDiiijjj\texttt{"} , where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then
         FITS-IRAF encoding is used,

         \sstitem
         Otherwise, if the FitsChan contains a keyword of the form
         \texttt{"} CDi\_j\texttt{"} , and at least one of RADECSYS, PROJPi, or CjVALi
         where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then FITS-IRAF encoding is
         used.

         \sstitem
         Otherwise, if the FitsChan contains any keywords of the form
         PROJPi, CjVALi or RADECSYS, where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits,
         then FITS-PC encoding is used.

         \sstitem
         Otherwise, if the FitsChan contains a keyword of the form
         CROTAi, where \texttt{"} i\texttt{"}  is a single digit, then FITS-AIPS encoding is
         used.

         \sstitem
         Otherwise, if the FitsChan contains a keyword of the form
         CRVALi, where \texttt{"} i\texttt{"}  is a single digit, then FITS-WCS encoding is
         used.

         \sstitem
         Otherwise, if the FitsChan contains the \texttt{"} PLTRAH\texttt{"}  keyword, then
         DSS encoding is used,

         \sstitem
         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.
   }
   \sstdiytopic{
      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 \htmlref{FrameSet}{FrameSet} which conforms to the STScI/DSS coordinate system
      model (this means the \htmlref{Mapping}{Mapping} which relates its base and current
      Frames must include either a \htmlref{DssMap}{DssMap} or a \htmlref{WcsMap}{WcsMap} with type
      AST\_\_TAN or AST\_\_TPN).

      When reading a DSS encoded Object (using astRead), the FitsChan
      concerned must initially be positioned at the first card (its
      \htmlref{Card}{Card} attribute must equal 1) and the result of the read, if
      successful, will always be a pointer to a FrameSet. The base
      \htmlref{Frame}{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 \texttt{"} end-of-file\texttt{"} . 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 \htmlref{SkyFrame}{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.
   }
   \sstdiytopic{
      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 \texttt{"} world coordinate systems\texttt{"} .
      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
      \texttt{"} alternate axis descriptions\texttt{"} ). Details of the use made by this
      Encoding of the conventions described in the FITS-WCS papers are
      given in the appendix \texttt{"} FITS-WCS Coverage\texttt{"}  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 \texttt{"} CDi\_j\texttt{"}  keywords, or \texttt{"} PCi\_j\texttt{"}  together
      with \texttt{"} CDELTi\texttt{"}  keywords. When writing a FrameSet to a FitsChan, the
      the value of the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan determines
      which system is used.

      In addition, this encoding supports the \texttt{"} TAN with polynomial correction
      terms\texttt{"}  projection which was included in a draft of the FITS-WCS paper,
      but was not present in the final version. A \texttt{"} TAN with polynomial
      correction terms\texttt{"}  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 \texttt{"} -TAN\texttt{"}  code results in an AST\_\_TPN projection if there are
      any projection parameters (given by the \htmlref{PVi\_m}{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 \texttt{"} -TAN\texttt{"}  code, but the projection
      parameters are stored in keywords with names \texttt{"} QVi\_m\texttt{"} , instead of the
      usual \texttt{"} PVi\_m\texttt{"} . 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
      \texttt{"} AZ--\texttt{"}  and \texttt{"} EL--\texttt{"}  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 \htmlref{SkyRefIs}{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 \texttt{"} OFLN\texttt{"}  and
      \texttt{"} OFLT\texttt{"}  as the axis codes in the CTYPE keywords. The other will
      describe absolute coordinates as specified by the \htmlref{System}{System} attribute
      of the SkyFrame, using the usual CTYPE codes (\texttt{"} RA--\texttt{"} /\texttt{"} DEC-\texttt{"} , 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
      \texttt{"} end-of-file\texttt{"} . 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.
   }
   \sstdiytopic{
      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:

      \sstitemlist{

         \sstitem
         The only celestial coordinate systems that may be represented
         are equatorial, galactic and ecliptic,

         \sstitem
         Sky projections can be represented only if any associated
         projection parameters are set to their default values.

         \sstitem
         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
      \texttt{"} FITS-IRAF\texttt{"}  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 \texttt{"} CDi\_j\texttt{"} , where
      \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits. The alternative form \texttt{"} CDiiijjj\texttt{"} , which
      is also in use, is recognised when reading an Object, but is never
      written.

      In addition, the experimental IRAF \texttt{"} ZPX\texttt{"}  and \texttt{"} TNX\texttt{"}  sky projections will
      be accepted when reading, but will never be written (the corresponding
      FITS \texttt{"} ZPN\texttt{"}  or \texttt{"} distorted TAN\texttt{"}  projection being used instead). However,
      there are restrictions on the use of these experimental projections.
      For \texttt{"} ZPX\texttt{"} , longitude and latitude correction surfaces (appearing as
      \texttt{"} lngcor\texttt{"}  or \texttt{"} latcor\texttt{"}  terms in the IRAF-specific \texttt{"} WAT\texttt{"}  keywords) are
      not supported. For \texttt{"} TNX\texttt{"}  projections, only cubic surfaces encoded as
      simple polynomials with \texttt{"} half cross-terms\texttt{"}  are supported. If an
      un-usable \texttt{"} TNX\texttt{"}  or \texttt{"} ZPX\texttt{"}  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 \texttt{"} ASTWARN\texttt{"} .

      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.
   }
   \sstdiytopic{
      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.
   }
   \sstdiytopic{
      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:

      \sstitemlist{

         \sstitem
         The only celestial coordinate systems that may be represented
         are equatorial, galactic and ecliptic,

         \sstitem
         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.

         \sstitem
         Sky projections can be represented only if any associated
         projection parameters are set to their default values.

         \sstitem
         The AIT, SFL and MER projections can only be written if the CRVAL
         keywords are zero for both longitude and latitude axes.

         \sstitem
         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.

         \sstitem
         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.
      }
   }
   \sstdiytopic{
      The FITS-AIPS$+$$+$ Encoding
   }{
      The FITS-AIPS$+$$+$ encoding is based on the FITS-AIPS encoding, but
      includes some features of the FITS-IRAF and FITS-PC encodings.
      Specifically, any celestial projections supported by FITS-PC may be
      used, including those which require parameterisation, and the axis
      rotation and scaling may be specified using CDi\_j keywords. When
      writing a FITS header, rotation will be specified using CROTA/CDELT
      keywords if possible, otherwise CDi\_j keywords will be used instead.
   }
   \sstdiytopic{
      The FITS-CLASS Encoding
   }{
      The FITS-CLASS encoding uses the conventions of the CLASS project.
      These are described in the section \texttt{"} Developer Manual\texttt{"} /\texttt{"} CLASS FITS

      Format\texttt{"}  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:

      \sstitemlist{

         \sstitem
         When a \htmlref{SpecFrame}{SpecFrame} is created by reading a FITS-CLASS header, the
           attributes describing the observer\texttt{'} s position (\htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon} and
           \htmlref{ObsAlt}{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.

         \sstitem
         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.

         \sstitem
         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.

         \sstitem
         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.

         \sstitem
         No rotation of the celestial axes is allowed, unless the spatial
           axes are degenerate (i.e. cover only a single pixel).

         \sstitem
         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.

         \sstitem
         The source velocity must be defined. In other words, the SpecFrame
           attributes \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} must have been assigned values.

         \sstitem
         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.
   }
   \sstdiytopic{
      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
      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 \htmlref{Class}{Class} or \htmlref{ID}{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 \texttt{"} end-of-file\texttt{"} .

      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.
   }
}
\sstroutine{
   Epoch
}{
   Epoch of observation
}{
   \sstdescription{
      This attribute is used to qualify the coordinate systems described by
      a \htmlref{Frame}{Frame}, by giving the moment in time when the coordinates are known
      to be correct. Often, this will be the date of observation, and is
      important in cases where coordinates systems move with respect to each
      other over the course of time.

      The Epoch attribute is stored as a Modified Julian Date, but
      when setting its value it may be given in a variety of
      formats. See the \texttt{"} Input Formats\texttt{"}  section (below) for details.
      Strictly, the Epoch value should be supplied in the TDB timescale,
      but for some purposes (for instance, for converting sky positions
      between different types of equatorial system) the timescale is not
      significant, and UTC may be used.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute. The basic Frame class provides
         a default of J2000.0 (Julian) but makes no use of the Epoch value.
         This is because the Frame class does not distinguish between
         different Cartesian coordinate systems (see the \htmlref{System}{System} attribute).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The default Epoch value for a CmpFrame is selected as follows;
         if the Epoch attribute has been set in the first component Frame
         then the Epoch value from the first component Frame is used as
         the default for the CmpFrame. Otherwise, if the Epoch attribute has
         been set in the second component Frame then the Epoch value from the
         second component Frame is used as the default for the CmpFrame.
         Otherwise, the default Epoch value from the first component
         Frame is used as the default for the CmpFrame. When the Epoch
         attribute of a CmpFrame is set or cleared, it is also set or
         cleared in the two component Frames.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Epoch attribute of a FrameSet is the same as that of its current
         Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The coordinates of sources within a SkyFrame can changed with time
         for various reasons, including: (i) changing aberration of light
         caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion
         around the Sun), (ii) changing gravitational deflection by the Sun
         due to changes in the observer\texttt{'} s position with time, (iii) fictitious
         motion due to rotation of non-inertial coordinate systems (e.g. the
         old FK4 system), and (iv) proper motion of the source itself (although
         this last effect is not handled by the SkyFrame class because it
         affects individual sources rather than the coordinate system as
         a whole).

         The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the
         old FK4-based coordinate systems (see the System attribute) and
         J2000.0 (Julian) for all others.

         Care must be taken to distinguish the Epoch value, which relates to
         motion (or apparent motion) of the source, from the superficially
         similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate
         system which is itself in motion in a (notionally) predictable way
         as a result of being referred to a slowly moving reference plane
         (e.g. the equator).

         See the description of the System attribute for details of which
         qualifying attributes apply to each celestial coordinate system.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         A TimeFrame describes a general time axis and so cannot be completely
         characterised by a single Epoch value. For this reason the TimeFrame
         class makes no use of the Epoch attribute. However, user code can
         still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"}
         time spanned by the TimeFrame. The default Epoch value for a TimeFrame
         will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s
         \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin,
         then the default Epoch value is J2000.0.
      }
   }
   \sstdiytopic{
      Input Formats
   }{
      The formats accepted when setting an Epoch value are listed
      below. They are all case-insensitive and are generally tolerant
      of extra white space and alternative field delimiters:

      \sstitemlist{

         \sstitem
         Besselian Epoch: Expressed in decimal years, with or without
         decimal places (\texttt{"} B1950\texttt{"}  or \texttt{"} B1976.13\texttt{"}  for example).

         \sstitem
         Julian Epoch: Expressed in decimal years, with or without
         decimal places (\texttt{"} J2000\texttt{"}  or \texttt{"} J2100.9\texttt{"}  for example).

         \sstitem
         Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"}
         for example).  Such values are interpreted as a Besselian epoch
         (see above) if less than 1984.0 and as a Julian epoch otherwise.

         \sstitem
         Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"}  for
         example).

         \sstitem
         Modified Julian Date: With or without decimal places
         (\texttt{"} MJD 54321.4\texttt{"}  for example).

         \sstitem
         Gregorian Calendar Date: With the month expressed either as an
         integer or a 3-character abbreviation, and with optional decimal
         places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"}  or
         \texttt{"} 1996-Oct-2.6\texttt{"}  for example). If no fractional part of a day is
         given, the time refers to the start of the day (zero hours).

         \sstitem
         Gregorian Date and Time: Any calendar date (as above) but with
         a fraction of a day expressed as hours, minutes and seconds
         (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"}  for example). The date and time can be
         separated by a space or by a \texttt{"} T\texttt{"}  (as used by ISO8601 format).
      }
   }
   \sstdiytopic{
      Output Format
   }{
      When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"}
      format described under \texttt{"} Input Formats\texttt{"} . This is a value in
      decimal years which will be a Besselian epoch if less than
      1984.0 and a Julian epoch otherwise.  By omitting any character
      prefix, this format allows the Epoch value to be obtained as
      either a character string or a floating point value.
   }
}
\sstroutine{
   Equinox
}{
   Epoch of the mean equinox
}{
   \sstdescription{
      This attribute is used to qualify those celestial coordinate
      systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on
      the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun)
      and/or the Earth\texttt{'} s equator.

      Both of these planes are in motion and their positions are
      difficult to specify precisely. In practice, therefore, a model
      ecliptic and/or equator are used instead. These, together with
      the point on the sky that defines the coordinate origin (the
      intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move
      with time according to some model which removes the more rapid
      fluctuations. The SkyFrame class supports both the FK4 and
      FK5 models.

      The position of a fixed source expressed in any of these
      coordinate systems will appear to change with time due to
      movement of the coordinate system itself (rather than motion of
      the source).  Such coordinate systems must therefore be
      qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"}
      or \texttt{"} equinox\texttt{"}  for short) which allows the position of the model
      coordinate system on the sky to be determined. This is the role
      of the Equinox attribute.

      The Equinox attribute is stored as a Modified Julian Date, but
      when setting or getting its value you may use the same formats
      as for the \htmlref{Epoch}{Epoch} attribute (q.v.).

      The default Equinox value is B1950.0 (Besselian) for the old
      FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and
      J2000.0 (Julian) for all others.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Care must be taken to distinguish the Equinox value, which
         relates to the definition of a time-dependent coordinate system
         (based on solar system reference planes which are in motion),
         from the superficially similar Epoch value. The latter is used
         to qualify coordinate systems where the positions of sources
         change with time (or appear to do so) for a variety of other
         reasons, such as aberration of light caused by the observer\texttt{'} s
         motion, etc.

         \sstitem
         See the description of the System attribute for details of
         which qualifying attributes apply to each celestial coordinate
         system.
      }
   }
}
\sstroutine{
   Escape
}{
   Allow changes of character attributes within strings?
}{
   \sstdescription{
      This attribute controls the appearance of text strings and numerical
      labels drawn by the \htmlref{astGrid}{astGrid} and (for the \htmlref{Plot}{Plot} class) \htmlref{astText}{astText} functions,
      by determining if any escape sequences contained within the strings
      should be used to control the appearance of the text, or should
      be printed literally. Note, the \htmlref{Plot3D}{Plot3D} class only interprets escape
      sequences within the
      astGrid function.

      If the Escape value of a Plot is one (the default), then any
      escape sequences in text strings produce the effects described
      below when printed. Otherwise, they are printed literally.

      See also the \htmlref{astEscapes}{astEscapes} function.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstdiytopic{
      Escape Sequences
   }{
      Escape sequences are introduced into the text string by a percent
      \texttt{"} \%\texttt{"}  character. Any unrecognised, illegal or incomplete escape sequences
      are printed literally. The following escape sequences are
      currently recognised (\texttt{"} ...\texttt{"}  represents a string of one or more
      decimal digits):

        \%\%      - Print a literal \texttt{"} \%\texttt{"}  character.

        \%$\wedge$...$+$  - Draw subsequent characters as super-scripts. The digits
                  \texttt{"} ...\texttt{"}  give the distance from the base-line of \texttt{"} normal\texttt{"}
                  text to the base-line of the super-script text, scaled
                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
                  \texttt{"} normal\texttt{"}  text.
        \%$\wedge$$+$     - Draw subsequent characters with the normal base-line.

        \%v...$+$  - Draw subsequent characters as sub-scripts. The digits
                  \texttt{"} ...\texttt{"}  give the distance from the base-line of \texttt{"} normal\texttt{"}
                  text to the base-line of the sub-script text, scaled
                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
                  \texttt{"} normal\texttt{"}  text.

        \%v$+$     - Draw subsequent characters with the normal base-line
                  (equivalent to \%$\wedge$$+$).

        \%$>$...$+$  - Leave a gap before drawing subsequent characters.
                  The digits \texttt{"} ...\texttt{"}  give the size of the gap, scaled
                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
                  \texttt{"} normal\texttt{"}  text.

        \%$<$...$+$  - Move backwards before drawing subsequent characters.
                  The digits \texttt{"} ...\texttt{"}  give the size of the movement, scaled
                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
                  \texttt{"} normal\texttt{"}  text.

        \%s...$+$  - Change the Size attribute for subsequent characters. The
                  digits \texttt{"} ...\texttt{"}  give the new Size as a fraction of the
                  \texttt{"} normal\texttt{"}  Size, scaled so that a value of \texttt{"} 100\texttt{"}  corresponds
                  to 1.0;

        \%s$+$     - Reset the Size attribute to its \texttt{"} normal\texttt{"}  value.

        \%w...$+$  - Change the Width attribute for subsequent characters. The
                  digits \texttt{"} ...\texttt{"}  give the new width as a fraction of the
                  \texttt{"} normal\texttt{"}  Width, scaled so that a value of \texttt{"} 100\texttt{"}  corresponds
                  to 1.0;

        \%w$+$     - Reset the Size attribute to its \texttt{"} normal\texttt{"}  value.

        \%f...$+$  - Change the Font attribute for subsequent characters. The
                  digits \texttt{"} ...\texttt{"}  give the new Font value.

        \%f$+$     - Reset the Font attribute to its \texttt{"} normal\texttt{"}  value.

        \%c...$+$  - Change the Colour attribute for subsequent characters. The
                  digits \texttt{"} ...\texttt{"}  give the new Colour value.

        \%c$+$     - Reset the Colour attribute to its \texttt{"} normal\texttt{"}  value.

        \%t...$+$  - Change the Style attribute for subsequent characters. The
                  digits \texttt{"} ...\texttt{"}  give the new Style value.

        \%t$+$     - Reset the Style attribute to its \texttt{"} normal\texttt{"}  value.

        \%h$+$     - Remember the current horizontal position (see \texttt{"} \%g$+$\texttt{"} )

        \%g$+$     - Go to the horizontal position of the previous \texttt{"} \%h$+$\texttt{"}  (if any).

        \%-      - Push the current graphics attribute values onto the top of
                  the stack (see \texttt{"} \%$+$\texttt{"} ).

        \%$+$      - Pop attributes values of the top the stack (see \texttt{"} \%-\texttt{"} ). If
                  the stack is empty, \texttt{"} normal\texttt{"}  attribute values are restored.
   }
}
\sstroutine{
   FillFactor
}{
   Fraction of the Region which is of interest
}{
   \sstdescription{
      This attribute indicates the fraction of the \htmlref{Region}{Region} which is of
      interest. AST does not use this attribute internally for any purpose.
      Typically, it could be used to indicate the fraction of the Region for
      which data is available.

      The supplied value must be in the range 0.0 to 1.0, and the default
      value is 1.0 (except as noted below).
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpRegion}{CmpRegion}
      }{
         The default FillFactor for a CmpRegion is the FillFactor of its
         first component Region.
      }
      \sstsubsection{
         \htmlref{Prism}{Prism}
      }{
         The default FillFactor for a Prism is the product of the
         FillFactors of its two component Regions.
      }
      \sstsubsection{
         \htmlref{Stc}{Stc}
      }{
         The default FillFactor for an Stc is the FillFactor of its
         encapsulated Region.
      }
   }
}
\sstroutine{
   FitsAxisOrder
}{
   Frame title
}{
   \sstdescription{
      This attribute specifies the order for the WCS axes in any new
      FITS-WCS headers created using the
      \htmlref{astWrite}{astWrite}
      method.

      The value of the FitsAxisOrder attribute can be either \texttt{"} $<$auto$>$\texttt{"}
      (the default value), \texttt{"} $<$copy$>$\texttt{"}  or a space-separated list of axis
      symbols:

      \texttt{"} $<$auto$>$\texttt{"} : causes the WCS axis order to be chosen automatically so that
      the i\texttt{'} th WCS axis in the new FITS header is the WCS axis which is
      more nearly parallel to the i\texttt{'} th pixel axis.

      \texttt{"} $<$copy$>$\texttt{"} : causes the WCS axis order to be set so that the i\texttt{'} th WCS
      axis in the new FITS header is the i\texttt{'} th WCS axis in the current
      \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} being written out to the header.

      \texttt{"} Sym1 Sym2...\texttt{"} : the space-separated list is seached in turn for
      the Symbol attribute of each axis in the current Frame of the
      FrameSet. The order in which these Symbols occur within the
      space-separated list defines the order of the WCS axes in the
      new FITS header. An error is reported if Symbol for a current
      Frame axis is not present in the supplied list. However, no error
      is reported if the list contains extra words that do not correspond
      to the Symbol of any current Frame axis.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   FitsDigits
}{
   Digits of precision for floating point FITS values
}{
   \sstdescription{
      This attribute gives the number of significant decimal digits to
      use when formatting floating point values for inclusion in the
      FITS header cards within a \htmlref{FitsChan}{FitsChan}.

      By default, a positive value is used which results in no loss of
      information, assuming that the value\texttt{'} s precision is double.
      Usually, this causes no problems.

      However, to adhere strictly to the recommendations of the FITS
      standard, the width of the formatted value (including sign,
      decimal point and exponent) ought not to be more than 20
      characters. If you are concerned about this, you should set
      FitsDigits to a negative value, such as -15. In this case, the
      absolute value ($+$15) indicates the maximum number of significant
      digits to use, but the actual number used may be fewer than this
      to ensure that the FITS recommendations are satisfied. When
      using this approach, the resulting number of significant digits
      may depend on the value being formatted and on the presence of
      any sign, decimal point or exponent.

      The value of this attribute is effective when FITS header cards
      are output, either using
      \htmlref{astFindFits}{astFindFits} or by the action of the FitsChan\texttt{'} s sink function
      when it is finally deleted.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Font(element)
}{
   Character font for a Plot element
}{
   \sstdescription{
      This attribute determines the character font index used when
      drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It
      takes a separate value for each graphical element so that, for
      instance, the setting \texttt{"} Font(title)=2\texttt{"}  causes the Plot title to
      be drawn using font number 2.

      The range of integer font indices available and the appearance
      of the resulting text is determined by the underlying graphics
      system.  The default behaviour is for all graphical elements to
      be drawn using the default font supplied by this graphics
      system.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of the graphical elements available, see the
         description of the Plot class.

         \sstitem
         If no graphical element is specified, (e.g. \texttt{"} Font\texttt{"}  instead
         of \texttt{"} Font(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
         affect the attribute value of all graphical elements, while a
         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Font(TextLab)
         value.
      }
   }
}
\sstroutine{
   Format(axis)
}{
   Format specification for axis values
}{
   \sstdescription{
      This attribute specifies the format to be used when displaying
      coordinate values associated with a particular \htmlref{Frame}{Frame} axis
      (i.e. to convert values from binary to character form). It is
      interpreted by the \htmlref{astFormat}{astFormat} function and determines the
      formatting which it applies.

      If no Format value is set for a Frame axis, a default value is
      supplied instead. This is based on the value of the Digits, or
      Digits(axis), attribute and is chosen so that it displays the
      requested number of digits of precision.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The Frame class interprets this attribute as a format
         specification string to be passed to the C \texttt{"} printf\texttt{"}  function
         (e.g. \texttt{"} \%1.7G\texttt{"} ) in order to format a single coordinate value
         (supplied as a double precision number).

         When supplying a value for this attribute, beware that the
         \texttt{"} \%\texttt{"}  character may be interpreted directly as a format
         specification by some printf-like functions (such as
         \htmlref{astSet}{astSet}). You may need to double it (i.e. use \texttt{"} \%\%\texttt{"} ) to avoid
         this.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the syntax and default value of
         the Format string to allow the formatting of sexagesimal
         values as appropriate for the particular celestial coordinate
         system being represented. The syntax of SkyFrame Format
         strings is described (below) in the \texttt{"} SkyFrame Formats\texttt{"}
         section.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Format attribute of a FrameSet axis is the same as that
         of its current Frame (as specified by the \htmlref{Current}{Current}
         attribute). Note that the syntax of the Format string is also
         determined by the current Frame.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class extends the syntax of the Format string to
         allow the formatting of TimeFrame axis values as Gregorian calendar
         dates and times. The syntax of TimeFrame Format strings is described
         (below) in the \texttt{"} TimeFrame Formats\texttt{"}  section.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
   \sstdiytopic{
      SkyFrame Formats
   }{
      The Format string supplied for a SkyFrame should contain zero or
      more of the following characters. These may occur in any order,
      but the following is recommended for clarity:

      \sstitemlist{

         \sstitem
         \texttt{"} $+$\texttt{"} : Indicates that a plus sign should be prefixed to positive
         values. By default, no plus sign is used.

         \sstitem
         \texttt{"} z\texttt{"} : Indicates that leading zeros should be prefixed to the
         value so that the first field is of constant width, as would be
         required in a fixed-width table (leading zeros are always
         prefixed to any fields that follow). By default, no leading
         zeros are added.

         \sstitem
         \texttt{"} i\texttt{"} : Use the standard ISO field separator (a colon) between
         fields. This is the default behaviour.

         \sstitem
         \texttt{"} b\texttt{"} : Use a blank to separate fields.

         \sstitem
         \texttt{"} l\texttt{"} : Use a letter (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"}  as appropriate) to
         separate fields.

         \sstitem
         \texttt{"} g\texttt{"} : Use a letter and symbols to separate fields (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"} ,
         etc, as appropriate), but include escape sequences in the formatted
         value so that the \htmlref{Plot}{Plot} class will draw the separators as small
         super-scripts.
         The default escape sequences are optimised for the pgplot graphics
         package, but new escape sequences may be specified using function
         astSetSkyDelim.

         \sstitem
         \texttt{"} d\texttt{"} : Include a degrees field. Expressing the angle purely in
         degrees is also the default if none of \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} , \texttt{"} s\texttt{"}  or \texttt{"} t\texttt{"}  are
         given.

         \sstitem
         \texttt{"} h\texttt{"} : Express the angle as a time and include an hours field
         (where 24 hours correspond to 360 degrees). Expressing the angle
         purely in hours is also the default if \texttt{"} t\texttt{"}  is given without
         either \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"} .

         \sstitem
         \texttt{"} m\texttt{"} : Include a minutes field. By default this is not included.

         \sstitem
         \texttt{"} s\texttt{"} : Include a seconds field. By default this is not included.
         This request is ignored if \texttt{"} d\texttt{"}  or \texttt{"} h\texttt{"}  is given, unless a minutes
         field is also included.

         \sstitem
         \texttt{"} t\texttt{"} : Express the angle as a time (where 24 hours correspond to
         360 degrees). This option is ignored if either \texttt{"} d\texttt{"}  or \texttt{"} h\texttt{"}  is
         given and is intended for use where the value is to be expressed
         purely in minutes and/or seconds of time (with no hours
         field). If \texttt{"} t\texttt{"}  is given without \texttt{"} d\texttt{"} , \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"}  being
         present, then it is equivalent to \texttt{"} h\texttt{"} .

         \sstitem
         \texttt{"} .\texttt{"} : Indicates that decimal places are to be given for the
         final field in the formatted string (whichever field this
         is). The \texttt{"} .\texttt{"}  should be followed immediately by an unsigned
         integer which gives the number of decimal places required, or by an
         asterisk. If an asterisk is supplied, a default number of decimal
         places is used which is based on the value of the Digits
         attribute.

      }
      All of the above format specifiers are case-insensitive. If
      several characters make conflicting requests (e.g. if both \texttt{"} i\texttt{"}
      and \texttt{"} b\texttt{"}  appear), then the character occurring last takes
      precedence, except that \texttt{"} d\texttt{"}  and \texttt{"} h\texttt{"}  always override \texttt{"} t\texttt{"} .

      If the format string starts with a percentage sign (\%), then the
      whole format string is assumed to conform to the syntax defined by
      the Frame class, and the axis values is formated as a decimal
      radians value.
   }
   \sstdiytopic{
      TimeFrame Formats
   }{
      The Format string supplied for a TimeFrame should either use the
      syntax defined by the base Frame class (i.e. a C \texttt{"} printf\texttt{"}  format
      string), or the extended \texttt{"} iso\texttt{"}  syntax described below (the default
      value is inherited from the Frame class):

      \sstitemlist{

         \sstitem
         C \texttt{"} printf\texttt{"}  syntax: If the Format string is a C \texttt{"} printf\texttt{"}  format
         description such as \texttt{"} \%1.7G\texttt{"} , the TimeFrame axis value will be
         formatted without change as a floating point value using this format.
         The formatted string will thus represent an offset from the zero point
         specified by the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute, measured in
         units given by the TimeFrame\texttt{'} s Unit attribute.

         \sstitem
         \texttt{"} iso\texttt{"}  syntax: This is used to format a TimeFrame axis value as a
         Gregorian date followed by an optional time of day. If the Format
         value commences with the string \texttt{"} iso\texttt{"}  then the TimeFrame axis value
         will be converted to an absolute MJD, including the addition of the
         current TimeOrigin value, and then formatted as a Gregorian date
         using the format \texttt{"} yyyy-mm-dd\texttt{"} . Optionally, the Format value may
         include an integer precision following the \texttt{"} iso\texttt{"}  specification (e.g.
         \texttt{"} iso.2\texttt{"} ), in which case the time of day will be appended to the
         formatted date (if no time of day is included, the date field is
         rounded to the nearest day). The integer value in the Format string
         indicates the number of decimal places to use in the seconds field. For
         instance, a Format value of \texttt{"} iso.0\texttt{"}  produces a time of day of the form
         \texttt{"} hh:mm:ss\texttt{"} , and a Format value of \texttt{"} iso.2\texttt{"}  produces a time of day of the
         form \texttt{"} hh:mm:ss.ss\texttt{"} . The date and time fields will be separated by a
         space unless \texttt{'} T\texttt{'}  is appended to the end of string, in which case
         the letter T (upper case) will be used as the separator. The value of
         the Digits attribute is ignored when using this \texttt{"} iso\texttt{"}  format.
      }
   }
}
\sstroutine{
   Full
}{
   Set level of output detail
}{
   \sstdescription{
      This attribute is a three-state flag and takes values of -1, 0
      or $+$1.  It controls the amount of information included in the
      output generated by a \htmlref{Channel}{Channel}.

      If Full is zero, then a modest amount of
      non-essential but useful information will be included in the
      output. If Full is negative, all non-essential information will
      be suppressed to minimise the amount of output, while if it is
      positive, the output will include the maximum amount of detailed
      information about the \htmlref{Object}{Object} being written.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         The default value is zero for a normal Channel.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         The default value is zero for a FitsChan.
      }
      \sstsubsection{
         \htmlref{XmlChan}{XmlChan}
      }{
         The default value is -1 for an XmlChan.
      }
      \sstsubsection{
         \htmlref{StcsChan}{StcsChan}
      }{
         The default value is zero for an StcsChan. Set a positive value
         to cause default values to be included in STC-S descriptions.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         All positive values supplied for this attribute are converted
         to $+$1 and all negative values are converted to -1.
      }
   }
}
\sstroutine{
   Gap(axis)
}{
   Interval between linearly spaced major axis values of a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the linear interval between the \texttt{"} major\texttt{"}  axis values of a \htmlref{Plot}{Plot}, at
      which (for example) major tick marks are drawn. It takes a separate
      value for each physical axis of the Plot so that, for instance,
      the setting \texttt{"} Gap(2)=3.0\texttt{"}  specifies the difference between adjacent major
      values along the second axis. The Gap attribute is only used when
      the LogTicks attribute indicates that the spacing between major axis
      values is to be linear. If major axis values are logarithmically spaced
      then the gap is specified using attribute LogGap.

      The Gap value supplied will usually be rounded to the nearest
      \texttt{"} nice\texttt{"}  value, suitable (e.g.) for generating axis labels, before
      use. To avoid this \texttt{"} nicing\texttt{"}  you should set an explicit format
      for the axis using the \htmlref{Format(axis)}{Format(axis)} or \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}
      attribute. The default behaviour is for the Plot to generate its
      own Gap value when required, based on the range of axis values
      to be represented.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Gap value should use the same units as are used internally
         for storing coordinate values on the corresponding axis. For
         example, with a celestial coordinate system, the Gap value
         should be in radians, not hours or degrees.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} Gap\texttt{"}  instead of \texttt{"} Gap(2)\texttt{"} ),
         then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the attribute
         value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation
         will use just the Gap(1) value.
      }
   }
}
\sstroutine{
   Grf
}{
   Use Grf functions registered through astGrfSet?
}{
   \sstdescription{
      This attribute selects the functions which are used to draw graphics by
      the \htmlref{Plot}{Plot} class. If it is zero, then the functions in the graphics
      interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script).
      Otherwise, functions registered using \htmlref{astGrfSet}{astGrfSet} are used. In this
      case, if a function is needed which has not been registered,
      then the function in the graphics interface selected at link-time is
      used.

      The default is to use the graphics interface
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
      \sstsubsection{
         \htmlref{Plot3D}{Plot3D}
      }{
         The Plot3D class ignores this attributes, assuming a value of
         zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The value of this attribute is not saved when the Plot is written
         out through a \htmlref{Channel}{Channel} to an external data store. On re-loading such
         a Plot using \htmlref{astRead}{astRead}, the attribute will be cleared, resulting in the
         graphics interface selected at link-time being used.
      }
   }
}
\sstroutine{
   Grid
}{
   Draw grid lines for a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether grid lines (a grid of curves marking the \texttt{"} major\texttt{"}  values
      on each axis) are drawn across the plotting area.

      If the Grid value of a \htmlref{Plot}{Plot} is non-zero, then grid lines will be
      drawn. Otherwise, short tick marks on the axes are used to mark
      the major axis values.  The default behaviour is to use tick
      marks if the entire plotting area is filled by valid physical
      coordinates, but to draw grid lines otherwise.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The spacing between major axis values, which determines the
         spacing of grid lines, may be set using the \htmlref{Gap(axis)}{Gap(axis)} attribute.
      }
   }
}
\sstroutine{
   GrismAlpha
}{
   The angle of incidence of the incoming light on the grating surface
}{
   \sstdescription{
      This attribute holds the angle between the incoming light and the
      normal to the grating surface, in radians. The default value is 0.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismEps
}{
   The angle between the normal and the dispersion plane
}{
   \sstdescription{
      This attribute holds the angle (in radians) between the normal to
      the grating or exit prism face, and the dispersion plane. The
      dispersion plane is the plane spanned by the incoming and outgoing
      ray. The default value is 0.0.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismG
}{
   The grating ruling density
}{
   \sstdescription{
      This attribute holds the number of grating rulings per unit length.
      The unit of length used should be consistent with the units used
      for attributes \htmlref{GrismWaveR}{GrismWaveR} and \htmlref{GrismNRP}{GrismNRP}. The default value is 0.0.
      (the appropriate value for a pure prism disperser with no grating).

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismM
}{
   The interference order
}{
   \sstdescription{
      This attribute holds the interference order being considered.
      The default value is 0.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismNR
}{
   The refractive index at the reference wavelength
}{
   \sstdescription{
      This attribute holds refractive index of the grism material at the
      reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default
      value is 1.0.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismNRP
}{
   The rate of change of refractive index with wavelength
}{
   \sstdescription{
      This attribute holds the rate of change of the refractive index of the
      grism material with respect to wavelength at the reference wavelength
      (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 0.0 (the
      appropriate value for a pure grating disperser with no prism). The
      units of this attribute should be consistent with those of attributes
      GrismWaveR and \htmlref{GrismG}{GrismG}.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismTheta
}{
   Angle between normal to detector plane and reference ray
}{
   \sstdescription{
      This attribute gives the angle of incidence of light of the
      reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}) onto the
      detector. Specifically, it holds the angle (in radians) between
      the normal to the detector plane and an incident ray at the reference
      wavelength. The default value is 0.0.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   GrismWaveR
}{
   The reference wavelength
}{
   \sstdescription{
      This attribute holds reference wavelength. The default value is
      5000 (Angstrom). The units of this attribute should be consistent with
      those of attributes \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG}.

      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
      has no more than one reference. That is, an error is reported if the
      GrismMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         GrismMap
      }{
         All GrismMaps have this attribute.
      }
   }
}
\sstroutine{
   ID
}{
   Object identification string
}{
   \sstdescription{
      This attribute contains a string which may be used to identify
      the \htmlref{Object}{Object} to which it is attached. There is no restriction on
      the contents of this string, which is not used internally by the
      AST library, and is simply returned without change when
      required. The default value is an empty string.

      An identification string can be valuable when, for example,
      several Objects have been stored in a file (using \htmlref{astWrite}{astWrite}) and
      are later retrieved (using \htmlref{astRead}{astRead}). Consistent use of the ID
      attribute allows the retrieved Objects to be identified without
      depending simply on the order in which they were stored.

      This attribute may also be useful during debugging, to
      distinguish similar Objects when using \htmlref{astShow}{astShow} to display them.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Unlike most other attributes, the value of the ID attribute is
         not transferred when an Object is copied. Instead, its value is
         undefined (and therefore defaults to an empty string) in any
         copy. However, it is retained in any external representation of
         an Object produced by the astWrite function.
      }
   }
}
\sstroutine{
   IF
}{
   The intermediate frequency in a dual sideband spectrum
}{
   \sstdescription{
      This attribute specifies the (topocentric) intermediate frequency in
      a dual sideband spectrum. Its sole use is to determine the local
      oscillator (LO) frequency (the frequency which marks the boundary
      between the lower and upper sidebands). The LO frequency is
      equal to the sum of the centre frequency and the intermediate
      frequency. Here, the \texttt{"} centre frequency\texttt{"}  is the topocentric
      frequency in Hz corresponding to the current value of the \htmlref{DSBCentre}{DSBCentre}
      attribute. The value of the IF attribute may be positive or
      negative: a positive value results in the LO frequency being above
      the central frequency, whilst a negative IF value results in the LO
      frequency being below the central frequency. The sign of the IF
      attribute value determines the default value for the \htmlref{SideBand}{SideBand}
      attribute.

      When setting a new value for this attribute, the units in which the
      frequency value is supplied may be indicated by appending a suitable
      string to the end of the formatted value. If the units are not
      specified, then the supplied value is assumed to be in units of GHz.
      For instance, the following strings all result in an IF of 4 GHz being
      used: \texttt{"} 4.0\texttt{"} , \texttt{"} 4.0 GHz\texttt{"} , \texttt{"} 4.0E9 Hz\texttt{"} , etc.

      When getting the value of this attribute, the returned value is
      always in units of GHz. The default value for this attribute is 4 GHz.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{DSBSpecFrame}{DSBSpecFrame}
      }{
         All DSBSpecFrames have this attribute.
      }
   }
}
\sstroutine{
   Ident
}{
   Permanent Object identification string
}{
   \sstdescription{
      This attribute is like the \htmlref{ID}{ID} attribute, in that it contains a
      string which may be used to identify the \htmlref{Object}{Object} to which it is
      attached. The only difference between ID and Ident is that Ident
      is transferred when an Object is copied, but ID is not.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   ImagFreq
}{
   The image sideband equivalent of the rest frequency
}{
   \sstdescription{
      This is a read-only attribute giving the frequency which
      corresponds to the rest frequency but is in the opposite sideband.

      The value is calculated by first transforming the rest frequency
      (given by the \htmlref{RestFreq}{RestFreq} attribute) from the standard of rest of the
      source (given by the \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} attributes) to the
      standard of rest of the observer (i.e. the topocentric standard of
      rest). The resulting topocentric frequency is assumed to be in the
      same sideband as the value given for the \htmlref{DSBCentre}{DSBCentre} attribute (the
      \texttt{"} observed\texttt{"}  sideband), and is transformed to the other sideband (the
      \texttt{"} image\texttt{"}  sideband). The new frequency is converted back to the standard
      of rest of the source, and the resulting value is returned as the
      attribute value, in units of GHz.
   }
   \sstattributetype{
      Floating point, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{DSBSpecFrame}{DSBSpecFrame}
      }{
         All DSBSpecFrames have this attribute.
      }
   }
}
\sstroutine{
   Indent
}{
   Specifies the indentation to use in text produced by a Channel
}{
   \sstdescription{
      This attribute controls the indentation within the output text produced by
      the \htmlref{astWrite}{astWrite} function.
      It gives the increase in the indentation for each level in the object
      heirarchy. If it is set to zero, no indentation will be used. [3]
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Channel}{Channel}
      }{
         The default value is zero for a basic Channel.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         The FitsChan class ignores this attribute.
      }
      \sstsubsection{
         \htmlref{StcsChan}{StcsChan}
      }{
         The default value for an StcsChan is zero, which causes the entire
         STC-S description is written out by a single invocation of the sink
         function. The text supplied to the sink function will not contain
         any linefeed characters, and each pair of adjacent words will be
         separated by a single space. The text may thus be arbitrarily large
         and the \htmlref{StcsLength}{StcsLength} attribute is ignored.

         If Indent is non-zero, then the text is written out via multiple
         calls to the sink function, each call corresponding to a single
         \texttt{"} line\texttt{"}  of text (although no line feed characters will be inserted
         by AST). The complete STC-S description is broken into lines so that:

         \sstitemlist{

            \sstitem
            the line length specified by attribute StcsLength is not exceeded

            \sstitem
            each sub-phrase (time, space, etc.) starts on a new line

            \sstitem
            each argument in a compound spatial region starts on a new line

         }
         If this causes a sub-phrase to extend to two or more lines, then the
         second and subsequent lines will be indented by three spaces compared
         to the first line. In addition, lines within a compound spatial region
         will have extra indentation to highlight the nesting produced by the
         parentheses. Each new level of nesting will be indented by a further
         three spaces.
      }
      \sstsubsection{
         \htmlref{XmlChan}{XmlChan}
      }{
         The default value for an XmlChan is zero, which results in no
         linefeeds or indentation strings being added to output text.
         If any non-zero value is assigned to Indent, then extra linefeed and
         space characters will be inserted as necessary to ensure that each
         XML tag starts on a new line, and each tag will be indented by
         a further 3 spaces to show its depth in the containment hierarchy.
      }
   }
}
\sstroutine{
   InternalUnit(axis)
}{
   Physical units for unformated axis values
}{
   \sstdescription{
      This read-only attribute contains a textual representation of the
      physical units used to represent unformatted (i.e. floating point)
      values on a particular axis of a \htmlref{Frame}{Frame}, typically handled internally
      within application code. In most cases, the value of the InternalUnit
      attribute will be the same as Unit attribute (i.e. formatted and
      unformatted axis values will normally use the same system of units).
      The main exception to this is the \htmlref{SkyFrame}{SkyFrame} class, which represents
      unformatted axis values in radians, regardless of the current
      setting of the Unit attribute.
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   IntraFlag
}{
   IntraMap identification string
}{
   \sstdescription{
      This attribute allows an \htmlref{IntraMap}{IntraMap} to be flagged so that it is
      distinguishable from other IntraMaps. The transformation function
      associated with the IntraMap may then enquire the value of this
      attribute and adapt the transformation it provides according to the
      particular IntraMap involved.

      Although this is a string attribute, it may often be useful to store
      numerical values here, encoded as a character string, and to use these
      as data within the transformation function. Note, however, that this
      mechanism is not suitable for transferring large amounts of data (more
      than about 1000 characters) to an IntraMap. For that purpose, global
      variables are recommended, although the IntraFlag value can be used to
      supplement this approach. The default IntraFlag value is an empty
      string.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         IntraMap
      }{
         All IntraMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A pair of IntraMaps whose transformations may potentially cancel
         cannot be simplified to produce a \htmlref{UnitMap}{UnitMap} (e.g. using \htmlref{astSimplify}{astSimplify})
         unless they have the same IntraFlag values. The test for equality is
         case-sensitive.
      }
   }
}
\sstroutine{
   Invert
}{
   Mapping inversion flag
}{
   \sstdescription{
      This attribute controls which one of a \htmlref{Mapping}{Mapping}\texttt{'} s two possible
      coordinate transformations is considered the \texttt{"} forward\texttt{"}
      transformation (the other being the \texttt{"} inverse\texttt{"}
      transformation). If the attribute value is zero (the default),
      the Mapping\texttt{'} s behaviour will be the same as when it was first
      created. However, if it is non-zero, its two transformations
      will be inter-changed, so that the Mapping displays the inverse
      of its original behaviour.

      Inverting the boolean sense of the Invert attribute will cause
      the values of a Mapping\texttt{'} s \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes to be
      interchanged. The values of its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}
      attributes will also be interchanged. This operation may be
      performed with the \htmlref{astInvert}{astInvert} function.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{UnitMap}{UnitMap}
      }{
         The value of the Invert attribute has no effect on the
         behaviour of a UnitMap.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         Inverting the boolean sense of the Invert attribute for a
         FrameSet will cause its base and current Frames (and its \htmlref{Base}{Base}
         and \htmlref{Current}{Current} attributes) to be interchanged. This, in turn,
         may affect other properties and attributes of the FrameSet
         (such as Nin, Nout, \htmlref{Naxes}{Naxes}, TranForward, TranInverse,
         etc.). The Invert attribute of a FrameSet is not itself
         affected by selecting a new base or current \htmlref{Frame}{Frame}.
      }
   }
}
\sstroutine{
   Invisible
}{
   Draw graphics using invisible ink?
}{
   \sstdescription{
      This attribute controls the appearance of all graphics produced by
      \htmlref{Plot}{Plot} methods by determining whether graphics should be visible or
      invisible.

      If the Invisible value of a Plot is non-zero, then all the Plot
      methods which normally generate graphical output do not do so (you
      can think of them drawing with \texttt{"} invisible ink\texttt{"} ). Such methods do,
      however, continue to do all the calculations which would be needed to
      produce the graphics. In particular, the bounding box enclosing the
      graphics is still calculated and can be retrieved as normal using
      \htmlref{astBoundingBox}{astBoundingBox}. The default value is zero, resulting in all methods
      drawing graphics as normal, using visible ink.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
}
\sstroutine{
   IsLatAxis(axis)
}{
   Is the specified celestial axis a latitude axis?
}{
   \sstdescription{
      This is a read-only boolean attribute that indicates the nature of
      the specified axis. The attribute has a non-zero value if the
      specified axis is a celestial latitude axis (Declination, Galactic
      latitude, etc), and is zero otherwise.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the SkyFrame axis to be tested.
      }
   }
}
\sstroutine{
   IsLinear
}{
   Is the Mapping linear?
}{
   \sstdescription{
      This attribute indicates whether a \htmlref{Mapping}{Mapping} is an instance of a
      class that always represents a linear transformation. Note, some
      Mapping classes can represent linear or non-linear transformations
      (the \htmlref{MathMap}{MathMap} class for instance). Such classes have a zero value for
      the IsLinear attribute. Specific instances of such classes can be
      tested for linearity using the
      \htmlref{astLinearApprox}{astLinearApprox} function.
      AST\_LINEARAPPROX routine.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         The IsLinear value for a CmpMap is determined by the classes
         of the encapsulated Mappings. For instance, a CmpMap that combines
         a \htmlref{ZoomMap}{ZoomMap} and a \htmlref{ShiftMap}{ShiftMap} will have a non-zero value for its IsLinear
         attribute, but a CmpMap that contains a MathMap will have a
         value of zero for its IsLinear attribute.
      }
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         The IsLinear value for a Frame is 1 (since a Frame is equivalent
         to a \htmlref{UnitMap}{UnitMap}).
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The IsLinear value for a FrameSet is obtained from the Mapping
         from the base Frame to the current Frame.
      }
   }
}
\sstroutine{
   IsLonAxis(axis)
}{
   Is the specified celestial axis a longitude axis?
}{
   \sstdescription{
      This is a read-only boolean attribute that indicates the nature of
      the specified axis. The attribute has a non-zero value if the
      specified axis is a celestial longitude axis (Right Ascension, Galactic
      longitude, etc), and is zero otherwise.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the SkyFrame axis to be tested.
      }
   }
}
\sstroutine{
   IsSimple
}{
   Has the Mapping been simplified?
}{
   \sstdescription{
      This attribute indicates whether a \htmlref{Mapping}{Mapping} has been simplified
      by the
      \htmlref{astSimplify}{astSimplify}
      method. If the IsSimple value is non-zero, then the Mapping has
      been simplified and so there is nothing to be gained by simplifying
      it again. Indeed, the
      astSimplify
      method will immediately return the Mapping unchanged if the IsSimple
      attribute indicates that the Mapping has already been simplified.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         All classes of Frame return zero for the IsSimple attribute.
         This is because changes can be made to a Frame which affect the
         Mapping represented by the Frame, and so there can be no
         guarantee that the Mapping may not need re-simplifying. Most
         non-Frame Mappings, on the other hand, are immutable and so when
         they are simplified it is certain that they weill remain in a
         simple state.
      }
   }
}
\sstroutine{
   IterInverse
}{
   Provide an iterative inverse transformation?
}{
   \sstdescription{
      This attribute indicates whether the inverse transformation of
      the \htmlref{PolyMap}{PolyMap} should be implemented via an iterative Newton-Raphson
      approximation that uses the forward transformation to transform
      candidate input positions until an output position is found which
      is close to the required output position. By default, an iterative
      inverse is provided if, and only if, no inverse polynomial was supplied
      when the PolyMap was constructed.

      The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that
      control the behaviour of the inverse approcimation method.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         PolyMap
      }{
         All PolyMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An iterative inverse can only be used if the PolyMap has equal
         numbers of inputs and outputs, as given by the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout}
         attributes. An error will be reported if IterInverse is set non-zero
         for a PolyMap that does not meet this requirement.
      }
   }
}
\sstroutine{
   Iwc
}{
   Include a Frame representing FITS-WCS intermediate world coordinates?
}{
   \sstdescription{
      This attribute is a boolean value which is used when a \htmlref{FrameSet}{FrameSet} is
      read from a \htmlref{FitsChan}{FitsChan} with a foreign FITS encoding (e.g. FITS-WCS) using
      \htmlref{astRead}{astRead}.
      If it has a non-zero value then the returned FrameSet will include
      Frames representing \texttt{"} intermediate world coordinates\texttt{"}  (IWC). These
      Frames will have \htmlref{Domain}{Domain} name \texttt{"} IWC\texttt{"}  for primary axis descriptions, and
      \texttt{"} IWCa\texttt{"}  for secondary axis descriptions, where \texttt{"} a\texttt{"}  is replaced by
      the single alternate axis description character, as used in the
      FITS-WCS header. The default value for \texttt{"} Iwc\texttt{"}  is zero.

      FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one
      axis for each WCS axis, and is the coordinate system produced by the
      rotation matrix (represented by FITS keyword PCi\_j, CDi\_j, etc).
      For instance, for a 2-D FITS-WCS header describing projected
      celestial longitude and latitude, the intermediate world
      coordinates represent offsets in degrees from the reference point
      within the plane of projection.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   KeyCase
}{
   Are keys case sensitive?
}{
   \sstdescription{
      This attribute is a boolean value which controls how keys are
      used. If KeyCase is zero, then key strings supplied to any method
      are automatically converted to upper case before being used. If
      KeyCase is non-zero (the default), then supplied key strings are
      used without modification.

      The value of this attribute can only be changed if the \htmlref{KeyMap}{KeyMap} is
      empty. Its value can be set conveniently when creating the KeyMap.
      An error will be reported if an attempt is made to change the
      attribute value when the KeyMap contains any entries.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         All KeyMaps have this attribute.
      }
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         The Table class over-rides this attribute by forcing it to zero.
         That is, keys within a Table are always case insensitive.
      }
   }
}
\sstroutine{
   KeyError
}{
   Report an error when getting the value of a non-existant KeyMap entry?
}{
   \sstdescription{
      This attribute is a boolean value which controls how the
      astMapGet...
      functions behave if the requested key is not found in the \htmlref{KeyMap}{KeyMap}.
      If KeyError is zero (the default), then these functions will return
      zero
      but no error will be reported. If KeyError is non-zero, then the
      same values are returned but an error is also reported.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         All KeyMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When setting a new value for KeyError, the supplied value is
         propagated to any KeyMaps contained within the supplied KeyMap.

         \sstitem
         When clearing the KeyError attribute, the attribute is also
         cleared in any KeyMaps contained within the supplied KeyMap.
      }
   }
}
\sstroutine{
   LTOffset
}{
   The offset from UTC to Local Time, in hours
}{
   \sstdescription{
      This specifies the offset from UTC to Local Time, in hours (fractional
      hours can be supplied). It is positive for time zones east of Greenwich.
      AST uses the figure as given, without making any attempt to correct for
      daylight saving. The default value is zero.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         All TimeFrames have this attribute.
      }
   }
}
\sstroutine{
   Label(axis)
}{
   Axis label
}{
   \sstdescription{
      This attribute specifies a label to be attached to each axis of
      a \htmlref{Frame}{Frame} when it is represented (e.g.) in graphical output.

      If a Label value has not been set for a Frame axis, then a
      suitable default is supplied.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default supplied by the Frame class is the string \texttt{"} \htmlref{Axis}{Axis}
         $<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for each successive axis.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Label value
         (e.g. to \texttt{"} Right ascension\texttt{"}  or \texttt{"} Galactic latitude\texttt{"} ) as
         appropriate for the particular celestial coordinate system
         being represented.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class re-defines the default Label value as
         appropriate for the particular time system being represented.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Label attribute of a FrameSet axis is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Axis labels are intended purely for interpretation by human
         readers and not by software.

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   LabelAt(axis)
}{
   Where to place numerical labels for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      where numerical axis labels and associated tick marks are
      placed.  It takes a separate value for each physical axis of a
      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LabelAt(2)=10.0\texttt{"}
      specifies where the numerical labels and tick marks for the
      second axis should be drawn.

      For each axis, the LabelAt value gives the value on the other
      axis at which numerical labels and tick marks should be placed
      (remember that Plots suitable for use with astGrid may only
      have two axes).  For example, in a celestial (RA,Dec) coordinate
      system, LabelAt(1) gives a Dec value which defines a line (of
      constant Dec) along which the numerical RA labels and their
      associated tick marks will be drawn. Similarly, LabelAt(2) gives
      the RA value at which the Dec labels and ticks will be drawn.

      The default bahaviour is for the Plot to generate its own
      position for numerical labels and tick marks.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The LabelAt value should use the same units as are used
         internally for storing coordinate values on the appropriate
         axis. For example, with a celestial coordinate system, the
         LabelAt value should be in radians, not hours or degrees.

         \sstitem
         Normally, the LabelAt value also determines where the lines
         representing coordinate axes will be drawn, so that the tick
         marks will lie on these lines (but also see the DrawAxes
         attribute).

         \sstitem
         In some circumstances, numerical labels and tick marks are
         drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling}
         attribute).  In this case, the value of the LabelAt attribute is
         ignored.
      }
   }
}
\sstroutine{
   LabelUnits(axis)
}{
   Use axis unit descriptions in a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether the descriptive labels drawn for each axis of a \htmlref{Plot}{Plot}
      should include a description of the units being used on the
      axis.  It takes a separate value for each physical axis of a
      Plot so that, for instance, the setting \texttt{"} LabelUnits(2)=1\texttt{"}
      specifies that a unit description should be included in the
      label for the second axis.

      If the LabelUnits value of a Plot axis is non-zero, a unit
      description will be included in the descriptive label for that
      axis, otherwise it will be omitted.  The default behaviour is to
      include a unit description unless the current \htmlref{Frame}{Frame} of the Plot
      is a \htmlref{SkyFrame}{SkyFrame} representing equatorial, ecliptic, galactic or
      supergalactic coordinates, in which case it is omitted.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The text used for the unit description is obtained from the
         Plot\texttt{'} s \htmlref{Unit(axis)}{Unit(axis)} attribute.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LabelUnits\texttt{"}  instead of
         \texttt{"} LabelUnits(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the LabelUnits(1) value.

         \sstitem
         If the current Frame of the Plot is not a SkyFrame, but includes
         axes which were extracted from a SkyFrame, then the default behaviour
         is to include a unit description only for those axes which were not
         extracted from a SkyFrame.
      }
   }
}
\sstroutine{
   LabelUp(axis)
}{
   Draw numerical Plot labels upright?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether the numerical labels for each axis of a \htmlref{Plot}{Plot} should be
      drawn upright or not. It takes a separate value for each
      physical axis of a Plot so that, for instance, the setting
      \texttt{"} LabelUp(2)=1\texttt{"}  specifies that numerical labels for the second
      axis should be drawn upright.

      If the LabelUp value of a Plot axis is non-zero, it causes
      numerical labels for that axis to be plotted upright (i.e. as
      normal, horizontal text), otherwise labels are drawn parallel to
      the axis to which they apply.

      The default is to produce upright labels if the labels are placed
      around the edge of the plot, and to produce labels that follow the
      axes if the labels are placed within the interior of the plot (see
      attribute \htmlref{Labelling}{Labelling}).
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         In some circumstances, numerical labels and tick marks are
         drawn around the edges of the plotting area (see the Labelling
         attribute).  In this case, the value of the LabelUp attribute is
         ignored.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LabelUp\texttt{"}  instead of
         \texttt{"} LabelUp(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the LabelUp(1) value.
      }
   }
}
\sstroutine{
   Labelling
}{
   Label and tick placement option for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the strategy for placing numerical labels and tick marks for a \htmlref{Plot}{Plot}.

      If the Labelling value of a Plot is \texttt{"} exterior\texttt{"}  (the default), then
      numerical labels and their associated tick marks are placed
      around the edges of the plotting area, if possible. If this is
      not possible, or if the Labelling value is \texttt{"} interior\texttt{"} , then they
      are placed along grid lines inside the plotting area.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute may be used to determine the exact
         placement of labels and tick marks that are drawn inside the
         plotting area.
      }
   }
}
\sstroutine{
   LatAxis
}{
   Index of the latitude axis
}{
   \sstdescription{
      This read-only attribute gives the index (1 or 2) of the latitude
      axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis
      permutations).
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   ListSize
}{
   Number of points in a PointList
}{
   \sstdescription{
      This is a read-only attribute giving the number of points in a
      \htmlref{PointList}{PointList}. This value is determined when the PointList is created.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         PointList
      }{
         All PointLists have this attribute.
      }
   }
}
\sstroutine{
   LogGap(axis)
}{
   Interval between major axis values of a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the logarithmic interval between the \texttt{"} major\texttt{"}  axis values of a \htmlref{Plot}{Plot}, at
      which (for example) major tick marks are drawn. It takes a separate
      value for each physical axis of the Plot so that, for instance,
      the setting \texttt{"} LogGap(2)=100.0\texttt{"}  specifies the ratio between adjacent major
      values along the second axis. The LogGap attribute is only used when
      the LogTicks attribute indicates that the spacing between major axis
      values is to be logarithmic. If major axis values are linearly spaced
      then the gap is specified using attribute Gap.

      The LogGap value supplied will be rounded to the nearest power of 10.
      The reciprocal of the supplied value may be used if this is necessary
      to produce usable major axis values. If a zero or negative value is
      supplied, an error will be reported when the grid is drawn. The default
      behaviour is for the Plot to generate its own LogGap value when
      required, based on the range of axis values to be represented.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The LogGap value is a ratio between axis values and is therefore
         dimensionless.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LogGap\texttt{"}  instead of \texttt{"} LogGap(2)\texttt{"} ),
         then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the attribute
         value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation
         will use just the LogGap(1) value.
      }
   }
}
\sstroutine{
   LogLabel(axis)
}{
   Use exponential format for numerical axis labels?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether the numerical axis labels should be in normal decimal form
      or should be represented as 10 raised to the appropriate power.
      That is, an axis value of 1000.0 will be drawn as \texttt{"} 1000.0\texttt{"}  if
      LogLabel is zero, but as \texttt{"} 10$\wedge$3\texttt{"}  if LogLabel is non-zero. If
      graphical escape sequences are supported (see attribute \htmlref{Escape}{Escape}),
      the power in such exponential labels will be drawn as a small
      superscript instead of using a \texttt{"} $\wedge$\texttt{"}  character to represent
      exponentiation.

      The default is to produce exponential labels if the major tick
      marks are logarithmically spaced (see the LogTicks attribute).
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Plot}{Plot}
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LogLabel\texttt{"}  instead of
         \texttt{"} LogLabel(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the LogLabel(1) value.
      }
   }
}
\sstroutine{
   LogPlot(axis)
}{
   Map the plot logarithmically onto the screen?
}{
   \sstdescription{
      This attribute controls the appearance of all graphics produced by
      the \htmlref{Plot}{Plot}, by determining whether the axes of the plotting surface
      are mapped logarithmically or linearly onto the base \htmlref{Frame}{Frame} of the
      \htmlref{FrameSet}{FrameSet} supplied when the Plot was constructed. It takes a separate
      value for each axis of the graphics coordinate system (i.e. the
      base Frame in the Plot) so that, for instance, the setting
      \texttt{"} LogPlot(2)=1\texttt{"}  specifies that the second axis of the graphics
      coordinate system (usually the vertical axis) should be mapped
      logarithmically onto the second axis of the base Frame of the
      FrameSet supplied when the Plot was constructed.

      If the LogPlot value of a Plot axis is non-zero, it causes that
      axis to be mapped logarithmically, otherwise (the default) the axis
      is mapped linearly.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The setting of the LogPlot attribute provides the default value
         for the related LogTicks attribute. By selecting suitable values for
         LogPlot and LogTicks, it is possible to have tick marks which are evenly
         spaced in value but which are mapped logarithmically onto the screen
         (and vice-versa).

         \sstitem
         An axis may only be mapped logarithmically if the visible part of
         the axis does not include the value zero. The visible part of the
         axis is that part which is mapped onto the plotting area, and is
         measured within the base Frame of the FrameSet which was supplied when
         the Plot was constructed. Any attempt to set LogPlot to a non-zero value
         will be ignored (without error) if the visible part of the axis
         includes the value zero

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LogPlot\texttt{"}  instead of
         \texttt{"} LogPlot(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the LogPlot(1) value.
      }
   }
}
\sstroutine{
   LogTicks(axis)
}{
   Space the major tick marks logarithmically?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether the major tick marks should be spaced logarithmically or
      linearly in axis value. It takes a separate value for each physical
      axis of the \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LogTicks(2)=1\texttt{"}
      specifies that the major tick marks on the second axis should be
      spaced logarithmically.

      If the LogTicks value for a physical axis is non-zero, the major
      tick marks on that axis will be spaced logarithmically (that is,
      there will be a constant ratio between the axis values at adjacent
      major tick marks). An error will be reported if the dynamic range of
      the axis (the ratio of the largest to smallest displayed axis value)
      is less than 10.0. If the LogTicks value is zero, the major tick marks
      will be evenly spaced (that is, there will be a constant difference
      between the axis values at adjacent major tick marks). The default is
      to produce logarithmically spaced tick marks if the corresponding
      LogPlot attribute is non-zero and the ratio of maximum axis value
      to minimum axis value is 100 or more. If either of these conditions
      is not met, the default is to produce linearly spaced tick marks.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The setting of the LogTicks attribute does not affect the mapping
         of the plot onto the screen, which is controlled by attribute LogPlot.
         By selecting suitable values for LogPlot and LogTicks, it is possible to
         have tick marks which are evenly spaced in value but which are mapped
         logarithmically onto the screen (and vica-versa).

         \sstitem
         An error will be reported when drawing an annotated axis grid if
         the visible part of the physical axis includes the value zero.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} LogTicks\texttt{"}  instead of
         \texttt{"} LogTicks(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the LogTicks(1) value.
      }
   }
}
\sstroutine{
   LonAxis
}{
   Index of the longitude axis
}{
   \sstdescription{
      This read-only attribute gives the index (1 or 2) of the longitude
      axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis
      permutations).
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   LutEpsilon
}{
   The relative error of the values held in the took-up table
}{
   \sstdescription{
      This attribute holds the relative error of the values held in the
      took-up table. It is used when simplifying a \htmlref{LutMap}{LutMap}, to determine
      if the LutMap should be considered linear. Setting a larger value
      makes it more likely that a LutMap will be replaced by a \htmlref{WinMap}{WinMap}
      (i.e. a linear \htmlref{Mapping}{Mapping}) when simplified.

      The default value is the value of the system constant DBL\_EPSILON
      (typically around 1e-16 or 2E-16). If the values in the look-up
      table were derived from single precision data, it may be appropriate
      to set this attribute to a value around 1E-7.

      Note, the value of this attribute may changed only if the LutMap
      has no more than one reference. That is, an error is reported if the
      LutMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         LutMap
      }{
         All LutMaps have this attribute.
      }
   }
}
\sstroutine{
   LutInterp
}{
   Look-up table interpolation method
}{
   \sstdescription{
      This attribute indicates the method to be used when finding the
      output value of a \htmlref{LutMap}{LutMap} for an input value part way between two
      table entries. If it is set to 0 (the default) then linear
      interpolation is used. Otherwise, nearest neighbour interpolation
      is used.

      Using nearest neighbour interpolation causes AST\_\_BAD to be returned
      for any point which falls outside the bounds of the table. Linear
      interpolation results in an extrapolated value being returned based
      on the two end entries in the table.

      Note, the value of this attribute may changed only if the LutMap
      has no more than one reference. That is, an error is reported if the
      LutMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         LutMap
      }{
         All LutMaps have this attribute.
      }
   }
}
\sstroutine{
   MajTickLen(axis)
}{
   Length of major tick marks for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the length of the major tick marks drawn on the axes of a \htmlref{Plot}{Plot}.
      It takes a separate value for each physical axis of the Plot so
      that, for instance, the setting \texttt{"} MajTickLen(2)=0\texttt{"}  specifies the
      length of the major tick marks drawn on the second axis.

      The MajTickLen value should be given as a fraction of the
      minimum dimension of the plotting area. Negative values cause
      major tick marks to be placed on the outside of the
      corresponding grid line or axis (but subject to any clipping
      imposed by the underlying graphics system), while positive
      values cause them to be placed on the inside.

      The default behaviour depends on whether a coordinate grid is
      drawn inside the plotting area (see the \htmlref{Grid}{Grid} attribute). If so,
      the default MajTickLen value is zero (so that major ticks are
      not drawn), otherwise the default is $+$0.015.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} MajTickLen\texttt{"}  instead of
         \texttt{"} MajTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the MajTickLen(1) value.
      }
   }
}
\sstroutine{
   MapLocked
}{
   Prevent new entries being added to a KeyMap?
}{
   \sstdescription{
      If this boolean attribute is set to
      a non-zero value,
      an error will be reported if an attempt is made to add a new entry
      to the \htmlref{KeyMap}{KeyMap}. Note, the value associated with any existing entries
      can still be changed, but no new entries can be stored in the KeyMap.
      The default value
      (zero)
      allows new entries to be added to the KeyMap.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         All KeyMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When setting a new value for MapLocked, the supplied value is
         propagated to any KeyMaps contained within the supplied KeyMap.

         \sstitem
         When clearing the MapLocked attribute, the attribute is also
         cleared in any KeyMaps contained within the supplied KeyMap.
      }
   }
}
\sstroutine{
   MatchEnd
}{
   Match trailing axes?
}{
   \sstdescription{
      This attribute is a boolean value which controls how a \htmlref{Frame}{Frame}
      behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match
      another (target) Frame. It applies only in the case where a
      match occurs between template and target Frames with different
      numbers of axes.

      If the MatchEnd value of the template Frame is zero, then the
      axes which occur first in the target Frame will be matched and
      any trailing axes (in either the target or template) will be
      disregarded. If it is non-zero, the final axes in each Frame
      will be matched and any un-matched leading axes will be
      disregarded instead.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default MatchEnd value for a Frame is zero, so that
         trailing axes are disregarded.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The MatchEnd attribute of a FrameSet is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
}
\sstroutine{
   MaxAxes
}{
   Maximum number of Frame axes to match
}{
   \sstdescription{
      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
      specifies the maximum number of axes that the target Frame may
      have in order to match the template.

      Normally, this value will equal the number of Frame axes, so
      that a template Frame will only match another Frame with the
      same number of axes as itself. By setting a different value,
      however, the matching process may be used to identify Frames
      with specified numbers of axes.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default MaxAxes value for a Frame is equal to the number
         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The MaxAxes attribute of a CmpFrame defaults to a large number
         (1000000) which is much larger than any likely number of axes in
         a Frame. Combined with the \htmlref{MinAxes}{MinAxes} default of zero (for a
         CmpFrame), this means that the default behaviour for a CmpFrame
         is to match any target Frame that consists of a subset of the
         axes in the template CmpFrame. To change this so that a CmpFrame
         will only match Frames that have the same number of axes, you
         should set the CmpFrame MaxAxes and MinAxes attributes to the
         number of axes in the CmpFrame.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The MaxAxes attribute of a FrameSet is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When setting a MaxAxes value, the value of the MinAxes
         attribute may also be silently changed so that it remains
         consistent with (i.e. does not exceed) the new value. The
         default MaxAxes value may also be reduced to remain consistent
         with the MinAxes value.

         \sstitem
         If a template Frame is used to match a target with a different
         number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used
         to determine how the individual axes of each Frame should match.
      }
   }
}
\sstroutine{
   MeshSize
}{
   Number of points used to represent the boundary of a Region
}{
   \sstdescription{
      This attribute controls how many points are used when creating a
      mesh of points covering the boundary or volume of a \htmlref{Region}{Region}. Such a
      mesh is returned by the
      \htmlref{astGetRegionMesh}{astGetRegionMesh}
      method. The boundary mesh is also used when testing for overlap
      between two Regions: each point in the bomdary mesh of the first
      Region is checked to see if it is inside or outside the second Region.
      Thus, the reliability of the overlap check depends on the value assigned
      to this attribute. If the value used is very low, it is possible for
      overlaps to go unnoticed. High values produce more reliable results, but
      can result in the overlap test being very slow. The default value is 200
      for two dimensional Regions and 2000 for three or more dimensional
      Regions (this attribute is not used for 1-dimensional regions since the
      boundary of a simple 1-d Region can only ever have two points). A
      value of five is used if the supplied value is less than five.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpRegion}{CmpRegion}
      }{
         The default MeshSize for a CmpRegion is the MeshSize of its
         first component Region.
      }
      \sstsubsection{
         \htmlref{Stc}{Stc}
      }{
         The default MeshSize for an Stc is the MeshSize of its
         encapsulated Region.
      }
   }
}
\sstroutine{
   MinAxes
}{
   Minimum number of Frame axes to match
}{
   \sstdescription{
      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
      specifies the minimum number of axes that the target Frame may
      have in order to match the template.

      Normally, this value will equal the number of Frame axes, so
      that a template Frame will only match another Frame with the
      same number of axes as itself. By setting a different value,
      however, the matching process may be used to identify Frames
      with specified numbers of axes.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default MinAxes value for a Frame is equal to the number
         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The MinAxes attribute of a CmpFrame defaults to zero. Combined
         with the \htmlref{MaxAxes}{MaxAxes} default of 1000000 (for a CmpFrame), this means
         that the default behaviour for a CmpFrame is to match any target
         Frame that consists of a subset of the axes in the template
         CmpFrame. To change this so that a CmpFrame will only match Frames
         that have the same number of axes, you should set the CmpFrame
         MinAxes and MaxAxes attributes to the number of axes in the CmpFrame.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The MinAxes attribute of a FrameSet is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When setting a MinAxes value, the value of the MaxAxes
         attribute may also be silently changed so that it remains
         consistent with (i.e. is not less than) the new value. The
         default MinAxes value may also be reduced to remain consistent
         with the MaxAxes value.

         \sstitem
         If a template Frame is used to match a target with a different
         number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used
         to determine how the individual axes of each Frame should match.
      }
   }
}
\sstroutine{
   MinTick(axis)
}{
   Density of minor tick marks for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the density of minor tick marks which appear between the major
      axis values of a \htmlref{Plot}{Plot}. It takes a separate value for each
      physical axis of a Plot so that, for instance, the setting
      \texttt{"} MinTick(2)=2\texttt{"}  specifies the density of minor tick marks along
      the second axis.

      The value supplied should be the number of minor divisions
      required between each pair of major axis values, this being one
      more than the number of minor tick marks to be drawn.  By
      default, a value is chosen that depends on the gap between major
      axis values and the nature of the axis.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} MinTick\texttt{"}  instead of
         \texttt{"} MinTick(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the MinTick(1) value.
      }
   }
}
\sstroutine{
   MinTickLen(axis)
}{
   Length of minor tick marks for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      the length of the minor tick marks drawn on the axes of a \htmlref{Plot}{Plot}.
      It takes a separate value for each physical axis of the Plot so
      that, for instance, the setting \texttt{"} MinTickLen(2)=0\texttt{"}  specifies the
      length of the minor tick marks drawn on the second axis.

      The MinTickLen value should be given as a fraction of the
      minimum dimension of the plotting area. Negative values cause
      minor tick marks to be placed on the outside of the
      corresponding grid line or axis (but subject to any clipping
      imposed by the underlying graphics system), while positive
      values cause them to be placed on the inside.

      The default value is $+$0.007.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The number of minor tick marks drawn is determined by the
         Plot\texttt{'} s \htmlref{MinTick(axis)}{MinTick(axis)} attribute.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} MinTickLen\texttt{"}  instead of
         \texttt{"} MinTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the MinTickLen(1) value.
      }
   }
}
\sstroutine{
   NatLat
}{
   Native latitude of the reference point of a FITS-WCS projection
}{
   \sstdescription{
      This attribute gives the latitude of the reference point of the
      FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in
      radians in the \texttt{"} native spherical\texttt{"}  coordinate system. This value is
      fixed for most projections, for instance it is PI/2 (90 degrees)
      for all zenithal projections. For some projections (e.g. the conics)
      the value is not fixed, but is specified by parameter one on the
      latitude axis.

      FITS-WCS paper II introduces the concept of a \texttt{"} fiducial point\texttt{"}
      which is logical distinct from the projection reference point.
      It is easy to confuse the use of these two points. The fiducial
      point is the point which has celestial coordinates given by the
      CRVAL FITS keywords. The native spherical coordinates for this point
      default to the values of the NatLat and \htmlref{NatLon}{NatLon}, but these defaults
      mey be over-ridden by values stored in the PVi\_j keywords. Put
      another way, the CRVAL keywords will by default give the celestial
      coordinates of the projection reference point, but may refer to
      some other point if alternative native longitude and latitude values
      are provided through the PVi\_j keywords.

      The NatLat attribute is read-only.
   }
   \sstattributetype{
      Floating point, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A default value of AST\_\_BAD is used if no latitude value is available.
      }
   }
}
\sstroutine{
   NatLon
}{
   Native longitude of the reference point of a FITS-WCS projection
}{
   \sstdescription{
      This attribute gives the longitude of the reference point of the
      FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in
      radians in the \texttt{"} native spherical\texttt{"}  coordinate system, and will
      usually be zero. See the description of attribute \htmlref{NatLat}{NatLat} for further
      information.

      The NatLon attribute is read-only.
   }
   \sstattributetype{
      Floating point, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
}
\sstroutine{
   Naxes
}{
   Number of Frame axes
}{
   \sstdescription{
      This is a read-only attribute giving the number of axes in a
      \htmlref{Frame}{Frame} (i.e. the number of dimensions of the coordinate space
      which the Frame describes). This value is determined when the
      Frame is created.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Naxes attribute of a FrameSet is the same as that of its
         current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The Naxes attribute of a CmpFrame is equal to the sum of the
         Naxes values of its two component Frames.
      }
   }
}
\sstroutine{
   Ncard
}{
   Number of FITS header cards in a FitsChan
}{
   \sstdescription{
      This attribute gives the total number of FITS header cards
      stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or
      deleted.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Ncolumn
}{
   The number of columns in the table
}{
   \sstdescription{
      This attribute holds the number of columns currently in the table. Columns
      are added and removed using the
      \htmlref{astAddColumn}{astAddColumn} and \htmlref{astRemoveColumn}{astRemoveColumn}
      functions.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   NegLon
}{
   Display negative longitude values?
}{
   \sstdescription{
      This attribute is a boolean value which controls how longitude values
      are normalized for display by \htmlref{astNorm}{astNorm}.

      If the NegLon attribute is zero, then normalized
      longitude values will be in the range zero to 2.pi. If NegLon is
      non-zero, then normalized longitude values will be in the range -pi
      to pi.

      The default value depends on the current value of the \htmlref{SkyRefIs}{SkyRefIs}
      attribute, If SkyRefIs has a value of \texttt{"} Origin\texttt{"} , then the default for
      NegLon is one, otherwise the default is zero.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   Negated
}{
   Region negation flag
}{
   \sstdescription{
      This attribute controls whether a \htmlref{Region}{Region} represents the \texttt{"} inside\texttt{"}  or
      the \texttt{"} outside\texttt{"}  of the area which was supplied when the Region was
      created. If the attribute value is zero (the default), the Region
      represents the inside of the original area. However, if it is non-zero,
      it represents the outside of the original area. The value of this
      attribute may be toggled using the
      \htmlref{astNegate}{astNegate} function.

      Note, whether the boundary is considered to be inside the Region or
      not is controlled by the \htmlref{Closed}{Closed} attribute. Changing the value of
      the Negated attribute does not change the value of the Closed attribute.
      Thus, if Region is closed, then the boundary of the Region will be
      inside the Region, whatever the setting of the Negated attribute.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Region
      }{
         All Regions have this attribute.
      }
   }
}
\sstroutine{
   Nframe
}{
   Number of Frames in a FrameSet
}{
   \sstdescription{
      This attrbute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This
      value will change as Frames are added or removed, but will
      always be at least one.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FrameSet
      }{
         All FrameSets have this attribute.
      }
   }
}
\sstroutine{
   Nin
}{
   Number of input coordinates for a Mapping
}{
   \sstdescription{
      This attribute gives the number of coordinate values required to
      specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of
      dimensions of the space in which the Mapping\texttt{'} s input points
      reside).
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         If a CmpMap\texttt{'} s component Mappings are joined in series, then
         its Nin attribute is equal to the Nin attribute of the first
         component (or to the \htmlref{Nout}{Nout} attribute of the second component
         if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero).

         If a CmpMap\texttt{'} s component Mappings are joined in parallel, then
         its Nin attribute is given by the sum of the Nin attributes
         of each component (or to the sum of their Nout attributes if
         the CmpMap\texttt{'} s Invert attribute is non-zero).
      }
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         The Nin attribute for a Frame is always equal to the number
         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Nin attribute of a FrameSet is equal to the number of
         axes (Naxes attribute) of its base Frame (as specified by the
         FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may
         therefore change if a new base Frame is selected.
      }
   }
}
\sstroutine{
   NiterInverse
}{
   Maximum number of iterations for the iterative inverse transformation
}{
   \sstdescription{
      This attribute controls the iterative inverse transformation
      used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero.

      Its value gives the maximum number of iterations of the
      Newton-Raphson algorithm to be used for each transformed position.
      The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{PolyMap}{PolyMap}
      }{
         All PolyMaps have this attribute.
      }
   }
}
\sstroutine{
   Nkey
}{
   Number of unique FITS keywords in a FitsChan
}{
   \sstdescription{
      This attribute gives the total number of unique FITS keywords
      stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or
      deleted. If no keyword occurrs more than once in the FitsChan, the
      \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs
      more than once, the Nkey attribute value will be smaller than
      the Ncard attribute value.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   Nobject
}{
   Number of Objects in class
}{
   \sstdescription{
      This attribute gives the total number of Objects currently in
      existence in the same class as the \htmlref{Object}{Object} whose attribute value
      is requested. This count does not include Objects which belong
      to derived (more specialised) classes.

      This attribute is mainly intended for debugging. It can be used
      to detect whether Objects which should have been deleted have,
      in fact, been deleted.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   Norm(axis)
}{
   Specifies the plane upon which a Plot3D draws text and markers
}{
   \sstdescription{
      This attribute controls the appearance of text and markers drawn
      by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which
      text and markers will be drawn by all subsequent invocations of the
      \htmlref{astText}{astText} and \htmlref{astMark}{astMark} functions.

      When setting or getting the Norm attribute, the attribute name must
      be qualified by an axis index in the range 1 to 3. The 3 elements of
      the Norm attribute are together interpreted as a vector in 3D graphics
      coordinates that is normal to the plane upon which text and marks
      should be drawn. When testing or clearing the attribute, the axis
      index is optional. If no index is supplied, then clearing the Norm
      attribute will clear all three elements, and testing the Norm attribute
      will return a non-zero value if any of the three elements are set.

      The default value is 1.0 for each of the 3 elements. The length of
      the vector is insignificant, but an error will be reported when
      attempting to draw text or markers if the vector has zero length.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Plot}{Plot}
      }{
         All Plot3Ds have this attribute.
      }
   }
}
\sstroutine{
   NormUnit(axis)
}{
   Normalised physical units for formatted axis values
}{
   \sstdescription{
      The value of this read-only attribute is derived from the current
      value of the Unit attribute. It will represent an equivalent system
      of units to the Unit attribute, but will potentially be simplified.
      For instance, if Unit is set to \texttt{"} s$*$(m/s)\texttt{"} , the NormUnit value will
      be \texttt{"} m\texttt{"} . If no simplification can be performed, the value of the
      NormUnit attribute will equal that of the Unit attribute.
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         All Frames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   Nout
}{
   Number of output coordinates for a Mapping
}{
   \sstdescription{
      This attribute gives the number of coordinate values generated
      by a \htmlref{Mapping}{Mapping} to specify each output point (i.e. the number of
      dimensions of the space in which the Mapping\texttt{'} s output points
      reside).
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         If a CmpMap\texttt{'} s component Mappings are joined in series, then
         its Nout attribute is equal to the Nout attribute of the
         second component (or to the \htmlref{Nin}{Nin} attribute of the first
         component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero).

         If a CmpMap\texttt{'} s component Mappings are joined in parallel, then
         its Nout attribute is given by the sum of the Nout attributes
         of each component (or to the sum of their Nin attributes if
         the CmpMap\texttt{'} s Invert attribute is non-zero).
      }
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         The Nout attribute for a Frame is always equal to the number
         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Nout attribute of a FrameSet is equal to the number of
         FrameSet axes (Naxes attribute) which, in turn, is equal to
         the Naxes attribute of the FrameSet\texttt{'} s current Frame (as
         specified by the \htmlref{Current}{Current} attribute). The Nout attribute value
         may therefore change if a new current Frame is selected.
      }
   }
}
\sstroutine{
   Nparameter
}{
   The number of global parameters in the table
}{
   \sstdescription{
      This attribute holds the number of global parameters currently in the table.
      Parameters are added and removed using the
      \htmlref{astAddParameter}{astAddParameter} and \htmlref{astRemoveParameter}{astRemoveParameter}
      functions.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   Nrow
}{
   The number of rows in the table
}{
   \sstdescription{
      This attribute holds the index of the last row to which any
      contents have been added using any of the
      astMapPut...
      AST\_MAPPUT...
      functions. The first row has index 1.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Table}{Table}
      }{
         All Tables have this attribute.
      }
   }
}
\sstroutine{
   NumLab(axis)
}{
   Draw numerical axis labels for a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether labels should be drawn to represent the numerical values
      along each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each
      physical axis of a Plot so that, for instance, the setting
      \texttt{"} NumLab(2)=1\texttt{"}  specifies that numerical labels should be drawn
      for the second axis.

      If the NumLab value of a Plot axis is non-zero (the default),
      then numerical labels will be drawn for that axis, otherwise
      they will be omitted.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The drawing of associated descriptive axis labels for a Plot
         (describing the quantity being plotted along each axis) is
         controlled by the \htmlref{TextLab(axis)}{TextLab(axis)} attribute.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} NumLab\texttt{"}  instead of
         \texttt{"} NumLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the NumLab(1) value.
      }
   }
}
\sstroutine{
   NumLabGap(axis)
}{
   Spacing of numerical labels for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      where numerical axis labels are placed relative to the axes they
      describe.  It takes a separate value for each physical axis of a
      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} NumLabGap(2)=-0.01\texttt{"}
      specifies where the numerical label for the second axis should
      be drawn.

      For each axis, the NumLabGap value gives the spacing between the
      axis line (or edge of the plotting area, if appropriate) and the
      nearest edge of the corresponding numerical axis
      labels. Positive values cause the descriptive label to be placed
      on the opposite side of the line to the default tick marks,
      while negative values cause it to be placed on the same side.

      The NumLabGap value should be given as a fraction of the minimum
      dimension of the plotting area, the default value being $+$0.01.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} NumLabGap\texttt{"}  instead of
         \texttt{"} NumLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the NumLabGap(1) value.
      }
   }
}
\sstroutine{
   ObjSize
}{
   The in-memory size of the Object
}{
   \sstdescription{
      This attribute gives the total number of bytes of memory used by
      the \htmlref{Object}{Object}. This includes any Objects which are encapsulated within
      the supplied Object.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   ObsAlt
}{
   The geodetic altitude of the observer
}{
   \sstdescription{
      This attribute specifies the geodetic altitude of the observer, in
      metres, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame}
      class makes no use of this attribute, but specialised subclasses of
      Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame}
      classes use it. The default value is zero.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
      \sstsubsection{
         SpecFrame
      }{
         Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
         it defines the Doppler shift introduced by the observers diurnal
         motion around the earths axis, which is needed when converting to
         or from the topocentric standard of rest. The maximum velocity
         error which can be caused by an incorrect value is 0.5 km/s. The
         default value for the attribute is zero.
      }
      \sstsubsection{
         TimeFrame
      }{
         Together with the ObsLon attribute, it is used when converting
         between certain time scales (TDB, TCB, LMST, LAST)
      }
   }
}
\sstroutine{
   ObsLat
}{
   The geodetic latitude of the observer
}{
   \sstdescription{
      This attribute specifies the geodetic latitude of the observer, in
      degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame}
      class makes no use of this attribute, but specialised subclasses of
      Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame}
      classes use it. The default value is zero.

      The value is stored internally in radians, but is converted to and
      from a degrees string for access. Some example input formats are:
      \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} ,
      \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can
      optionally be indicated using characters \texttt{"} N\texttt{"}  and \texttt{"} S\texttt{"}  in place of the
      usual \texttt{"} $+$\texttt{"}  and \texttt{"} -\texttt{"} . When converting the stored value to a string, the
      format \texttt{"} [s]dd:mm:ss.ss\texttt{"}  is used, when \texttt{"} [s]\texttt{"}  is \texttt{"} N\texttt{"}  or \texttt{"} S\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
      \sstsubsection{
         SpecFrame
      }{
         Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
         it defines the Doppler shift introduced by the observers diurnal
         motion around the earths axis, which is needed when converting to
         or from the topocentric standard of rest. The maximum velocity
         error which can be caused by an incorrect value is 0.5 km/s. The
         default value for the attribute is zero.
      }
      \sstsubsection{
         TimeFrame
      }{
         Together with the ObsLon attribute, it is used when converting
         between certain time scales (TDB, TCB, LMST, LAST)
      }
   }
}
\sstroutine{
   ObsLon
}{
   The geodetic longitude of the observer
}{
   \sstdescription{
      This attribute specifies the geodetic (or equivalently, geocentric)
      longitude of the observer, in degrees, measured positive eastwards.
      See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this
      attribute, but specialised subclasses of Frame may use it. For instance,
      the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value
      is zero.

      The value is stored internally in radians, but is converted to and
      from a degrees string for access. Some example input formats are:
      \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} ,
      \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can
      optionally be indicated using characters \texttt{"} E\texttt{"}  and \texttt{"} W\texttt{"}  in place of the
      usual \texttt{"} $+$\texttt{"}  and \texttt{"} -\texttt{"} . When converting the stored value to a string, the
      format \texttt{"} [s]ddd:mm:ss.ss\texttt{"}  is used, when \texttt{"} [s]\texttt{"}  is \texttt{"} E\texttt{"}  or \texttt{"} W\texttt{"}  and the
      numerical value is chosen to be less than 180 degrees.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
      \sstsubsection{
         SpecFrame
      }{
         Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
         it defines the Doppler shift introduced by the observers diurnal
         motion around the earths axis, which is needed when converting to
         or from the topocentric standard of rest. The maximum velocity
         error which can be caused by an incorrect value is 0.5 km/s. The
         default value for the attribute is zero.
      }
      \sstsubsection{
         TimeFrame
      }{
         Together with the ObsLon attribute, it is used when converting
         between certain time scales (TDB, TCB, LMST, LAST)
      }
   }
}
\sstroutine{
   PVMax(i)
}{
   Maximum number of FITS-WCS projection parameters
}{
   \sstdescription{
      This attribute specifies the largest legal index for a PV projection
      parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the
      largest legal value for \texttt{"} m\texttt{"}  when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"}  attribute).
      The axis index is specified by i, and should be in the range 1 to 99.
      The value for each axis is determined by the projection type specified
      when the WcsMap
      is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be
      changed.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
}
\sstroutine{
   PVi\_m
}{
   FITS-WCS projection parameters
}{
   \sstdescription{
      This attribute specifies the projection parameter values to be
      used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection.
      Each PV attribute name should include two integers, i and m,
      separated by an underscore. The axis index is specified
      by i, and should be in the range 1 to 99. The parameter number
      is specified by m, and should be in the range 0 to 99. For
      example, \texttt{"} PV2\_1=45.0\texttt{"}  would specify a value for projection
      parameter 1 of axis 2 in a WcsMap.

      These projection parameters correspond exactly to the values
      stored using the FITS-WCS keywords \texttt{"} PV1\_1\texttt{"} , \texttt{"} PV1\_2\texttt{"} , etc. This
      means that projection parameters which correspond to angles must
      be given in degrees (despite the fact that the angular
      coordinates and other attributes used by a WcsMap are in
      radians).

      The set of projection parameters used by a WcsMap depends on the
      type of projection, which is determined by its \htmlref{WcsType}{WcsType}
      parameter.  Most projections either do not require projection
      parameters, or use parameters 1 and 2 associated with the latitude
      axis. You should consult the FITS-WCS paper for details.

      Some projection parameters have default values (as defined in
      the FITS-WCS paper) which apply if no explicit value is given.
      You may omit setting a value for these \texttt{"} optional\texttt{"}  parameters and the
      default will apply. Some projection parameters, however, have no
      default and a value must be explicitly supplied.  This is most
      conveniently
      done using the \texttt{"} options\texttt{"}  argument of \htmlref{astWcsMap}{astWcsMap} (q.v.) when a WcsMap
      is first created. An error will result when a WcsMap is used to
      transform coordinates if any of its required projection
      parameters has not been set and lacks a default value.

      A \texttt{"} get\texttt{"}  operation for a parameter which has not been assigned a value
      will return the default value defined in the FITS-WCS paper, or
      AST\_\_BAD if the paper indicates that the parameter has no default.
      A default value of zero is returned for parameters which are not
      accessed by the projection.

      Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude
      axis to hold the native longitude and latitude of the fiducial
      point of the projection, in degrees. The default values for these
      parameters are determined by the projection type. The AST-specific
      TPN projection does not use this convention - all projection
      parameters for both axes are used to represent polynomical correction
      terms, and the native longitude and latitude at the fiducial point may
      not be changed from the default values of zero and 90 degrees.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The value of this attribute may changed only if the WcsMap
         has no more than one reference. That is, an error is reported if the
         WcsMap has been cloned, either by including it within another object
         such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
         \htmlref{astClone}{astClone}
         function.

         \sstitem
         If the projection parameter values given for a WcsMap do not
         satisfy all the required constraints (as defined in the FITS-WCS
         paper), then an error will result when the WcsMap is used to
         transform coordinates.
      }
   }
}
\sstroutine{
   PcdCen(axis)
}{
   Centre coordinates of pincushion/barrel distortion
}{
   \sstdescription{
      This attribute specifies the centre of the pincushion/barrel
      distortion implemented by a \htmlref{PcdMap}{PcdMap}. It takes a separate value for
      each axis of the PcdMap so that, for instance, the settings
      \texttt{"} PcdCen(1)=345.0,PcdCen(2)=-104.4\texttt{"}  specify that the pincushion
      distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2
      respectively. This attribute is set when a PcdMap is created, but may
      later be modified. If the attribute is cleared, the default value for
      both axes is zero.

      Note, the value of this attribute may changed only if the PcdMap
      has no more than one reference. That is, an error is reported if the
      PcdMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         PcdMap
      }{
         All PcdMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If no axis is specified, (e.g. \texttt{"} PcdCen\texttt{"}  instead of
         \texttt{"} PcdCen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of both axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
         operation will use just the PcdCen(1) value.
      }
   }
}
\sstroutine{
   Permute
}{
   Permute axis order?
}{
   \sstdescription{
      This attribute is a boolean value which controls how a \htmlref{Frame}{Frame}
      behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match
      another (target) Frame. It specifies whether the axis order of
      the target Frame may be permuted in order to obtain a match.

      If the template\texttt{'} s Permute value is zero, it will match a target
      only if it can do so without changing the order of its
      axes. Otherwise, it will attempt to permute the target\texttt{'} s axes as
      necessary.

      The default value is 1, so that axis permutation will be attempted.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute. However, the Frame class
         effectively ignores this attribute and behaves as if it has
         the value 1. This is because the axes of a basic Frame are
         not distinguishable and will always match any other Frame
         whatever their order.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         Unlike a basic Frame, the SkyFrame class makes use of this
         attribute.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Permute attribute of a FrameSet is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
}
\sstroutine{
   PolarLong
}{
   The longitude value to assign to either pole
}{
   \sstdescription{
      This attribute holds the longitude value, in radians, to be
      returned when a Cartesian position corresponding to either the north
      or south pole is transformed into spherical coordinates. The
      default value is zero.

      Note, the value of this attribute may changed only if the \htmlref{SphMap}{SphMap}
      has no more than one reference. That is, an error is reported if the
      SphMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         SphMap
      }{
         All SphMaps have this attribute.
      }
   }
}
\sstroutine{
   PolyTan
}{
   Use PVi\_m keywords to define distorted TAN projection?
}{
   \sstdescription{
      This attribute is a boolean value which specifies how FITS \texttt{"} TAN\texttt{"}
      projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign
      encoded FITS header. If zero, the projection is assumed to conform
      to the published FITS-WCS standard. If positive, the convention
      for a distorted TAN projection included in an early draft version
      of FITS-WCS paper II are assumed. In this convention the
      coefficients of a polynomial distortion to be applied to
      intermediate world coordinates are specified by the \htmlref{PVi\_m}{PVi\_m} keywords.
      This convention was removed from the paper before publication and so
      does not form part of the standard. Indeed, it is incompatible with
      the published standard because it re-defines the meaning of the
      first five PVi\_m keywords on the longitude axis, which are reserved
      by the published standard for other purposes. However, headers that
      use this convention are still to be found, for instance the SCAMP
      utility (http://www.astromatic.net/software/scamp) creates them.

      The default value for the PolyTan attribute is -1. A negative
      values causes the used convention to depend on the contents
      of the \htmlref{FitsChan}{FitsChan}. If the FitsChan contains any PVi\_m keywords for
      the latitude axis, or if it contains PVi\_m keywords for the
      longitude axis with \texttt{"} m\texttt{"}  greater than 4, then the distorted TAN
      convention is used. Otherwise, the standard convention is used.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   PreserveAxes
}{
   Preserve axes?
}{
   \sstdescription{
      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
      determines which axes appear (and in what order) in the \texttt{"} result\texttt{"}
      Frame produced.

      If PreserveAxes is zero in the template Frame, then the result
      Frame will have the same number (and order) of axes as the
      template. If it is non-zero, however, the axes of the target
      Frame will be preserved, so that the result Frame will have the
      same number (and order) of axes as the target.

      The default value is zero, so that target axes are not preserved
      and the result Frame resembles the template.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         All Frames have this attribute.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The PreserveAxes attribute of a FrameSet is the same as that
         of its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
}
\sstroutine{
   ProjP(m)
}{
   FITS-WCS projection parameters
}{
   \sstdescription{
      This attribute provides aliases for the PV attributes, which
      specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap}
      when implementing a FITS-WCS sky projection. ProjP is retained for
      compatibility with previous versions of FITS-WCS and AST. New
      applications should use the PV attibute instead.

      Attributes ProjP(0) to ProjP(9) correspond to attributes PV$<$axlat$>$\_0
      to PV$<$axlat$>$\_9, where $<$axlat$>$ is replaced by the index of the
      latitude axis (given by attribute WcsAxis(2)). See PV for further
      details.

      Note, the value of this attribute may changed only if the WcsMap
      has no more than one reference. That is, an error is reported if the
      WcsMap has been cloned, either by including it within another object
      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
      \htmlref{astClone}{astClone}
      function.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
}
\sstroutine{
   Projection
}{
   Sky projection description
}{
   \sstdescription{
      This attribute provides a place to store a description of the
      type of sky projection used when a \htmlref{SkyFrame}{SkyFrame} is attached to a
      2-dimensional object, such as an image or plotting surface. For
      example, typical values might be \texttt{"} orthographic\texttt{"} , \texttt{"} Hammer-Aitoff\texttt{"}
      or \texttt{"} cylindrical equal area\texttt{"} .

      The Projection value is purely descriptive and does not affect
      the celestial coordinate system represented by the SkyFrame in
      any way. If it is set to a non-blank string, the description
      provided may be used when forming the default value for the
      SkyFrame\texttt{'} s \htmlref{Title}{Title} attribute (so that typically it will appear in
      graphical output, for instance). The default value is an empty
      string.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   RefCount
}{
   Count of active Object pointers
}{
   \sstdescription{
      This attribute gives the number of active pointers associated
      with an \htmlref{Object}{Object}. It is modified whenever pointers are created or
      annulled (by \htmlref{astClone}{astClone}, \htmlref{astAnnul}{astAnnul} or \htmlref{astEnd}{astEnd} for example). The count
      includes the initial pointer issued when the Object was created.

      If the reference count for an Object falls to zero as the result
      of annulling a pointer to it, then the Object will be deleted.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   RefDec
}{
   The declination of the reference point
}{
   \sstdescription{
      This attribute specifies the FK5 J2000.0 declination of a reference
      point on the sky. See the description of attribute \htmlref{RefRA}{RefRA} for details.
      The default RefDec is \texttt{"} 0:0:0\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   RefRA
}{
   The right ascension of the reference point
}{
   \sstdescription{
      This attribute, together with the \htmlref{RefDec}{RefDec} attribute, specifies the FK5
      J2000.0 coordinates of a reference point on the sky. For 1-dimensional
      spectra, this should normally be the position of the source. For
      spectral data with spatial coverage (spectral cubes, etc), this should
      be close to centre of the spatial coverage. It is used to define the
      correction for Doppler shift to be applied when using the
      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}
      method to convert between different standards of rest.

      The \htmlref{SpecFrame}{SpecFrame} class assumes this velocity correction is spatially
      invariant. If a single SpecFrame is used (for instance, as a
      component of a \htmlref{CmpFrame}{CmpFrame}) to describe spectral values at different
      points on the sky, then it is assumes that the doppler shift at any
      spatial position is the same as at the reference position. The
      maximum velocity error introduced by this assumption is of the order
      of V$*$SIN(FOV), where FOV is the angular field of view, and V is the
      relative velocity of the two standards of rest. As an example, when
      correcting from the observers rest frame (i.e. the topocentric rest
      frame) to the kinematic local standard of rest the maximum value of V
      is about 20 km/s, so for 5 arc-minute field of view the maximum velocity
      error introduced by the correction will be about 0.03 km/s. As another
      example, the maximum error when correcting from the observers rest frame
      to the local group is about 5 km/s over a 1 degree field of view.

      The RefRA and RefDec attributes are stored internally in radians, but
      are converted to and from a string for access. The format \texttt{"} hh:mm:ss.ss\texttt{"}
      is used for RefRA, and \texttt{"} dd:mm:ss.s\texttt{"}  is used for RefDec. The methods
      \htmlref{astSetRefPos}{astSetRefPos} and \htmlref{astGetRefPos}{astGetRefPos} may be used to access the values of
      these attributes directly as unformatted values in radians.

      The default for RefRA is \texttt{"} 0:0:0\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         SpecFrame
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   RegionClass
}{
   The AST class name of the Region encapsulated within an Stc
}{
   \sstdescription{
      This is a read-only attribute giving the AST class name of the
      \htmlref{Region}{Region} encapsulated within an \htmlref{Stc}{Stc} (that is, the class of the Region
      which was supplied when the Stc was created).
   }
   \sstattributetype{
      String, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Stc
      }{
         All Stc objects this attribute.
      }
   }
}
\sstroutine{
   Report
}{
   Report transformed coordinates?
}{
   \sstdescription{
      This attribute controls whether coordinate values are reported
      whenever a \htmlref{Mapping}{Mapping} is used to transform a set of points. If its
      value is zero (the default), no report is made. However, if it
      is non-zero, the coordinates of each point are reported (both
      before and after transformation) by writing them to standard
      output.

      This attribute is provided as an aid to debugging, and to avoid
      having to report values explicitly in simple programs.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         When applied to a compound Mapping (CmpMap), only the Report
         attribute of the CmpMap, and not those of its component
         Mappings, is used.  Coordinate information is never reported
         for the component Mappings individually, only for the
         complete CmpMap.
      }
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         When applied to any Frame, the formatting capabilities of the
         Frame (as provided by the \htmlref{astFormat}{astFormat} function) will be used to
         format the reported coordinates.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         When applied to any FrameSet, the formatting capabilities of
         the base and current Frames will be used (as above) to
         individually format the input and output coordinates, as
         appropriate. The Report attribute of a FrameSet is not itself
         affected by selecting a new base or current Frame, but the
         resulting formatting capabilities may be.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Unlike most other attributes, the value of the Report
         attribute is not transferred when a Mapping is copied. Instead,
         its value is undefined (and therefore defaults to zero) in any
         copy. Similarly, it becomes undefined in any external
         representation of a Mapping produced by the \htmlref{astWrite}{astWrite} function.
      }
   }
}
\sstroutine{
   ReportLevel
}{
   Determines which read/write conditions are reported
}{
   \sstdescription{
      This attribute determines which, if any, of the conditions that occur
      whilst reading or writing an \htmlref{Object}{Object} should be reported. These
      conditions will generate either a fatal error or a warning, as
      determined by attribute \htmlref{Strict}{Strict}. ReportLevel can take any of the
      following values:

      0 - Do not report any conditions.

      1 - \htmlref{Report}{Report} only conditions where significant information content has been
      changed. For instance, an unsupported time-scale has been replaced by a
      supported near-equivalent time-scale. Another example is if a basic
      \htmlref{Channel}{Channel} unexpected encounters data items that may have been introduced
      by later versions of AST.

      2 - Report the above, and in addition report significant default
      values. For instance, if no time-scale was specified when reading an
      Object from an external data source, report the default time-scale
      that is being used.

      3 - Report the above, and in addition report any other potentially
      interesting conditions that have no significant effect on the
      conversion. For instance, report if a time-scale of \texttt{"} TT\texttt{"}
      (terrestrial time) is used in place of \texttt{"} ET\texttt{"}  (ephemeris time). This
      change has no signficiant effect because ET is the predecessor of,
      and is continuous with, TT. Synonyms such as \texttt{"} IAT\texttt{"}  and \texttt{"} TAI\texttt{"}  are
      another example.

      The default value is 1. Note, there are many other conditions that
      can occur whilst reading or writing an Object that completely
      prevent the conversion taking place. Such conditions will always
      generate errors, irrespective of the ReportLevel and Strict attributes.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         All Channels have this attribute.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         All the conditions selected by the FitsChan \htmlref{Warnings}{Warnings} attribute are
         reported at level 1.
      }
   }
}
\sstroutine{
   RestFreq
}{
   The rest frequency
}{
   \sstdescription{
      This attribute specifies the frequency corresponding to zero
      velocity. It is used when converting between between velocity-based
      coordinate systems and and other coordinate systems (such as frequency,
      wavelength, energy, etc). The default value is 1.0E5 GHz.

      When setting a new value for this attribute, the new value can be
      supplied either directly as a frequency, or indirectly as a wavelength
      or energy, in which case the supplied value is converted to a frequency
      before being stored. The nature of the supplied value is indicated by
      appending text to the end of the numerical value indicating the units in
      which the value is supplied. If the units are not specified, then the
      supplied value is assumed to be a frequency in units of GHz. If the
      supplied unit is a unit of frequency, the supplied value is assumed to
      be a frequency in the given units. If the supplied unit is a unit of
      length, the supplied value is assumed to be a (vacuum) wavelength. If
      the supplied unit is a unit of energy, the supplied value is assumed to
      be an energy. For instance, the following strings all result in
      a rest frequency of around 1.4E14 Hz being used: \texttt{"} 1.4E5\texttt{"} , \texttt{"} 1.4E14 Hz\texttt{"} ,
      \texttt{"} 1.4E14 s$*$$*$-1\texttt{"} , \texttt{"} 1.4E5 GHz\texttt{"} , \texttt{"} 2.14E-6 m\texttt{"} , \texttt{"} 21400 Angstrom\texttt{"} , \texttt{"} 9.28E-20 J\texttt{"} ,
      \texttt{"} 9.28E-13 erg\texttt{"} , \texttt{"} 0.58 eV\texttt{"} , etc.

      When getting the value of this attribute, the returned value is
      always a frequency in units of GHz.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   RootCorner
}{
   Specifies which edges of the 3D box should be annotated
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      which edges of the cube enclosing the 3D graphics space are used
      for displaying numerical and descriptive axis labels. The attribute
      value identifies one of the eight corners of the cube within
      which graphics are being drawn (i.e. the cube specified by the
      \texttt{"} graphbox\texttt{"}  parameter when \htmlref{astPlot3D}{astPlot3D}
      was called tp create the \htmlref{Plot3D}{Plot3D}). \htmlref{Axis}{Axis} labels and tick marks will
      be placed on the three cube edges that meet at the given corner.

      The attribute value should consist of three character, each of
      which must be either \texttt{"} U\texttt{"}  or \texttt{"} L\texttt{"} . The first character in the string
      specifies the position of the corner on the first graphics axis.
      If the character is \texttt{"} U\texttt{"}  then the corner is at the upper bound on the
      first graphics axis. If it is \texttt{"} L\texttt{"} , then the corner is at the lower
      bound on the first axis. Likewise, the second and third characters
      in the string specify the location of the corner on the second and
      third graphics axes.

      For instance, corner \texttt{"} LLL\texttt{"}  is the corner that is at the lower bound
      on all three graphics axes, and corner \texttt{"} ULU\texttt{"}  is at the upper bound
      on axes 1 and 3 but at the lower bound on axis 2.

      The default value is \texttt{"} LLL\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Plot3D
      }{
         All Plot3Ds have this attribute.
      }
   }
}
\sstroutine{
   Seed
}{
   Random number seed for a MathMap
}{
   \sstdescription{
      This attribute, which may take any integer value, determines the
      sequence of random numbers produced by the random number functions in
      \htmlref{MathMap}{MathMap} expressions. It is set to an unpredictable default value when
      a MathMap is created, so that by default each MathMap uses a different
      set of random numbers.

      If required, you may set this Seed attribute to a value of your
      choosing in order to produce repeatable behaviour from the random
      number functions. You may also enquire the Seed value (e.g. if an
      initially unpredictable value has been used) and then use it to
      reproduce the resulting sequence of random numbers, either from the
      same MathMap or from another one.

      Clearing the Seed attribute gives it a new unpredictable default
      value.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         MathMap
      }{
         All MathMaps have this attribute.
      }
   }
}
\sstroutine{
   SideBand
}{
   Indicates which sideband a dual sideband spectrum represents
}{
   \sstdescription{
      This attribute indicates whether the \htmlref{DSBSpecFrame}{DSBSpecFrame} currently
      represents its lower or upper sideband, or an offset from the local
      oscillator frequency. When querying the current value, the returned
      string is always one of \texttt{"} usb\texttt{"}  (for upper sideband), \texttt{"} lsb\texttt{"}  (for lower
      sideband), or \texttt{"} lo\texttt{"}  (for offset from the local oscillator frequency).
      When setting a new value, any of the strings \texttt{"} lsb\texttt{"} , \texttt{"} usb\texttt{"} , \texttt{"} observed\texttt{"} ,
      \texttt{"} image\texttt{"}  or \texttt{"} lo\texttt{"}  may be supplied (case insensitive). The \texttt{"} observed\texttt{"}
      sideband is which ever sideband (upper or lower) contains the central
      spectral position given by attribute \htmlref{DSBCentre}{DSBCentre}, and the \texttt{"} image\texttt{"}
      sideband is the other sideband. It is the sign of the \htmlref{IF}{IF} attribute
      which determines if the observed sideband is the upper or lower
      sideband. The default value for SideBand is the observed sideband.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         DSBSpecFrame
      }{
         All DSBSpecFrames have this attribute.
      }
   }
}
\sstroutine{
   SimpFI
}{
   Forward-inverse MathMap pairs simplify?
}{
   \sstdescription{
      This attribute should be set to a non-zero value if applying a
      \htmlref{MathMap}{MathMap}\texttt{'} s forward transformation, followed immediately by the matching
      inverse transformation will always restore the original set of
      coordinates. It indicates that AST may replace such a sequence of
      operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered
      while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).

      By default, the SimpFI attribute is zero, so that AST will not perform
      this simplification unless you have set SimpFI to indicate that it is
      safe to do so.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         MathMap
      }{
         All MathMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For simplification to occur, the two MathMaps must be in series and
         be identical (with textually identical transformation
         functions). Functional equivalence is not sufficient.

         \sstitem
         The consent of both MathMaps is required before simplification can
         take place. If either has a SimpFI value of zero, then simplification
         will not occur.

         \sstitem
         The SimpFI attribute controls simplification only in the case where
         a MathMap\texttt{'} s forward transformation is followed by the matching inverse
         transformation. It does not apply if an inverse transformation is
         followed by a forward transformation. This latter case is controlled
         by the \htmlref{SimpIF}{SimpIF} attribute.

         \sstitem
         The \texttt{"} forward\texttt{"}  and \texttt{"} inverse\texttt{"}  transformations referred to are those
         defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"}  and
         \texttt{"} inv\texttt{"}  parameters of its constructor function). If the MathMap is
         inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the
         SimpFI and SimpIF attributes will be interchanged.
      }
   }
}
\sstroutine{
   SimpIF
}{
   Inverse-forward MathMap pairs simplify?
}{
   \sstdescription{
      This attribute should be set to a non-zero value if applying a
      \htmlref{MathMap}{MathMap}\texttt{'} s inverse transformation, followed immediately by the matching
      forward transformation will always restore the original set of
      coordinates. It indicates that AST may replace such a sequence of
      operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered
      while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).

      By default, the SimpIF attribute is zero, so that AST will not perform
      this simplification unless you have set SimpIF to indicate that it is
      safe to do so.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         MathMap
      }{
         All MathMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For simplification to occur, the two MathMaps must be in series and
         be identical (with textually identical transformation
         functions). Functional equivalence is not sufficient.

         \sstitem
         The consent of both MathMaps is required before simplification can
         take place. If either has a SimpIF value of zero, then simplification
         will not occur.

         \sstitem
         The SimpIF attribute controls simplification only in the case where
         a MathMap\texttt{'} s inverse transformation is followed by the matching forward
         transformation. It does not apply if a forward transformation is
         followed by an inverse transformation. This latter case is controlled
         by the \htmlref{SimpFI}{SimpFI} attribute.

         \sstitem
         The \texttt{"} forward\texttt{"}  and \texttt{"} inverse\texttt{"}  transformations referred to are those
         defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"}  and
         \texttt{"} inv\texttt{"}  parameters of its constructor function). If the MathMap is
         inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the
         SimpFI and SimpIF attributes will be interchanged.
      }
   }
}
\sstroutine{
   SimpVertices
}{
   Simplify a Polygon by transforming its vertices?
}{
   \sstdescription{
      This attribute controls the behaviour of the
      \htmlref{astSimplify}{astSimplify}
      method when applied to a \htmlref{Polygon}{Polygon}. The simplified Polygon is created
      by transforming the vertices from the \htmlref{Frame}{Frame} in which the Polygon
      was originally defined into the Frame currently represented by the
      Polygon. If SimpVertices is non-zero (the default) then this
      simplified Polygon is returned without further checks. If SimpVertices
      is zero, a check is made that the edges of the new Polygon do not
      depart significantly from the edges of the original Polygon (as
      determined by the uncertainty associated with the Polygon). This
      could occur, for instance, if the \htmlref{Mapping}{Mapping} frrm the original to the
      current Frame is highly non-linear. If this check fails, the
      original unsimplified Polygon is returned without change.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Polygon
      }{
         All Polygons have this attribute.
      }
   }
}
\sstroutine{
   SinkFile
}{
   Output file to which to data should be written
}{
   \sstdescription{
      This attribute specifies the name of a file to which the \htmlref{Channel}{Channel}
      should write data. If specified it is used in preference to any sink
      function specified when the Channel was created.

      Assigning a new value to this attribute will cause any previously
      opened SinkFile to be closed. The first subsequent call to
      \htmlref{astWrite}{astWrite}
      will attempt to open the new file (an error will be reported if the
      file cannot be opened), and write data to it. All subsequent call to
      astWrite
      will write data to the new file, until the SinkFile attribute is
      cleared or changed.

      Clearing the attribute causes any open SinkFile to be closed. All
      subsequent data writes will use the sink function specified when the
      Channel was created, or will write to standard output if no sink
      function was specified.

      If no value has been assigned to SinkFile, a null string will be
      returned if an attempt is made to get the attribute value.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         When the FitsChan is destroyed, any headers in the FitsChan will be
         written out to the sink file, if one is specified (if not, the
         sink function used when the FitsChan was created is used). The
         sink file is a text file (not a FITS file) containing one header
         per line.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A new SinkFile will over-write any existing file with the same
         name unless the existing file is write protected, in which case an
         error will be reported.

         \sstitem
         Any open SinkFile is closed when the Channel is deleted.

         \sstitem
         If the Channel is copied or dumped
         (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow})
         the SinkFile attribute is left in a cleared state in the output
         Channel (i.e. the value of the SinkFile attribute is not copied).
      }
   }
}
\sstroutine{
   Size(element)
}{
   Character size for a Plot element
}{
   \sstdescription{
      This attribute determines the character size used when drawing
      each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
      separate value for each graphical element so that, for instance,
      the setting \texttt{"} Size(title)=2.0\texttt{"}  causes the Plot title to be drawn
      using twice the default character size.

      The range of character sizes available and the appearance of the
      resulting text is determined by the underlying graphics system.
      The default behaviour is for all graphical elements to be drawn
      using the default character size supplied by this graphics
      system.
   }
   \sstattributetype{
      Floating Point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of the graphical elements available, see the
         description of the Plot class.

         \sstitem
         If no graphical element is specified, (e.g. \texttt{"} Size\texttt{"}  instead
         of \texttt{"} Size(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
         affect the attribute value of all graphical elements, while a
         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Size(TextLab)
         value.
      }
   }
}
\sstroutine{
   SizeGuess
}{
   The expected size of the KeyMap
}{
   \sstdescription{
      This is attribute gives an estimate of the number of entries that
      will be stored in the \htmlref{KeyMap}{KeyMap}. It is used to tune the internal
      properties of the KeyMap for speed and efficiency. A larger value
      will result in faster access at the expense of increased memory
      requirements. However if the SizeGuess value is much larger than
      the actual size of the KeyMap, then there will be little, if any,
      speed gained by making the SizeGuess even larger. The default value
      is 300.

      The value of this attribute can only be changed if the KeyMap is
      empty. Its value can be set conveniently when creating the KeyMap.
      An error will be reported if an attempt is made to set or clear the
      attribute when the KeyMap contains any entries.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         All KeyMaps have this attribute.
      }
   }
}
\sstroutine{
   Skip
}{
   Skip irrelevant data?
}{
   \sstdescription{
      This is a boolean attribute which indicates whether the \htmlref{Object}{Object}
      data being read through a \htmlref{Channel}{Channel} are inter-mixed with other,
      irrelevant, external data.

      If Skip is zero (the default), then the source of input data is
      expected to contain descriptions of AST Objects and comments and
      nothing else (if anything else is read, an error will
      result). If Skip is non-zero, then any non-Object data
      encountered between Objects will be ignored and simply skipped
      over in order to reach the next Object.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         All Channels have this attribute.
      }
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         The FitsChan class sets the default value of this attribute
         to 1, so that all irrelevant FITS headers will normally be
         ignored.
      }
   }
}
\sstroutine{
   SkyRef(axis)
}{
   Position defining the offset coordinate system
}{
   \sstdescription{
      This attribute allows a \htmlref{SkyFrame}{SkyFrame} to represent offsets, rather than
      absolute axis values, within the coordinate system specified by the
      \htmlref{System}{System} attribute. If supplied, SkyRef should be set to hold the
      longitude and latitude of a point within the coordinate system
      specified by the System attribute. The coordinate system represented
      by the SkyFrame will then be rotated in order to put the specified
      position at either the pole or the origin of the new coordinate system
      (as indicated by the \htmlref{SkyRefIs}{SkyRefIs} attribute). The orientation of the
      modified coordinate system is then controlled using the SkyRefP
      attribute.

      If an integer axis index is included in the attribute name (e.g.
      \texttt{"} SkyRef(1)\texttt{"} ) then the attribute value should be supplied as a single
      floating point axis value, in radians, when setting a value for the
      attribute, and will be returned in the same form when getting the value
      of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"}
      or \texttt{"} 2\texttt{"}  (the values to use for longitude and latitude axes are
      given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes).

      If no axis index is included in the attribute name (e.g. \texttt{"} SkyRef\texttt{"} ) then
      the attribute value should be supplied as a character string
      containing two formatted axis values (an axis 1 value followed by a
      comma, followed by an axis 2 value). The same form
      will be used when getting the value of the attribute.

      The default values for SkyRef are zero longitude and zero latitude.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the System attribute of the SkyFrame is changed, any position
         given for SkyRef is transformed into the new System.

         \sstitem
         If a value has been assigned to SkyRef attribute, then
         the default values for certain attributes are changed as follows:
         the default axis Labels for the SkyFrame are modified by appending
         \texttt{"}  offset\texttt{"}  to the end, the default axis Symbols for the SkyFrame are
         modified by prepending the character \texttt{"} D\texttt{"}  to the start, and the
         default title is modified by replacing the projection information by the
         origin information.
      }
   }
   \sstdiytopic{
      Aligning SkyFrames with Offset Coordinate Systems
   }{
      The offset coordinate system within a SkyFrame should normally be
      considered as a superficial \texttt{"} re-badging\texttt{"}  of the axes of the coordinate
      system specified by the System attribute - it merely provides an
      alternative numerical \texttt{"} label\texttt{"}  for each position in the System coordinate
      system. The SkyFrame retains full knowledge of the celestial coordinate
      system on which the offset coordinate system is based (given by the
      System attribute). For instance, the SkyFrame retains knowledge of the
      way that one celestial coordinate system may \texttt{"} drift\texttt{"}  with respect to
      another over time. Normally, if you attempt to align two SkyFrames (e.g.
      using the \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame} routine),
      the effect of any offset coordinate system defined in either SkyFrame
      will be removed, resulting in alignment being performed in the
      celestial coordinate system given by the \htmlref{AlignSystem}{AlignSystem} attribute.
      However, by setting the \htmlref{AlignOffset}{AlignOffset} attribute ot a non-zero value, it
      is possible to change this behaviour so that the effect of the offset
      coordinate system is not removed when aligning two SkyFrames.
   }
}
\sstroutine{
   SkyRefIs
}{
   Selects the nature of the offset coordinate system
}{
   \sstdescription{
      This attribute controls how the values supplied for the SkyRef and
      SkyRefP attributes are used. These three attributes together allow
      a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin
      or pole within the coordinate system specified by the \htmlref{System}{System} attribute,
      rather than absolute axis values. SkyRefIs can take one of the
      case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"}  or \texttt{"} Ignored\texttt{"} .

      If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system
      represented by the SkyFrame is modified to put the origin of longitude
      and latitude at the position specified by the SkyRef attribute.

      If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented
      by the SkyFrame is modified to put the north pole at the position
      specified by the SkyRef attribute.

      If SkyRefIs is set to \texttt{"} Ignored\texttt{"}  (the default), then any value set for the
      SkyRef attribute is ignored, and the SkyFrame represents the coordinate
      system specified by the System attribute directly without any rotation.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   SkyRefP(axis)
}{
   Position on primary meridian of offset coordinate system
}{
   \sstdescription{
      This attribute is used to control the orientation of the offset
      coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used,
      it should be set to hold the longitude and latitude of a point within
      the coordinate system specified by the \htmlref{System}{System} attribute. The offset
      coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in
      order to put the position supplied for SkyRefP on the zero longitude
      meridian. This rotation is about an axis from the centre of the
      celestial sphere to the point specified by the SkyRef attribute.
      The default value for SkyRefP is usually the north pole (that is, a
      latitude of $+$90 degrees in the coordinate system specified by the System
      attribute). The exception to this is if the SkyRef attribute is
      itself set to either the north or south pole. In these cases the
      default for SkyRefP is the origin (that is, a (0,0) in the coordinate
      system specified by the System attribute).

      If an integer axis index is included in the attribute name (e.g.
      \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single
      floating point axis value, in radians, when setting a value for the
      attribute, and will be returned in the same form when getting the value
      of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"}
      or \texttt{"} 2\texttt{"}  (the values to use for longitude and latitude axes are
      given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes).

      If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then
      the attribute value should be supplied as a character string
      containing two formatted axis values (an axis 1 value followed by a
      comma, followed by an axis 2 value). The same form
      will be used when getting the value of the attribute.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If the position given by the SkyRef attribute defines the origin
         of the offset coordinate system (that is, if the SkyRefIs attribute
         is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations
         which will put the supplied SkyRefP position on the zero longitude
         meridian. The orientation which is actually used is the one which
         gives the SkyRefP position a positive latitude in the offset coordinate
         system (the other possible orientation would give the SkyRefP position
         a negative latitude).

         \sstitem
         An error will be reported if an attempt is made to use a
         SkyRefP value which is co-incident with SkyRef or with the point
         diametrically opposite to SkyRef on the celestial sphere. The
         reporting of this error is deferred until the SkyRef and SkyRefP
         attribute values are used within a calculation.

         \sstitem
         If the System attribute of the SkyFrame is changed, any position
         given for SkyRefP is transformed into the new System.
      }
   }
}
\sstroutine{
   SkyTol
}{
   The smallest significant shift in sky coordinates
}{
   \sstdescription{
      This attribute indicates the accuracy of the axis values that will
      be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two
      positions within the SkyFrame is smaller than the value of SkyTol,
      then the two positions will (for the puposes indicated below) be
      considered to be co-incident.

      This value is used only when constructing the \htmlref{Mapping}{Mapping} between
      two different SkyFrames (for instance, when calling
      \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame}).
      If the transformation between the two SkyFrames causes positions to
      shift by less than SkyTol arc-seconds, then the transformation is
      replaced by a \htmlref{UnitMap}{UnitMap}.  This could in certain circumatances allow
      major simplifications to be made to the transformation between
      any pixel grids associated with the two SkyFrames (for instance, if
      each SkyFrame is part of the WCS \htmlref{FrameSet}{FrameSet} associated with an image).

      A common case is when two SkyFrames use the FK5 system, but have
      slightly different \htmlref{Epoch}{Epoch} values. If the \htmlref{AlignSystem}{AlignSystem} attribute has
      its default value of \texttt{"} ICRS\texttt{"} , then the transformation between the
      two SkyFrames will include a very small rotation (FK5 rotates with
      respect to ICRS as a rate of about 0.0005 arc-seconds per year). In
      most circumstances such a small rotation is insignificant. Setting
      SkyTol to some suitably small non-zero value will cause this
      rotation to be ignored, allowing much simpler transformations to
      be used.

      The test to determine the shift introduced by transforming between
      the two SkyFrames is performed by transforming a set of 14 position
      spread evenly over the whole sky. The largest shift produced at any
      of these 14 positions is compared to the value of SkyTol.

      The SkyTol value is in units of arc-seconds, and the default value
      is 0.001.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         SkyFrame
      }{
         All SkyFrames have this attribute.
      }
   }
}
\sstroutine{
   SortBy
}{
   Determines how keys are sorted in a KeyMap
}{
   \sstdescription{
      This attribute determines the order in which keys are returned by the
      \htmlref{astMapKey}{astMapKey}
      function. It may take the following values (the default is \texttt{"} None\texttt{"} ):

      \sstitemlist{

         \sstitem
         \texttt{"} None\texttt{"} : The keys are returned in an arbitrary order. This is the
         fastest method as it avoids the need for a sorted list of keys to
         be maintained and used.

         \sstitem
         \texttt{"} AgeDown\texttt{"} : The keys are returned in the order in which values were
         stored in the \htmlref{KeyMap}{KeyMap}, with the key for the most recent value being
         returned last. If the value of an existing entry is changed, it goes
         to the end of the list.

         \sstitem
         \texttt{"} AgeUp\texttt{"} : The keys are returned in the order in which values were
         stored in the KeyMap, with the key for the most recent value being
         returned first. If the value of an existing entry is changed, it goes
         to the top of the list.

         \sstitem
         \texttt{"} KeyAgeDown\texttt{"} : The keys are returned in the order in which they
         were originally stored in the KeyMap, with the most recent key being
         returned last. If the value of an existing entry is changed, its
         position in the list does not change.

         \sstitem
         \texttt{"} KeyAgeUp\texttt{"} : The keys are returned in the order in which they
         were originally stored in the KeyMap, with the most recent key being
         returned first. If the value of an existing entry is changed, its
         position in the list does not change.

         \sstitem
         \texttt{"} KeyDown\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"}
         being returned last.

         \sstitem
         \texttt{"} KeyUp\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"}
         being returned first.
      }
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         KeyMap
      }{
         All KeyMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If a new value is assigned to SortBy (or if SortBy is cleared),
         all entries currently in the KeyMap are re-sorted according to the
         new SortBy value.
      }
   }
}
\sstroutine{
   SourceFile
}{
   Input file from which to read data
}{
   \sstdescription{
      This attribute specifies the name of a file from which the \htmlref{Channel}{Channel}
      should read data. If specified it is used in preference to any source
      function specified when the Channel was created.

      Assigning a new value to this attribute will cause any previously
      opened SourceFile to be closed. The first subsequent call to
      \htmlref{astRead}{astRead}
      will attempt to open the new file (an error will be reported if the
      file cannot be opened), and read data from it. All subsequent call to
      astRead
      will read data from the new file, until the SourceFile attribute is
      cleared or changed.

      Clearing the attribute causes any open SourceFile to be closed. All
      subsequent data reads will use the source function specified when the
      Channel was created, or will read from standard input if no source
      function was specified.

      If no value has been assigned to SourceFile, a null string will be
      returned if an attempt is made to get the attribute value.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{FitsChan}{FitsChan}
      }{
         In the case of a FitsChan, the specified SourceFile supplements
         the source function specified when the FitsChan was created,
         rather than replacing the source function. The source file
         should be a text file (not a FITS file) containing one header per
         line. When a value is assigned to SourceFile, the file is opened
         and read immediately, and all headers read from the file are
         appended to the end of any header already in the FitsChan. The file
         is then closed. Clearing the SourceFile attribute has no further
         effect, other than nullifying the string (i.e. the file name)
         associated with the attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Any open SourceFile is closed when the Channel is deleted.

         \sstitem
         If the Channel is copied or dumped
         (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow})
         the SourceFile attribute is left in a cleared state in the output
         Channel (i.e. the value of the SourceFile attribute is not copied).
      }
   }
}
\sstroutine{
   SourceSys
}{
   Spectral system in which the source velocity is stored
}{
   \sstdescription{
      This attribute identifies the spectral system in which the
      \htmlref{SourceVel}{SourceVel} attribute value (the source velocity) is supplied and
      returned. It can be one of the following:

      \sstitemlist{

         \sstitem
            \texttt{"} VRAD\texttt{"}  or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s)

         \sstitem
            \texttt{"} VOPT\texttt{"}  or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s)

         \sstitem
            \texttt{"} ZOPT\texttt{"}  or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless)

         \sstitem
            \texttt{"} BETA\texttt{"} : Beta factor (dimensionless)

         \sstitem
            \texttt{"} VELO\texttt{"}  or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s)

      }
      When setting a new value for the SourceVel attribute, the source
      velocity should be supplied in the spectral system indicated
      by this attribute. Likewise, when getting the value of the SourceVel
      attribute, the velocity will be returned in this spectral system.

      If the value of SourceSys is changed, the value stored for SourceVel
      will be converted from the old to the new spectral systems.

      The default value is \texttt{"} VELO\texttt{"}  (apparent radial velocity).
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   SourceVRF
}{
   Rest frame in which the source velocity is stored
}{
   \sstdescription{
      This attribute identifies the rest frame in which the source
      velocity or redshift is stored (the source velocity or redshift is
      accessed using attribute \htmlref{SourceVel}{SourceVel}). When setting a new value for the
      SourceVel attribute, the source velocity or redshift should be supplied
      in the rest frame indicated by this attribute. Likewise, when getting
      the value of the SourceVel attribute, the velocity or redshift will be
      returned in this rest frame.

      If the value of SourceVRF is changed, the value stored for SourceVel
      will be converted from the old to the new rest frame.

      The values which can be supplied are the same as for the \htmlref{StdOfRest}{StdOfRest}
      attribute (except that SourceVRF cannot be set to \texttt{"} Source\texttt{"} ). The
      default value is \texttt{"} Helio\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   SourceVel
}{
   The source velocity
}{
   \sstdescription{
      This attribute (together with \htmlref{SourceSys}{SourceSys}, \htmlref{SourceVRF}{SourceVRF}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec})
      defines the \texttt{"} Source\texttt{"}  standard of rest (see attribute \htmlref{StdOfRest}{StdOfRest}). This is
      a rest frame which is moving towards the position given by RefRA and
      RefDec at a  velocity given by SourceVel. A positive value means
      the source is moving away from the observer. When a new value is
      assigned to this attribute, the supplied value is assumed to refer
      to the spectral system specified by the SourceSys attribute. For
      instance, the SourceVel value may be supplied as a radio velocity, a
      redshift, a beta factor, etc. Similarly, when the current value of
      the SourceVel attribute is obtained, the returned value will refer
      to the spectral system specified by the SourceSys value. If the
      SourceSys value is changed, any value previously stored for the SourceVel
      attribute will be changed automatically from the old spectral system
      to the new spectral system.

      When setting a value for SourceVel, the value should be supplied in the
      rest frame specified by the SourceVRF attribute. Likewise, when getting
      the value of SourceVel, it will be returned in the rest frame specified
      by the SourceVRF attribute.

      The default SourceVel value is zero.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         All SpecFrames have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         It is important to set an appropriate value for SourceVRF and
         SourceSys before setting a value for SourceVel. If a new value is later
         set for SourceVRF or SourceSys, the value stored for SourceVel will
         simultaneously be changed to the new standard of rest or spectral
         system.
      }
   }
}
\sstroutine{
   SpecOrigin
}{
   The zero point for SpecFrame axis values
}{
   \sstdescription{
      This specifies the origin from which all spectral values are measured.
      The default value (zero) results in the \htmlref{SpecFrame}{SpecFrame} describing
      absolute spectral values in the system given by the \htmlref{System}{System} attribute
      (e.g. frequency, velocity, etc). If a SpecFrame is to be used to
      describe offset from some origin, the SpecOrigin attribute
      should be set to hold the required origin value. The SpecOrigin value
      stored inside the SpecFrame structure is modified whenever SpecFrame
      attribute values are changed so that it refers to the original spectral
      position.

      When setting a new value for this attribute, the supplied value is assumed
      to be in the system, units and standard of rest described by the SpecFrame.
      Likewise, when getting the value of this attribute, the value is returned
      in the system, units and standard of rest described by the SpecFrame. If
      any of these attributes are changed, then any previously stored SpecOrigin
      value will also be changed so that refers to the new system, units or
      standard of rest.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         SpecFrame
      }{
         All SpecFrames have this attribute.
      }
   }
}
\sstroutine{
   SpecVal
}{
   The spectral position at which flux values are measured
}{
   \sstdescription{
      This attribute specifies the spectral position (frequency, wavelength,
      etc.), at which the values described by the \htmlref{FluxFrame}{FluxFrame} are measured.
      It is used when determining the \htmlref{Mapping}{Mapping} between between FluxFrames.

      The default value and spectral system used for this attribute are
      both specified when the FluxFrame is created.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         FluxFrame
      }{
         All FluxFrames have this attribute.
      }
   }
}
\sstroutine{
   StcsArea
}{
   Return the CoordinateArea component when reading an STC-S document?
}{
   \sstdescription{
      This is a boolean attribute which controls what is returned
      by the
      \htmlref{astRead}{astRead}
      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
      If StcsArea is set non-zero (the default), then a \htmlref{Region}{Region}
      representing the STC CoordinateArea will be returned by
      astRead.
      If StcsArea is set to zero, then the STC CoordinateArea
      will not be returned.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         StcsChan
      }{
         All StcsChans have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} can be used to
         specify other Objects to be returned by
         astRead.
         If more than one of these attributes is set non-zero, then the
         actual \htmlref{Object}{Object} returned by
         astRead
         will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this
         case, the Region representing the STC CoordinateArea will be
         stored in the returned KeyMap using the key \texttt{"} AREA\texttt{"} . If StcsArea
         is the only attribute to be set non-zero, then the Object returned by
         astRead
         will be the CoordinateArea Region itself.

         \sstitem
         The class of Region used to represent the CoordinateArea for each
         STC-S sub-phrase is determined by the first word in the
         sub-phrase (the \texttt{"} sub-phrase identifier\texttt{"} ). The individual sub-phrase
         Regions are combined into a single \htmlref{Prism}{Prism}, which is then simplified
         using \htmlref{astSimplify}{astSimplify}
         to form the returned region.

         \sstitem
         Sub-phrases that represent a single value ( that is, have
         identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"}  or \texttt{"} Redshift\texttt{"}  ) are
         considered to be be part of the STC CoordinateArea component.

         \sstitem
         The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have
         its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no
         start time is specified by the sub-phrase, then the stop time will be
         used instead. If no stop time is specified by the sub-phrase, then
         the single time value specified in the sub-phrase will be used
         instead. Subsequently clearing the TimeOrigin attribute (or setting
         its value to zero) will cause the TimeFrame to reprsent absolute times.

         \sstitem
         The \htmlref{Epoch}{Epoch} attribute for the returned Region is set in the same
         way as the TimeOrigin attribute (see above).
      }
   }
}
\sstroutine{
   StcsCoords
}{
   Return the Coordinates component when reading an STC-S document?
}{
   \sstdescription{
      This is a boolean attribute which controls what is returned
      by the
      \htmlref{astRead}{astRead}
      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
      If StcsCoords is set non-zero, then a \htmlref{PointList}{PointList}
      representing the STC Coordinates will be returned by
      astRead.
      If StcsCoords is set to zero (the default), then the STC
      Coordinates will not be returned.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         StcsChan
      }{
         All StcsChans have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Other attributes such as \htmlref{StcsArea}{StcsArea} and \htmlref{StcsProps}{StcsProps} can be used to
         specify other Objects to be returned by
         astRead.
         If more than one of these attributes is set non-zero, then the
         actual \htmlref{Object}{Object} returned by
         astRead
         will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this
         case, the PointList representing the STC Coordinates will be
         stored in the returned KeyMap using the key \texttt{"} COORDS\texttt{"} . If StcsCoords
         is the only attribute to be set non-zero, then the Object returned by
         astRead
         will be the Coordinates PointList itself.

         \sstitem
         The Coordinates component is specified by the additional axis
         values embedded within the body of each STC-S sub-phrase that
         represents an extended area. Sub-phrases that represent a single
         value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"}
         or \texttt{"} Redshift\texttt{"}  ) are not considered to be be part of the STC
         Coordinates component.

         \sstitem
         If the STC-S documents does not contain a Coordinates component,
         then a NULL object pointer
         will be returned by
         astRead
         if the Coordinates component is the only object being returned. If
         other objects are also being returned (see attributes StcsProps and
         StcsArea), then the returned KeyMap will contain a \texttt{"} COORDS\texttt{"}  key
         only if the Coordinates component is read succesfully.

         \sstitem
         The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have
         its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no
         start time is specified by the sub-phrase, then the stop time will be
         used instead. If no stop time is specified by the sub-phrase, then
         the single time value specified in the sub-phrase will be used
         instead. Subsequently clearing the TimeOrigin attribute (or setting
         its value to zero) will cause the TimeFrame to reprsent absolute times.

         \sstitem
         The \htmlref{Epoch}{Epoch} attribute for the returned \htmlref{Region}{Region} is set in the same
         way as the TimeOrigin attribute (see above).
      }
   }
}
\sstroutine{
   StcsLength
}{
   Controls output line length
}{
   \sstdescription{
      This attribute specifies the maximum length to use when writing out
      text through the sink function supplied when the \htmlref{StcsChan}{StcsChan} was created.
      It is ignored if the \htmlref{Indent}{Indent} attribute is zero (in which case the text
      supplied to the sink function can be of any length). The default value
      is 70.

      The number of characters in each string written out through the sink
      function will not usually be greater than the value of this attribute
      (but may be less). However, if any single word in the STC-S
      description exceeds the specified length, then the word will be
      written out as a single line.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         StcsChan
      }{
         All StcsChans have this attribute.
      }
   }
}
\sstroutine{
   StcsProps
}{
   Return all properties when reading an STC-S document?
}{
   \sstdescription{
      This is a boolean attribute which controls what is returned
      by the
      \htmlref{astRead}{astRead}
      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
      If StcsProps is set non-zero, then a \htmlref{KeyMap}{KeyMap} containing all the
      properties read from the STC-S document will be returned by
      astRead.
      If StcsProps is set to zero (the default), then the properties
      will not be returned.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         StcsChan
      }{
         All StcsChans have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsArea}{StcsArea} can be used to
         specify other Objects to be returned by
         astRead.
         If more than one of these attributes is set non-zero, then the
         actual \htmlref{Object}{Object} returned by
         astRead
         will be a KeyMap containing the requested Objects. In this
         case, the properties KeyMap will be stored in the returned KeyMap
         using the key \texttt{"} PROPS\texttt{"} . If StcsProps is the only attribute to be
         set non-zero, then the Object returned by
         astRead
         will be the properties KeyMap itself.

         \sstitem
         The KeyMap containing the properties will have entries for one or
         more of the following keys: \texttt{"} TIME\_PROPS\texttt{"} , \texttt{"} SPACE\_PROPS\texttt{"} , \texttt{"} SPECTRAL\_PROPS\texttt{"}
         and \texttt{"} REDSHIFT\_PROPS\texttt{"} . Each of these entries will be another KeyMap
         containing the properties of the corresponding STC-S sub-phrase.
      }
   }
}
\sstroutine{
   StdOfRest
}{
   Standard of rest
}{
   \sstdescription{
      This attribute identifies the standard of rest to which the spectral
      axis values of a \htmlref{SpecFrame}{SpecFrame} refer, and may take any of the values
      listed in the \texttt{"} Standards of Rest\texttt{"}  section (below).

      The default StdOfRest value is \texttt{"} Helio\texttt{"} .
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         SpecFrame
      }{
         All SpecFrames have this attribute.
      }
   }
   \sstdiytopic{
      Standards of Rest
   }{
      The SpecFrame class supports the following StdOfRest values (all are
      case-insensitive):

      \sstitemlist{

         \sstitem
         \texttt{"} Topocentric\texttt{"} , \texttt{"} Topocent\texttt{"}  or \texttt{"} Topo\texttt{"} : The observers rest-frame (assumed
         to be on the surface of the earth). Spectra recorded in this standard of
         rest suffer a Doppler shift which varies over the course of a day
         because of the rotation of the observer around the axis of the earth.
         This standard of rest must be qualified using the \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon},
         \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes.

         \sstitem
         \texttt{"} Geocentric\texttt{"} , \texttt{"} Geocentr\texttt{"}  or \texttt{"} Geo\texttt{"} : The rest-frame of the earth centre.
         Spectra recorded in this standard of rest suffer a Doppler shift which
         varies over the course of a year because of the rotation of the earth
         around the Sun. This standard of rest must be qualified using the Epoch,
         RefRA and RefDec attributes.

         \sstitem
         \texttt{"} Barycentric\texttt{"} , \texttt{"} Barycent\texttt{"}  or \texttt{"} Bary\texttt{"} : The rest-frame of the solar-system
         barycentre. Spectra recorded in this standard of rest suffer a Doppler
         shift which depends both on the velocity of the Sun through the Local
         Standard of Rest, and on the movement of the planets through the solar
         system. This standard of rest must be qualified using the Epoch, RefRA
         and RefDec attributes.

         \sstitem
         \texttt{"} Heliocentric\texttt{"} , \texttt{"} Heliocen\texttt{"}  or \texttt{"} Helio\texttt{"} : The rest-frame of the Sun.
         Spectra recorded in this standard of rest suffer a Doppler shift which
         depends on the velocity of the Sun through the Local Standard of Rest.
         This standard of rest must be qualified using the RefRA and RefDec
         attributes.

         \sstitem
         \texttt{"} LSRK\texttt{"} , \texttt{"} LSR\texttt{"} : The rest-frame of the kinematical Local Standard of
         Rest. Spectra recorded in this standard of rest suffer a Doppler shift
         which depends on the velocity of the kinematical Local Standard of Rest
         through the galaxy. This standard of rest must be qualified using the
         RefRA and RefDec attributes.

         \sstitem
         \texttt{"} LSRD\texttt{"} : The rest-frame of the dynamical Local Standard of Rest. Spectra
         recorded in this standard of rest suffer a Doppler shift which depends
         on the velocity of the dynamical Local Standard of Rest through the
         galaxy.  This standard of rest must be qualified using the RefRA and
         RefDec attributes.

         \sstitem
         \texttt{"} Galactic\texttt{"} , \texttt{"} Galactoc\texttt{"}  or \texttt{"} Gal\texttt{"} : The rest-frame of the galactic centre.
         Spectra recorded in this standard of rest suffer a Doppler shift which
         depends on the velocity of the galactic centre through the local group.
         This standard of rest must be qualified using the RefRA and RefDec
         attributes.

         \sstitem
         \texttt{"} Local\_group\texttt{"} , \texttt{"} Localgrp\texttt{"}  or \texttt{"} LG\texttt{"} : The rest-frame of the local group.
         This standard of rest must be qualified using the RefRA and RefDec
         attributes.

         \sstitem
         \texttt{"} Source\texttt{"} , or \texttt{"} src\texttt{"} : The rest-frame of the source. This standard of
         rest must be qualified using the RefRA, RefDec and \htmlref{SourceVel}{SourceVel} attributes.

      }
      Where more than one alternative \htmlref{System}{System} value is shown above, the
      first of these will be returned when an enquiry is made.
   }
}
\sstroutine{
   Strict
}{
   Report an error if any unexpeted data items are found?
}{
   \sstdescription{
      This is a boolean attribute which indicates whether a warning
      rather than an error should be issed for insignificant conversion
      problems. If it is set non-zero, then fatal errors are issued
      instead of warnings, resulting in the
      AST error status being set.
      If Strict is zero (the default), then execution continues after minor
      conversion problems, and a warning message is added to the \htmlref{Channel}{Channel}
      structure. Such messages can be retrieved using the
      \htmlref{astWarnings}{astWarnings}
      function.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Channel
      }{
         All Channels have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This attribute was introduced in AST version 5.0. Prior to this
         version of AST unexpected data items read by a basic Channel always
         caused an error to be reported. So applications linked against
         versions of AST prior to version 5.0 may not be able to read \htmlref{Object}{Object}
         descriptions created by later versions of AST, if the Object\texttt{'} s class
         description has changed.
      }
   }
}
\sstroutine{
   Style(element)
}{
   Line style for a Plot element
}{
   \sstdescription{
      This attribute determines the line style used when drawing each
      element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
      separate value for each graphical element so that, for instance,
      the setting \texttt{"} Style(border)=2\texttt{"}  causes the Plot border to be drawn
      using line style 2 (which might result in, say, a dashed line).

      The range of integer line styles available and their appearance
      is determined by the underlying graphics system.  The default
      behaviour is for all graphical elements to be drawn using the
      default line style supplied by this graphics system (normally,
      this is likely to give a solid line).
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of the graphical elements available, see the
         description of the Plot class.

         \sstitem
         If no graphical element is specified, (e.g. \texttt{"} Style\texttt{"}  instead of
         \texttt{"} Style(border)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all graphical elements, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the Style(\htmlref{Border}{Border}) value.
      }
   }
}
\sstroutine{
   Symbol(axis)
}{
   Axis symbol
}{
   \sstdescription{
      This attribute specifies a short-form symbol to be used to
      represent coordinate values for a particular axis of a
      \htmlref{Frame}{Frame}. This might be used (e.g.) in algebraic expressions where
      a full description of the axis would be inappropriate. Examples
      include \texttt{"} RA\texttt{"}  and \texttt{"} Dec\texttt{"}  (for Right Ascension and Declination).

      If a Symbol value has not been set for a Frame axis, then a
      suitable default is supplied.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default Symbol value supplied by the Frame class is the
         string \texttt{"} $<$\htmlref{Domain}{Domain}$>$$<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for successive
         axes, and $<$Domain$>$ is the value of the Frame\texttt{'} s Domain
         attribute (truncated if necessary so that the final string
         does not exceed 15 characters). If no Domain value has been
         set, \texttt{"} x\texttt{"}  is used as the $<$Domain$>$ value in constructing this
         default string.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Symbol value
         (e.g. to \texttt{"} RA\texttt{"}  or \texttt{"} Dec\texttt{"} ) as appropriate for the particular
         celestial coordinate system being represented.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class re-defines the default Symbol value as
         appropriate for the particular time system being represented.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Symbol attribute of a FrameSet axis is the same as that
         of its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   System
}{
   Coordinate system used to describe positions within the domain
}{
   \sstdescription{
      In general it is possible for positions within a given physical
      domain to be described using one of several different coordinate
      systems. For instance, the \htmlref{SkyFrame}{SkyFrame} class can use galactic
      coordinates, equatorial coordinates, etc, to describe positions on
      the sky. As another example, the \htmlref{SpecFrame}{SpecFrame} class can use frequency,
      wavelength, velocity, etc, to describe a position within an
      electromagnetic spectrum. The System attribute identifies the particular
      coordinate system represented by a \htmlref{Frame}{Frame}. Each class of Frame
      defines a set of acceptable values for this attribute, as listed
      below (all are case insensitive). Where more than one alternative
      System value is shown, the first of will be returned when an
      enquiry is made.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The System attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} ,
         and may not be altered.
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The System attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} ,
         and may not be altered. In addition, the CmpFrame class allows
         the System attribute to be referenced for a component Frame by
         including the index of an axis within the required component
         Frame. For instance, \texttt{"} System(3)\texttt{"}  refers to the System attribute
         of the component Frame which includes axis 3 of the CmpFrame.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The System attribute of a FrameSet is the same as that of its
         current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
      \sstsubsection{
         SkyFrame
      }{
         The SkyFrame class supports the following System values and
         associated celestial coordinate systems:

         \sstitemlist{

            \sstitem
            \texttt{"} AZEL\texttt{"} : Horizon coordinates. The longitude axis is azimuth
            such that geographic north has an azimuth of zero and geographic
            east has an azimuth of $+$PI/2 radians. The zenith has elevation
            $+$PI/2. When converting to and from other celestial coordinate
            systems, no corrections are applied for atmospheric refraction
            or polar motion (however, a correction for diurnal aberattion is
            applied). Note, unlike most other
            celestial coordinate systems, this system is right handed. Also,
            unlike other SkyFrame systems, the AzEl system is sensitive to
            the timescale in which the \htmlref{Epoch}{Epoch} value is supplied. This is
            because of the gross diurnal rotation which this system undergoes,
            causing a small change in time to translate to a large rotation.
            When converting to or from an AzEl system, the Epoch value for
            both source and destination SkyFrames should be supplied in the
            TDB timescale. The difference between TDB and TT is between 1
            and 2 milliseconds, and so a TT value can usually be supplied in
            place of a TDB value. The TT timescale is related to TAI via
            TT = TAI $+$ 32.184 seconds.

            \sstitem
            \texttt{"} ECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the
            ecliptic and mean equinox specified by the qualifying \htmlref{Equinox}{Equinox}
            value.

            \sstitem
            \texttt{"} FK4\texttt{"} : The old FK4 (barycentric) equatorial coordinate system,
            which should be qualified by an Equinox value. The underlying
            model on which this is based is non-inertial and rotates slowly
            with time, so for accurate work FK4 coordinate systems should
            also be qualified by an Epoch value.

            \sstitem
            \texttt{"} FK4-NO-E\texttt{"}  or \texttt{"} FK4\_NO\_E\texttt{"} : The old FK4 (barycentric) equatorial
            system but without the \texttt{"} E-terms of aberration\texttt{"}  (e.g. some radio
            catalogues). This coordinate system should also be qualified by
            both an Equinox and an Epoch value.

            \sstitem
            \texttt{"} FK5\texttt{"}  or \texttt{"} EQUATORIAL\texttt{"} : The modern FK5 (barycentric) equatorial
            coordinate system. This should be qualified by an Equinox value.

            \sstitem
            \texttt{"} GALACTIC\texttt{"} : Galactic coordinates (IAU 1958).

            \sstitem
            \texttt{"} GAPPT\texttt{"} , \texttt{"} GEOCENTRIC\texttt{"}  or \texttt{"} APPARENT\texttt{"} : The geocentric apparent
            equatorial coordinate system, which gives the apparent positions
            of sources relative to the true plane of the Earth\texttt{'} s equator and
            the equinox (the coordinate origin) at a time specified by the
            qualifying Epoch value. (Note that no Equinox is needed to
            qualify this coordinate system because no model \texttt{"} mean equinox\texttt{"}
            is involved.)  These coordinates give the apparent right
            ascension and declination of a source for a specified date of
            observation, and therefore form an approximate basis for
            pointing a telescope. Note, however, that they are applicable to
            a fictitious observer at the Earth\texttt{'} s centre, and therefore
            ignore such effects as atmospheric refraction and the (normally
            much smaller) aberration of light due to the rotational velocity
            of the Earth\texttt{'} s surface.  Geocentric apparent coordinates are
            derived from the standard FK5 (J2000.0) barycentric coordinates
            by taking account of the gravitational deflection of light by
            the Sun (usually small), the aberration of light caused by the
            motion of the Earth\texttt{'} s centre with respect to the barycentre
            (larger), and the precession and nutation of the Earth\texttt{'} s spin
            axis (normally larger still).

            \sstitem
            \texttt{"} HELIOECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the
            ecliptic and mean equinox of J2000.0, in which an offset is added to
            the longitude value which results in the centre of the sun being at
            zero longitude at the date given by the Epoch attribute. Attempts to
            set a value for the Equinox attribute will be ignored, since this
            system is always referred to J2000.0.

            \sstitem
            \texttt{"} ICRS\texttt{"} : The Internation Celestial Reference System, realised
            through the Hipparcos catalogue. Whilst not an equatorial system
            by definition, the ICRS is very close to the FK5 (J2000) system
            and is usually treated as an equatorial system. The distinction
            between ICRS and FK5 (J2000) only becomes important when accuracies
            of 50 milli-arcseconds or better are required. ICRS need not be
            qualified by an Equinox value.

            \sstitem
            \texttt{"} J2000\texttt{"} : An equatorial coordinate system based on the mean
            dynamical equator and equinox of the J2000 epoch. The dynamical
            equator and equinox differ slightly from those used by the FK5
            model, and so a \texttt{"} J2000\texttt{"}  SkyFrame will differ slightly from an
            \texttt{"} FK5(Equinox=J2000)\texttt{"}  SkyFrame. The J2000 System need not be
            qualified by an Equinox value

            \sstitem
            \texttt{"} SUPERGALACTIC\texttt{"} : De Vaucouleurs Supergalactic coordinates.

            \sstitem
            \texttt{"} UNKNOWN\texttt{"} : Any other general spherical coordinate system. No
            \htmlref{Mapping}{Mapping} can be created between a pair of SkyFrames if either of the
            SkyFrames has System set to \texttt{"} Unknown\texttt{"} .

         }
         Currently, the default System value is \texttt{"} ICRS\texttt{"} . However, this
         default may change in future as new astrometric standards
         evolve. The intention is to track the most modern appropriate
         standard. For this reason, you should use the default only if
         this is what you intend (and can tolerate any associated slight
         change in future). If you intend to use the ICRS system
         indefinitely, then you should specify it explicitly.
      }
      \sstsubsection{
         SpecFrame
      }{
         The SpecFrame class supports the following System values and
         associated spectral coordinate systems (the default is \texttt{"} WAVE\texttt{"}  -
         wavelength). They are all defined in FITS-WCS paper III:

         \sstitemlist{

            \sstitem
            \texttt{"} FREQ\texttt{"} : Frequency (GHz)

            \sstitem
            \texttt{"} ENER\texttt{"}  or \texttt{"} ENERGY\texttt{"} : Energy (J)

            \sstitem
            \texttt{"} WAVN\texttt{"}  or \texttt{"} WAVENUM\texttt{"} : Wave-number (1/m)

            \sstitem
            \texttt{"} WAVE\texttt{"}  or \texttt{"} WAVELEN\texttt{"} : Vacuum wave-length (Angstrom)

            \sstitem
            \texttt{"} AWAV\texttt{"}  or \texttt{"} AIRWAVE\texttt{"} : Wave-length in air (Angstrom)

            \sstitem
            \texttt{"} VRAD\texttt{"}  or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s)

            \sstitem
            \texttt{"} VOPT\texttt{"}  or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s)

            \sstitem
            \texttt{"} ZOPT\texttt{"}  or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless)

            \sstitem
            \texttt{"} BETA\texttt{"} : Beta factor (dimensionless)

            \sstitem
            \texttt{"} VELO\texttt{"}  or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s)

         }
         The default value for the Unit attribute for each system is shown
         in parentheses. Note that the default value for the ActiveUnit flag
         is non-zero
         for a SpecFrame, meaning that changes to the Unit attribute for
         a SpecFrame will result in the SpecFrame being re-mapped within
         its enclosing FrameSet in order to reflect the change in units
         (see \htmlref{astSetActiveUnit}{astSetActiveUnit} function for further information).
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class supports the following System values and
         associated coordinate systems (the default is \texttt{"} MJD\texttt{"} ):

         \sstitemlist{

            \sstitem
            \texttt{"} MJD\texttt{"} : Modified Julian Date (d)

            \sstitem
            \texttt{"} JD\texttt{"} : Julian Date (d)

            \sstitem
            \texttt{"} JEPOCH\texttt{"} : Julian epoch (yr)

            \sstitem
            \texttt{"} BEPOCH\texttt{"} : Besselian (yr)

         }
         The default value for the Unit attribute for each system is shown
         in parentheses. Strictly, these systems should not allow changes
         to be made to the units. For instance, the usual definition of
         \texttt{"} MJD\texttt{"}  and \texttt{"} JD\texttt{"}  include the statement that the values will be in
         units of days. However, AST does allow the use of other units
         with all the above supported systems (except BEPOCH), on the
         understanding that conversion to the \texttt{"} correct\texttt{"}  units involves
         nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h,
         1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined
         in terms of tropical years of 365.2422 days, rather than the
         usual Julian year of 365.25 days. Therefore, to avoid any
         confusion, the Unit attribute is automatically cleared to \texttt{"} yr\texttt{"}  when
         a System value of BEPOCH System is selected, and an error is
         reported if any attempt is subsequently made to change the Unit
         attribute.

         Note that the default value for the ActiveUnit flag
         is non-zero
         for a TimeFrame, meaning that changes to the Unit attribute for
         a TimeFrame will result in the TimeFrame being re-mapped within
         its enclosing FrameSet in order to reflect the change in units
         (see astSetActiveUnit function for further information).
      }
      \sstsubsection{
         \htmlref{FluxFrame}{FluxFrame}
      }{
         The FluxFrame class supports the following System values and
         associated systems for measuring observed value:

         \sstitemlist{

            \sstitem
            \texttt{"} FLXDN\texttt{"} : Flux per unit frequency (W/m$\wedge$2/Hz)

            \sstitem
            \texttt{"} FLXDNW\texttt{"} : Flux per unit wavelength (W/m$\wedge$2/Angstrom)

            \sstitem
            \texttt{"} SFCBR\texttt{"} : Surface brightness in frequency units (W/m$\wedge$2/Hz/arcmin$*$$*$2)

            \sstitem
            \texttt{"} SFCBRW\texttt{"} : Surface brightness in wavelength units (W/m$\wedge$2/Angstrom/arcmin$*$$*$2)

         }
         The above lists specified the default units for each System. If an
         explicit value is set for the Unit attribute but no value is set
         for System, then the default System value is determined by the Unit
         string (if the units are not appropriate for describing any of the
         supported Systems then an error will be reported when an attempt is
         made to access the System value). If no value has been specified for
         either Unit or System, then System=FLXDN and Unit=W/m$\wedge$2/Hz are
         used.
      }
   }
}
\sstroutine{
   TabOK
}{
   Should the FITS-WCS -TAB algorithm be recognised?
}{
   \sstdescription{
      This attribute is an integer value which indicates if the \texttt{"} -TAB\texttt{"}
      algorithm, defined in FITS-WCS paper III, should be supported by
      the \htmlref{FitsChan}{FitsChan}. The default value is zero. A zero or negative value
      results in no support for -TAB axes (i.e. axes that have \texttt{"} -TAB\texttt{"}
      in their CTYPE keyword value). In this case, the
      \htmlref{astWrite}{astWrite}
      method will return zero if the write operation would required the
      use of the -TAB algorithm, and the
      \htmlref{astRead}{astRead}
      method will return
      a NULL pointer
      if any axis in the supplied header uses the -TAB algorithm.

      If TabOK is set to a non-zero positive integer, these methods will
      recognise and convert axes described by the -TAB algorithm, as
      follows:

      The astWrite
      method will generate headers that use the -TAB algorithm (if
      possible) if no other known FITS-WCS algorithm can be used to
      describe the supplied \htmlref{FrameSet}{FrameSet}. This will result in a table of
      coordinate values and index vectors being stored in the FitsChan.
      After the write operation, the calling application should check to
      see if such a table has been stored in the FitsChan. If so, the
      table should be retrived from the FitsChan using the
      \htmlref{astGetTables}{astGetTables}
      method, and the data (and headers) within it copied into a new
      FITS binary table extension. See
      astGetTables
      for more information. The FitsChan uses a \htmlref{FitsTable}{FitsTable} object to store
      the table data and headers. This FitsTable will contain the required
      columns and headers as described by FITS-WCS paper III - the
      coordinates array will be in a column named \texttt{"} COORDS\texttt{"} , and the index
      vector(s) will be in columns named \texttt{"} INDEX$<$i$>$\texttt{"}  (where $<$i$>$ is the index
      of the corresponding FITS WCS  axis). Note, index vectors are only
      created if required. The EXTNAME value will be set to the value of the
      AST\_\_TABEXTNAME constant (currently \texttt{"} WCS-TAB\texttt{"} ). The EXTVER header
      will be set to the positive integer value assigned to the TabOK
      attribute. No value will be stored for the EXTLEVEL header, and should
      therefore be considered to default to 1.

      The astRead
      method will generate a FrameSet from headers that use the -TAB
      algorithm so long as the necessary FITS binary tables are made
      available. There are two ways to do this: firstly, if the application
      knows which FITS binary tables will be needed, then it can create a
      Fitstable describing each such table and store it in the FitsChan
      (using method
      \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) before invoking the astRead method.
      Secondly, if the application does not know which FITS binary tables
      will be needed by
      astRead,
      then it can register a call-back function with the FitsChan using
      method
      \htmlref{astTableSource}{astTableSource}.
      This call-back function will be called from within
      astRead
      if and when a -TAB header is encountered. When called, its arguments
      will give the name, version and level of the FITS extension containing
      a required table. The call-back function should read this table from
      an external FITS file, and create a corresponding FitsTable which
      it should then return to
      astRead. Note, currently astRead
      can only handle -TAB headers that describe 1-dimensional (i.e.
      separable) axes.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
}
\sstroutine{
   TextLab(axis)
}{
   Draw descriptive axis labels for a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether textual labels should be drawn to describe the quantity
      being represented on each axis of a \htmlref{Plot}{Plot}. It takes a separate
      value for each physical axis of a Plot so that, for instance,
      the setting \texttt{"} TextLab(2)=1\texttt{"}  specifies that descriptive labels
      should be drawn for the second axis.

      If the TextLab value of a Plot axis is non-zero, then
      descriptive labels will be drawn for that axis, otherwise they
      will be omitted. The default behaviour is to draw descriptive
      labels if tick marks and numerical labels are being drawn around
      the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute),
      but to omit them otherwise.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The text used for the descriptive labels is derived from the
         Plot\texttt{'} s \htmlref{Label(axis)}{Label(axis)} attribute, together with its \htmlref{Unit(axis)}{Unit(axis)}
         attribute if appropriate (see the \htmlref{LabelUnits(axis)}{LabelUnits(axis)} attribute).

         \sstitem
         The drawing of numerical axis labels for a Plot (which
         indicate values on the axis) is controlled by the \htmlref{NumLab(axis)}{NumLab(axis)}
         attribute.

         \sstitem
         If no axis is specified, (e.g. \texttt{"} TextLab\texttt{"}  instead of
         \texttt{"} TextLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the TextLab(1) value.
      }
   }
}
\sstroutine{
   TextLabGap(axis)
}{
   Spacing of descriptive axis labels for a Plot
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      where descriptive axis labels are placed relative to the axes they
      describe.  It takes a separate value for each physical axis of a
      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} TextLabGap(2)=0.01\texttt{"}
      specifies where the descriptive label for the second axis should
      be drawn.

      For each axis, the TextLabGap value gives the spacing between the
      descriptive label and the edge of a box enclosing all other parts
      of the annotated grid (excluding other descriptive labels). The gap
      is measured to the nearest edge of the label (i.e. the top or the
      bottom). Positive values cause the descriptive label to be placed
      outside the bounding box, while negative values cause it to be placed
      inside.

      The TextLabGap value should be given as a fraction of the minimum
      dimension of the plotting area, the default value being $+$0.01.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If drawn, descriptive labels are always placed at the edges of
         the plotting area, even although the corresponding numerical
         labels may be drawn along axis lines in the interior of the
         plotting area (see the \htmlref{Labelling}{Labelling} attribute).

         \sstitem
         If no axis is specified, (e.g. \texttt{"} TextLabGap\texttt{"}  instead of
         \texttt{"} TextLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the TextLabGap(1) value.
      }
   }
}
\sstroutine{
   TickAll
}{
   Draw tick marks on all edges of a Plot?
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      whether tick marks should be drawn on all edges of a \htmlref{Plot}{Plot}.

      If the TickAll value of a Plot is non-zero (the default), then
      tick marks will be drawn on all edges of the Plot. Otherwise,
      they will be drawn only on those edges where the numerical and
      descriptive axis labels are drawn (see the \htmlref{Edge(axis)}{Edge(axis)}
      attribute).
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         In some circumstances, numerical labels and tick marks are
         drawn along grid lines inside the plotting area, rather than
         around its edges (see the \htmlref{Labelling}{Labelling} attribute).  In this case,
         the value of the TickAll attribute is ignored.
      }
   }
}
\sstroutine{
   TimeOrigin
}{
   The zero point for TimeFrame axis values
}{
   \sstdescription{
      This specifies the origin from which all time values are measured.
      The default value (zero) results in the \htmlref{TimeFrame}{TimeFrame} describing
      absolute time values in the system given by the \htmlref{System}{System} attribute
      (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to
      describe elapsed time since some origin, the TimeOrigin attribute
      should be set to hold the required origin value. The TimeOrigin value
      stored inside the TimeFrame structure is modified whenever TimeFrame
      attribute values are changed so that it refers to the original moment
      in time.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         TimeFrame
      }{
         All TimeFrames have this attribute.
      }
   }
   \sstdiytopic{
      Input Formats
   }{
      The formats accepted when setting a TimeOrigin value are listed
      below. They are all case-insensitive and are generally tolerant
      of extra white space and alternative field delimiters:

      \sstitemlist{

         \sstitem
         Besselian \htmlref{Epoch}{Epoch}: Expressed in decimal years, with or without
         decimal places (\texttt{"} B1950\texttt{"}  or \texttt{"} B1976.13\texttt{"}  for example).

         \sstitem
         Julian Epoch: Expressed in decimal years, with or without
         decimal places (\texttt{"} J2000\texttt{"}  or \texttt{"} J2100.9\texttt{"}  for example).

         \sstitem
         Units: An unqualified decimal value is interpreted as a value in
         the system specified by the TimeFrame\texttt{'} s System attribute, in the
         units given by the TimeFrame\texttt{'} s Unit attribute. Alternatively, an
         appropriate unit string can be appended to the end of the floating
         point value (\texttt{"} 123.4 d\texttt{"}  for example), in which case the supplied value
         is scaled into the units specified by the Unit attribute.

         \sstitem
         Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"}  for
         example).

         \sstitem
         Modified Julian Date: With or without decimal places
         (\texttt{"} MJD 54321.4\texttt{"}  for example).

         \sstitem
         Gregorian Calendar Date: With the month expressed either as an
         integer or a 3-character abbreviation, and with optional decimal
         places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"}  or
         \texttt{"} 1996-Oct-2.6\texttt{"}  for example). If no fractional part of a day is
         given, the time refers to the start of the day (zero hours).

         \sstitem
         Gregorian Date and Time: Any calendar date (as above) but with
         a fraction of a day expressed as hours, minutes and seconds
         (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"}  for example). The date and time can be
         separated by a space or by a \texttt{"} T\texttt{"}  (as used by ISO8601 format).
      }
   }
   \sstdiytopic{
      Output Format
   }{
      When enquiring TimeOrigin values, the returned formatted floating
      point value represents a value in the TimeFrame\texttt{'} s System, in the unit
      specified by the TimeFrame\texttt{'} s Unit attribute.
   }
}
\sstroutine{
   TimeScale
}{
   Time scale
}{
   \sstdescription{
      This attribute identifies the time scale to which the time axis values
      of a \htmlref{TimeFrame}{TimeFrame} refer, and may take any of the values listed in the
      \texttt{"} Time Scales\texttt{"}  section (below).

      The default TimeScale value depends on the current \htmlref{System}{System} value; if
      the current TimeFrame system is \texttt{"} Besselian epoch\texttt{"}  the default is
      \texttt{"} TT\texttt{"} , otherwise it is \texttt{"} TAI\texttt{"} . Note, if the System attribute is set
      so that the TimeFrame represents Besselian \htmlref{Epoch}{Epoch}, then an error
      will be reported if an attempt is made to set the TimeScale to
      anything other than TT.

      Note, the supported time scales fall into two groups. The first group
      containing  UT1, GMST, LAST and LMST define time in terms of the
      orientation of the earth. The second group (containing all the remaining
      time scales) define time in terms of an atomic process. Since the rate of
      rotation of the earth varies in an unpredictable way, conversion between
      two timescales in different groups relies on a value being supplied for
      the \htmlref{Dut1}{Dut1} attribute (defined by the parent \htmlref{Frame}{Frame} class). This attribute
      specifies the difference between the UT1 and UTC time scales, in seconds,
      and defaults to zero. See the documentation for the Dut1 attribute for
      further details.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         TimeFrame
      }{
         All TimeFrames have this attribute.
      }
   }
   \sstdiytopic{
      Time Scales
   }{
      The TimeFrame class supports the following TimeScale values (all are
      case-insensitive):

      \sstitemlist{

         \sstitem
         \texttt{"} TAI\texttt{"}  - International Atomic Time

         \sstitem
         \texttt{"} UTC\texttt{"}  - Coordinated Universal Time

         \sstitem
         \texttt{"} UT1\texttt{"}  - Universal Time

         \sstitem
         \texttt{"} GMST\texttt{"}  - Greenwich Mean Sidereal Time

         \sstitem
         \texttt{"} LAST\texttt{"}  - Local Apparent Sidereal Time

         \sstitem
         \texttt{"} LMST\texttt{"}  - Local Mean Sidereal Time

         \sstitem
         \texttt{"} TT\texttt{"}  - Terrestrial Time

         \sstitem
         \texttt{"} TDB\texttt{"}  - Barycentric Dynamical Time

         \sstitem
         \texttt{"} TCB\texttt{"}  - Barycentric Coordinate Time

         \sstitem
         \texttt{"} TCG\texttt{"}  - Geocentric Coordinate Time

         \sstitem
         \texttt{"} LT\texttt{"}  - Local Time (the offset from UTC is given by attribute \htmlref{LTOffset}{LTOffset})

      }
      An very informative description of these and other time scales is
      available at http://www.ucolick.org/$\sim$sla/leapsecs/timescales.html.
   }
   \sstdiytopic{
      UTC \htmlref{Warnings}{Warnings}
   }{
      UTC should ideally be expressed using separate hours, minutes and
      seconds fields (or at least in seconds for a given date) if leap seconds
      are to be taken into account. Since the TimeFrame class represents
      each moment in time using a single floating point number (the axis value)
      there will be an ambiguity during a leap second. Thus an error of up to
      1 second can result when using AST to convert a UTC time to another
      time scale if the time occurs within a leap second. Leap seconds
      occur at most twice a year, and are introduced to take account of
      variation in the rotation of the earth. The most recent leap second
      occurred on 1st January 1999. Although in the vast majority of cases
      leap second ambiguities won\texttt{'} t matter, there are potential problems in
      on-line data acquisition systems and in critical applications involving
      taking the difference between two times.
   }
}
\sstroutine{
   Title
}{
   Frame title
}{
   \sstdescription{
      This attribute holds a string which is used as a title in (e.g.)
      graphical output to describe the coordinate system which a \htmlref{Frame}{Frame}
      represents. Examples might be \texttt{"} Detector Coordinates\texttt{"}  or
      \texttt{"} Galactic Coordinates\texttt{"} .

      If a Title value has not been set for a Frame, then a suitable
      default is supplied, depending on the class of the Frame.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default supplied by the Frame class is \texttt{"} $<$n$>$-d coordinate
         system\texttt{"} , where $<$n$>$ is the number of Frame axes (\htmlref{Naxes}{Naxes}
         attribute).
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The CmpFrame class re-defines the default Title value to be
         \texttt{"} $<$n$>$-d compound coordinate system\texttt{"} , where $<$n$>$ is the number
         of CmpFrame axes (Naxes attribute).
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Title attribute of a FrameSet is the same as that of its
         current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A Frame\texttt{'} s Title is intended purely for interpretation by human
         readers and not by software.
      }
   }
}
\sstroutine{
   TitleGap
}{
   Vertical spacing for a Plot title
}{
   \sstdescription{
      This attribute controls the appearance of an annotated
      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
      where the title of a \htmlref{Plot}{Plot} is drawn.

      Its value gives the spacing between the bottom edge of the title
      and the top edge of a bounding box containing all the other parts
      of the annotated grid. Positive values cause the title to be
      drawn outside the box, while negative values cause it to be drawn
      inside.

      The TitleGap value should be given as a fraction of the minimum
      dimension of the plotting area, the default value being $+$0.05.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
      \sstsubsection{
         \htmlref{Plot3D}{Plot3D}
      }{
         The Plot3D class ignores this attributes since it does not draw
         a \htmlref{Title}{Title}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The text used for the title is obtained from the Plot\texttt{'} s Title
         attribute.
      }
   }
}
\sstroutine{
   Tol
}{
   Plotting tolerance
}{
   \sstdescription{
      This attribute specifies the plotting tolerance (or resolution)
      to be used for the graphical output produced by a \htmlref{Plot}{Plot}.  Smaller
      values will result in smoother and more accurate curves being
      drawn, but may slow down the plotting process. Conversely,
      larger values may speed up the plotting process in cases where
      high resolution is not required.

      The Tol value should be given as a fraction of the minimum
      dimension of the plotting area, and should lie in the range
      from 1.0e-7 to 1.0. By default, a value of 0.01 is used.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
}
\sstroutine{
   TolInverse
}{
   Target relative error for the iterative inverse transformation
}{
   \sstdescription{
      This attribute controls the iterative inverse transformation
      used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero.

      Its value gives the target relative error in teh axis values of
      each transformed position. Further iterations will be performed
      until the target relative error is reached, or the maximum number
      of iterations given by attribute \htmlref{NiterInverse}{NiterInverse} is reached.

      The default value is 1.0E-6.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{PolyMap}{PolyMap}
      }{
         All PolyMaps have this attribute.
      }
   }
}
\sstroutine{
   Top(axis)
}{
   Highest axis value to display
}{
   \sstdescription{
      This attribute gives the highest axis value to be displayed (for
      instance, by the \htmlref{astGrid}{astGrid} method).
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Frame}{Frame}
      }{
         The default supplied by the Frame class is to display all axis
         values, without any limit.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Top value to $+$90 degrees
         for latitude axes, and 180 degrees for co-latitude axes. The
         default for longitude axes is to display all axis values.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   TranForward
}{
   Forward transformation defined?
}{
   \sstdescription{
      This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform
      coordinates in the \texttt{"} forward\texttt{"}  direction (i.e. converting input
      coordinates into output coordinates). If this attribute is
      non-zero, the forward transformation is available. Otherwise, it
      is not.
   }
   \sstattributetype{
      Integer (boolean), read-only.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         The TranForward attribute value for a CmpMap is given by the
         boolean AND of the value for each component Mapping.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The TranForward attribute of a FrameSet applies to the
         transformation which converts between the FrameSet\texttt{'} s base
         \htmlref{Frame}{Frame} and its current Frame (as specified by the \htmlref{Base}{Base} and
         \htmlref{Current}{Current} attributes). This value is given by the boolean AND
         of the TranForward values which apply to each of the
         individual sub-Mappings required to perform this conversion.
         The TranForward attribute value for a FrameSet may therefore
         change if a new Base or Current Frame is selected.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error will result if a Mapping with a TranForward value of
         zero is used to transform coordinates in the forward direction.
      }
   }
}
\sstroutine{
   TranInverse
}{
   Inverse transformation defined?
}{
   \sstdescription{
      This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform
      coordinates in the \texttt{"} inverse\texttt{"}  direction (i.e. converting output
      coordinates back into input coordinates). If this attribute is
      non-zero, the inverse transformation is available. Otherwise, it
      is not.
   }
   \sstattributetype{
      Integer (boolean), readonly.
   }
   \sstapplicability{
      \sstsubsection{
         Mapping
      }{
         All Mappings have this attribute.
      }
      \sstsubsection{
         \htmlref{CmpMap}{CmpMap}
      }{
         The TranInverse attribute value for a CmpMap is given by the
         boolean AND of the value for each component Mapping.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The TranInverse attribute of a FrameSet applies to the
         transformation which converts between the FrameSet\texttt{'} s current
         \htmlref{Frame}{Frame} and its base Frame (as specified by the \htmlref{Current}{Current} and
         \htmlref{Base}{Base} attributes). This value is given by the boolean AND of
         the TranInverse values which apply to each of the individual
         sub-Mappings required to perform this conversion.
         The TranInverse attribute value for a FrameSet may therefore
         change if a new Base or Current Frame is selected.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         An error will result if a Mapping with a TranInverse value of
         zero is used to transform coordinates in the inverse direction.
      }
   }
}
\sstroutine{
   Unit(axis)
}{
   Physical units for formatted axis values
}{
   \sstdescription{
      This attribute contains a textual representation of the physical
      units used to represent formatted coordinate values on a particular
      axis of a \htmlref{Frame}{Frame}.
      The \htmlref{astSetActiveUnit}{astSetActiveUnit} function controls how the Unit values
      are used.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Frame
      }{
         The default supplied by the Frame class is an empty string.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         The SkyFrame class re-defines the default Unit value (e.g. to
         \texttt{"} hh:mm:ss.sss\texttt{"} ) to describe the character string returned by
         the \htmlref{astFormat}{astFormat} function when formatting coordinate values.
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         The SpecFrame class re-defines the default Unit value so that it
         is appropriate for the current \htmlref{System}{System} value. See the System
         attribute for details. An error will be reported if an attempt
         is made to use an inappropriate Unit.
      }
      \sstsubsection{
         \htmlref{TimeFrame}{TimeFrame}
      }{
         The TimeFrame class re-defines the default Unit value so that it
         is appropriate for the current System value. See the System
         attribute for details. An error will be reported if an attempt
         is made to use an inappropriate Unit (e.g. \texttt{"} km\texttt{"} ).
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The Unit attribute of a FrameSet axis is the same as that of
         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This attribute described the units used when an axis value is
         formatted into a string using
         astFormat.
         In some cases these units may be different to those used to represent
         floating point axis values within application code (for instance a
         SkyFrame always uses radians to represent floating point axis values).
         The InternalUnit attribute described the units used for floating
         point values.

         \sstitem
         When specifying this attribute by name, it should be
         subscripted with the number of the Frame axis to which it
         applies.
      }
   }
}
\sstroutine{
   UnitRadius
}{
   SphMap input vectors lie on a unit sphere?
}{
   \sstdescription{
      This is a boolean attribute which indicates whether the
      3-dimensional vectors which are supplied as input to a \htmlref{SphMap}{SphMap}
      are known to always have unit length, so that they lie on a unit
      sphere centred on the origin.

      If this condition is true (indicated by setting UnitRadius
      non-zero), it implies that a \htmlref{CmpMap}{CmpMap} which is composed of a
      SphMap applied in the forward direction followed by a similar
      SphMap applied in the inverse direction may be simplified
      (e.g. by \htmlref{astSimplify}{astSimplify}) to become a \htmlref{UnitMap}{UnitMap}. This is because the
      input and output vectors will both have unit length and will
      therefore have the same coordinate values.

      If UnitRadius is zero (the default), then although the output
      vector produced by the CmpMap (above) will still have unit
      length, the input vector may not have. This will, in general,
      change the coordinate values, so it prevents the pair of SphMaps
      being simplified.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         SphMap
      }{
         All SphMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This attribute is intended mainly for use when SphMaps are
         involved in a sequence of Mappings which project (e.g.) a
         dataset on to the celestial sphere. By regarding the celestial
         sphere as a unit sphere (and setting UnitRadius to be non-zero)
         it becomes possible to cancel the SphMaps present, along with
         associated sky projections, when two datasets are aligned using
         celestial coordinates. This often considerably improves
         performance.

         \sstitem
         Such a situations often arises when interpreting FITS data and
         is handled automatically by the \htmlref{FitsChan}{FitsChan} class.

         \sstitem
         The value of the UnitRadius attribute is used only to control
         the simplification of Mappings and has no effect on the value of
         the coordinates transformed by a SphMap. The lengths of the
         input 3-dimensional Cartesian vectors supplied are always
         ignored, even if UnitRadius is non-zero.

         \sstitem
         The value of this attribute may changed only if the SphMap
         has no more than one reference. That is, an error is reported if the
         SphMap has been cloned, either by including it within another object
         such as a CmpMap or \htmlref{FrameSet}{FrameSet} or by calling the
         \htmlref{astClone}{astClone}
         function.
      }
   }
}
\sstroutine{
   UseDefs
}{
   Use default values for unspecified attributes?
}{
   \sstdescription{
      This attribute specifies whether default values should be used
      internally for object attributes which have not been assigned a
      value explicitly. If a non-zero value (the default) is supplied for
      UseDefs, then default values will be used for attributes which have
      not explicitly been assigned a value. If zero is supplied for UseDefs,
      then an error will be reported if an attribute for which no explicit
      value has been supplied is needed internally within AST.

      Many attributes (including the UseDefs attribute itself) are unaffected
      by the setting of the UseDefs attribute, and default values will always
      be used without error for such attributes. The \texttt{"} Applicability:\texttt{"}  section
      below lists the attributes which are affected by the setting of UseDefs.

      Note, UseDefs only affects access to attributes internally within
      AST. The public accessor functions such as
      astGetC
      is unaffected by the UseDefs attribute - default values will always
      be returned if no value has been set. Application code should use the
      \htmlref{astTest}{astTest}
      function if required to determine if a value has been set for an
      attribute.
   }
   \sstattributetype{
      Integer (boolean).
   }
   \sstapplicability{
      \sstsubsection{
         \htmlref{Object}{Object}
      }{
         All Objects have this attribute, but ignore its setting except
         as described below for individual classes.
      }
      \sstsubsection{
         \htmlref{FrameSet}{FrameSet}
      }{
         The default value of UseDefs for a FrameSet is redefined to be
         the UseDefs value of its current \htmlref{Frame}{Frame}.
      }
      \sstsubsection{
         \htmlref{CmpFrame}{CmpFrame}
      }{
         The default value of UseDefs for a CmpFrame is redefined to be
         the UseDefs value of its first component Frame.
      }
      \sstsubsection{
         \htmlref{Region}{Region}
      }{
         The default value of UseDefs for a Region is redefined to be
         the UseDefs value of its encapsulated Frame.
      }
      \sstsubsection{
         Frame
      }{
         If UseDefs is zero, an error is reported when aligning Frames if the
         \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat} or \htmlref{ObsLon}{ObsLon} attribute is required but has not been
         assigned a value explicitly.
      }
      \sstsubsection{
         \htmlref{SkyFrame}{SkyFrame}
      }{
         If UseDefs is zero, an error is reported when aligning SkyFrames
         if any of the following attributes are required but have not been
         assigned a value explicitly: Epoch, \htmlref{Equinox}{Equinox}.
      }
      \sstsubsection{
         \htmlref{SpecFrame}{SpecFrame}
      }{
         If UseDefs is zero, an error is reported when aligning SpecFrames
         if any of the following attributes are required but have not been
         assigned a value explicitly: Epoch, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec}, \htmlref{RestFreq}{RestFreq},
         \htmlref{SourceVel}{SourceVel}, \htmlref{StdOfRest}{StdOfRest}.
      }
      \sstsubsection{
         \htmlref{DSBSpecFrame}{DSBSpecFrame}
      }{
         If UseDefs is zero, an error is reported when aligning DSBSpecFrames
         or when accessing the \htmlref{ImagFreq}{ImagFreq} attribute if any of the following
         attributes are required but have not been assigned a value explicitly:
         Epoch, \htmlref{DSBCentre}{DSBCentre}, \htmlref{IF}{IF}.
      }
   }
}
\sstroutine{
   Variant
}{
   Indicates which variant of the current Frame is to be used
}{
   \sstdescription{
      This attribute can be used to change the \htmlref{Mapping}{Mapping} that connects the
      current \htmlref{Frame}{Frame} to the other Frames in the \htmlref{FrameSet}{FrameSet}. By default, each
      Frame in a FrameSet is connected to the other Frames by a single
      Mapping that can only be changed by using the
      \htmlref{astRemapFrame}{astRemapFrame}
      method. However, it is also possible to associate multiple Mappings
      with a Frame, each Mapping having an identifying name. If this is
      done, the \texttt{"} Variant\texttt{"}  attribute can be set to indicate the name of
      the Mapping that is to be used with the current Frame.

      A possible (if unlikely) use-case is to create a FrameSet that can
      be used to describe the WCS of an image formed by co-adding images
      of two different parts of the sky. In such an image, each pixel contains
      flux from two points on the sky.and so the WCS for the image should
      ideally contain one pixel Frame and two SkyFrames - one describing
      each of the two co-added images. There is nothing to prevent a
      FrameSet containing two explicit SkyFrames, but the problem then arises
      of how to distinguish between them. The two primary characteristics of
      a Frame that distinguishes it from other Frames  are its class and its
      \htmlref{Domain}{Domain} attribute value. The class of a Frame cannot be changed, but we
      could in principle use two different Domain values to distinguish the
      two SkyFrames. However, in practice it is not uncommon for application
      software to assume that SkyFrames will have the default Domain value
      of \texttt{"} SKY\texttt{"} . That is, instead of searching for Frames that have a class
      of \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , such software searches for Frames that have a Domain
      of \texttt{"} SKY\texttt{"} . To alleviate this problem, it is possible to add a single
      SkyFrame to the FrameSet, but specifying two alternate Mappings to
      use with the SkyFrame. Setting the \texttt{"} Variant\texttt{"}  attribute to the name
      of one or the other of these alternate Mappings will cause the
      SkyFrame to be remapped within the FrameSet so that it uses the
      specified Mapping. The same facility can be used with any class of
      Frame, not just SkyFrames.

      To use this facility, the Frame should first be added to the
      FrameSet in the usual manner using the
      \htmlref{astAddFrame}{astAddFrame} method. By default, the Mapping supplied to astAddFrame
      is assigned a name equal to the Domain name of the Frame. To assign a
      different name to it, the
      \htmlref{astAddVariant}{astAddVariant}
      method should then be called specifying the required name and a NULL
      Mapping. The
      astAddVariant
      method should then be called repeatedly to add each required extra
      Mapping to the current Frame, supplying a unique name for each one.

      Each Frame in a FrameSet can have its own set of variant Mappings.
      To control the Mappings in use with a specific Frame, you need first
      to make it the current Frame in the FrameSet.

      The
      \htmlref{astMirrorVariants}{astMirrorVariants} function
      allows the effects of variant Mappings associated with a nominated
      Frame to be propagated to other Frames in the FrameSet.

      Once this has been done, setting a new value for the \texttt{"} Variant\texttt{"}
      attribute of a FrameSet will cause the current Frame in the
      FrameSet to be remapped to use the specified variant Mapping. An
      error will be reported if the current Frame has no variant Mapping
      with the supplied name.

      Getting the value of the \texttt{"} Variant\texttt{"}  attribute will return the name
      of the variant Mapping currently in use with the current Frame. If
      the Frame has no variant Mappings, the value will default to the
      Domain name of the current Frame.

      Clearing the \texttt{"} Variant\texttt{"}  attribute will have the effect of removing
      all variant Mappings (except for the currently selected Mapping) from
      the current Frame.

      Testing the \texttt{"} Variant\texttt{"}  attribute will return
      a non-zero value
      if the current Frame contains any variant Mappings, and
      zero
      otherwise.

      A complete list of the names associated with all the available
      variant Mappings in the current Frame can be obtained from the
      \htmlref{AllVariants}{AllVariants} attribute.

      If a Frame with variant Mappings is remapped using the
      astRemapFrame
      method, the currently selected variant Mapping is used by
      astRemapFrame
      and the other variant Mappings are removed from the Frame.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         FrameSet
      }{
         All FrameSets have this attribute.
      }
   }
}
\sstroutine{
   Warnings
}{
   Controls the issuing of warnings about various conditions
}{
   \sstdescription{
      This attribute controls the issuing of warnings about selected
      conditions when an \htmlref{Object}{Object} or keyword is read from or written to a
      \htmlref{FitsChan}{FitsChan}. The value supplied for the Warnings attribute should
      consist of a space separated list of condition names (see the
      \htmlref{AllWarnings}{AllWarnings} attribute for a list of the currently defined names).
      Each name indicates a condition which should be reported. The default
      value for Warnings is the string \texttt{"} BadKeyName BadKeyValue Tnx Zpx
      BadCel BadMat BadPV BadCTYPE\texttt{"} .

      The text of any warning will be stored within the FitsChan in the
      form of one or more new header cards with keyword ASTWARN. If
      required, applications can check the FitsChan for ASTWARN cards
      (using \htmlref{astFindFits}{astFindFits}) after the call to \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} has been
      performed, and report the text of any such cards to the user. ASTWARN
      cards will be propagated to any output header unless they are
      deleted from the FitsChan using \htmlref{astDelFits}{astDelFits}.
   }
   \sstattributetype{
      String
   }
   \sstapplicability{
      \sstsubsection{
         FitsChan
      }{
         All FitsChans have this attribute.
      }
   }
   \sstnotes{
      This attribute only controls the warnings that are to be stored as
      a set of header cards in the FitsChan as described above. It has no
      effect on the storage of warnings in the parent \htmlref{Channel}{Channel} structure.
      All warnings are stored in the parent Channel structure, from where
      they can be retrieved using the
      \htmlref{astWarnings}{astWarnings}
      function.
   }
}
\sstroutine{
   WcsAxis(lonlat)
}{
   FITS-WCS projection axes
}{
   \sstdescription{
      This attribute gives the indices of the longitude and latitude
      coordinates of the FITS-WCS projection within the coordinate
      space used by a \htmlref{WcsMap}{WcsMap}. These indices are defined when the
      WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot
      subsequently be altered.

      If \texttt{"} lonlat\texttt{"}  is 1, the index of the longitude axis is
      returned. Otherwise, if it is 2, the index of the latitude axis
      is returned.
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
}
\sstroutine{
   WcsType
}{
   FITS-WCS projection type
}{
   \sstdescription{
      This attribute specifies which type of FITS-WCS projection will
      be performed by a \htmlref{WcsMap}{WcsMap}. The value is specified when a WcsMap
      is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be
      changed.

      The values used are represented by macros with names of
      the form \texttt{"} AST\_\_XXX\texttt{"} , where \texttt{"} XXX\texttt{"}  is the (upper case) 3-character
      code used by the FITS-WCS \texttt{"} CTYPEi\texttt{"}  keyword to identify the
      projection. For example, possible values are AST\_\_TAN (for the
      tangent plane or gnomonic projection) and AST\_\_AIT (for the
      Hammer-Aitoff projection). AST\_\_TPN is an exception in that it
      is not part of the FITS-WCS standard (it represents a TAN
      projection with polynomial correction terms as defined in an early
      draft of the FITS-WCS paper).
   }
   \sstattributetype{
      Integer, read-only.
   }
   \sstapplicability{
      \sstsubsection{
         WcsMap
      }{
         All WcsMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of available projections, see the FITS-WCS paper.
      }
   }
}
\sstroutine{
   Width(element)
}{
   Line width for a Plot element
}{
   \sstdescription{
      This attribute determines the line width used when drawing each
      element of graphical output produced by a \htmlref{Plot}{Plot}.  It takes a
      separate value for each graphical element so that, for instance,
      the setting \texttt{"} Width(border)=2.0\texttt{"}  causes the Plot border to be
      drawn using a line width of 2.0. A value of 1.0 results in a
      line thickness which is approximately 0.0005 times the length of
      the diagonal of the entire display surface.

      The actual appearance of lines drawn with any particular width,
      and the range of available widths, is determined by the
      underlying graphics system.  The default behaviour is for all
      graphical elements to be drawn using the default line width
      supplied by this graphics system. This will not necessarily
      correspond to a Width value of 1.0.
   }
   \sstattributetype{
      Floating point.
   }
   \sstapplicability{
      \sstsubsection{
         Plot
      }{
         All Plots have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         For a list of the graphical elements available, see the
         description of the Plot class.

         \sstitem
         If no graphical element is specified, (e.g. \texttt{"} Width\texttt{"}  instead of
         \texttt{"} Width(border)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
         the attribute value of all graphical elements, while a \texttt{"} get\texttt{"}  or
         \texttt{"} test\texttt{"}  operation will use just the Width(\htmlref{Border}{Border}) value.
      }
   }
}
\sstroutine{
   XmlFormat
}{
   System for formatting Objects as XML
}{
   \sstdescription{
      This attribute specifies the formatting system to use when AST
      Objects are written out as XML through an \htmlref{XmlChan}{XmlChan}. It
      affects the behaviour of the \htmlref{astWrite}{astWrite} function when
      they are used to transfer any AST \htmlref{Object}{Object} to or from an external
      XML representation.

      The XmlChan class allows AST objects to be represented in the form
      of XML in several ways (conventions) and the XmlFormat attribute is
      used to specify which of these should be used. The formatting options
      available are outlined in the \texttt{"} Formats Available\texttt{"}  section below.

      By default, an XmlChan will attempt to determine which format system
      is already in use, and will set the default XmlFormat value
      accordingly (so that subsequent I/O operations adopt the same
      conventions). It does this by looking for certain critical items
      which only occur in particular formats. For details of how this
      works, see the \texttt{"} Choice of Default Format\texttt{"}  section below. If you wish
      to ensure that a particular format system is used, independently of
      any XML already read, you should set an explicit XmlFormat value
      yourself.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         XmlChan
      }{
         All XmlChans have this attribute.
      }
   }
   \sstdiytopic{
      Formats Available
   }{
      The XmlFormat attribute can take any of the following (case
      insensitive) string values to select the corresponding formatting
      system:

      \sstitemlist{

         \sstitem
         \texttt{"} NATIVE\texttt{"} : This is a direct conversion to XML of the heirarchical
         format used by a standard XML channel (and also by the NATIVE
         encoding of a \htmlref{FitsChan}{FitsChan}).

         \sstitem
         \texttt{"} QUOTED\texttt{"} : This is the same as NATIVE format except that extra
         information is included which allows client code to convert the
         XML into a form which can be read by a standard AST \htmlref{Channel}{Channel}. This
         extra information indicates which AST attribute values should be
         enclosed in quotes before being passed to a Channel.

         \sstitem
         \texttt{"} IVOA\texttt{"} : This is a format that uses an early draft of the STC-X schema
         developed by the International Virtual Observatory Alliance (IVOA -
         see \texttt{"} http://www.ivoa.net/\texttt{"} ) to describe coordinate systems, regions,
         mappings, etc. Support is limited to V1.20 described at
         \texttt{"} http://www.ivoa.net/Documents/WD/STC/STC-20050225.html\texttt{"} . Since the
         version of STC-X finally adopted by the IVOA differs in several
         significant respects from V1.20, this format is now mainly of
         historical interest. Note, the alternative \texttt{"} STC-S\texttt{"}  format (a
         simpler non-XML encoding of the STC metadata) is supported by the
         \htmlref{StcsChan}{StcsChan} class.
      }
   }
   \sstdiytopic{
      Choice of Default Format;
   }{
      If the XmlFormat attribute of an XmlChan is not set, the default
      value it takes is determined by the presence of certain critical
      items within the document most recently read using
      \htmlref{astRead}{astRead}.
      The sequence of decision used to arrive at the default value is as
      follows:

      \sstitemlist{

         \sstitem
         If the previous document read contained any elements in any of the STC
         namespaces (\texttt{"} urn:nvo-stc\texttt{"} , \texttt{"} urn:nvo-coords\texttt{"}  or \texttt{"} urn:nvo-region\texttt{"} ), then
         the default value is IVOA.

         \sstitem
         If the previous document read contained any elements in the AST
         namespace which had an associated XML attribute called \texttt{"} quoted\texttt{"} , then
         the default value is QUOTED.

         \sstitem
         Otherwise, if none of these conditions is met (as would be the
         case if no document had yet been read), then NATIVE format is
         used.

      }
      Setting an explicit value for the XmlFormat attribute always
      over-rides this default behaviour.
   }
   \sstdiytopic{
      The IVOA Format
   }{
      The IVOA support caters only for certain parts of V1.20 of the
      draft Space-Time Coordinate (STC) schema (see
      http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this
      draft has now been superceded by an officially adopted version that
      differs in several significant respects from V1.20. Consequently,
      the \texttt{"} IVOA\texttt{"}  XmlChan format is of historical interest only.

      The following points should be noted when using an XmlChan to read
      or write STC information (note, this list is currently incomplete):

      \sstitemlist{

         \sstitem
         Objects can currently only be read using this format, not written.

         \sstitem
         The AST object generated by reading an $<$STCMetadata$>$ element will
         be an instance of one of the AST \texttt{"} \htmlref{Stc}{Stc}\texttt{"}  classes: \htmlref{StcResourceProfile}{StcResourceProfile},
         \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcObsDataLocation}{StcObsDataLocation}.

         \sstitem
         When reading an $<$STCMetadata$>$ element, the axes in the returned
         AST Object will be in the order space, time, spectral, redshift,
         irrespective of the order in which the axes occur in the $<$STCMetadata$>$
         element. If the supplied $<$STCMetadata$>$ element does not contain all of
         these axes, the returned AST Object will also omit them, but the
         ordering of those axes which are present will be as stated above. If
         the spatial frame represents a celestial coordinate system the
         spatial axes will be in the order (longitude, latitude).

         \sstitem
         Until such time as the AST \htmlref{TimeFrame}{TimeFrame} is complete, a simple
         1-dimensional \htmlref{Frame}{Frame} (with \htmlref{Domain}{Domain} set to TIME) will be used to
         represent the STC $<$TimeFrame$>$ element. Consequently, most of the
         information within a $<$TimeFrame$>$ element is currently ignored.

         \sstitem
         $<$SpaceFrame$>$ elements can only be read if they describe a celestial
         longitude and latitude axes supported by the AST \htmlref{SkyFrame}{SkyFrame} class. The
         space axes will be returned in the order (longitude, latitude).

         \sstitem
         Velocities associated with SpaceFrames cannot be read.

         \sstitem
         Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element
         are currently ignored.

         \sstitem
         Any second or subsequent $<$AstroCoordSystem$>$ found within an
         STCMetaData element is ignored.

         \sstitem
         Any second or subsequent $<$AstroCoordArea$>$ found within an
         STCMetaData element is ignored.

         \sstitem
         Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored.

         \sstitem
         Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored.

         \sstitem
         $<$SpaceFrame$>$ elements can only be read if they refer to
         one of the following space reference frames: ICRS, GALACTIC\_II,
         SUPER\_GALACTIC, HEE, FK4, FK5, ECLIPTIC.

         \sstitem
         $<$SpaceFrame$>$ elements can only be read if the reference
         position is TOPOCENTER. Also, any planetary ephemeris is ignored.

         \sstitem
         Regions: there is currently no support for STC regions of type
         Sector, ConvexHull or SkyIndex.

         \sstitem
         The AST \htmlref{Region}{Region} read from a CoordInterval element is considered to
         be open if either the lo\_include or the hi\_include attribute is
         set to false.

         \sstitem
         $<$RegionFile$>$ elements are not supported.

         \sstitem
         Vertices within $<$\htmlref{Polygon}{Polygon}$>$ elements are always considered to be
         joined using great circles (that is, $<$SmallCircle$>$ elements are
         ignored).
      }
   }
}
\sstroutine{
   XmlLength
}{
   Controls output buffer length
}{
   \sstdescription{
      This attribute specifies the maximum length to use when writing out
      text through the sink function supplied when the \htmlref{XmlChan}{XmlChan} was created.

      The number of characters in each string written out through the sink
      function will not be greater than the value of this attribute (but
      may be less). A value of zero (the default) means there is no limit -
      each string can be of any length.
   }
   \sstattributetype{
      Integer.
   }
   \sstapplicability{
      \sstsubsection{
         XmlChan
      }{
         All XmlChans have this attribute.
      }
   }
}
\sstroutine{
   XmlPrefix
}{
   The namespace prefix to use when writing
}{
   \sstdescription{
      This attribute is a string which is to be used as the namespace
      prefix for all XML elements created as a result of writing an AST
      \htmlref{Object}{Object} out through an \htmlref{XmlChan}{XmlChan}. The URI associated with the namespace
      prefix is given by the symbolic constant AST\_\_XMLNS defined in
      ast.h.
      A definition of the namespace prefix is included in each top-level
      element produced by the XmlChan.

      The default value is a blank string which causes no prefix to be
      used. In this case each top-level element will set the default
      namespace to be the value of AST\_\_XMLNS.
   }
   \sstattributetype{
      String.
   }
   \sstapplicability{
      \sstsubsection{
         Object
      }{
         All Objects have this attribute.
      }
   }
}
\sstroutine{
   Zoom
}{
   ZoomMap scale factor
}{
   \sstdescription{
      This attribute holds the \htmlref{ZoomMap}{ZoomMap} scale factor, by which
      coordinate values are multiplied (by the forward transformation)
      or divided (by the inverse transformation). The default value
      is unity.

      Note that if a ZoomMap is inverted (e.g. by using \htmlref{astInvert}{astInvert}),
      then the reciprocal of this zoom factor will, in effect, be
      used.

      In general, \htmlref{Mapping}{Mapping} attributes cannot be changed after the Mapping
      has been created (the exception to this is the \htmlref{Invert}{Invert} attribute,
      which can be changed at any time). However, several of the oldest
      Mapping classes - including the ZoomMap class - were introduced
      into the AST library before this restriction was enforced. To
      reduce the chances of breaking existing software, the attributes of
      such Mappings may still be changed, but only for Mapping instances
      that have exactly one active reference. In other words, an error will
      be reported if an attempt is made to set or clear an attribute of a
      Mapping (other than the Invert attribute) if that Mapping has been
      cloned. Mappings are cloned when they are incorporated into another
      object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet}, or when the
      \htmlref{astClone}{astClone}
      function is used.
   }
   \sstattributetype{
      Double precision.
   }
   \sstapplicability{
      \sstsubsection{
         ZoomMap
      }{
         All ZoomMaps have this attribute.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         The Zoom attribute may not be set to zero.
      }
   }
}
\normalsize

\cleardoublepage
\section{\label{ss:classdescriptions}AST Class Descriptions}
\small
\sstroutine{
   Axis
}{
   Store axis information
}{
   \sstdescription{
      The Axis class is used to store information associated with a
      particular axis of a \htmlref{Frame}{Frame}. It is used internally by the AST
      library and has no constructor function. You should encounter it
      only within textual output (e.g. from \htmlref{astWrite}{astWrite}).
   }
   \sstconstructor{
      None.
   }
   \sstdiytopic{
      Inheritance
   }{
      The Axis class inherits from the \htmlref{Object}{Object} class.
   }
}
\sstroutine{
   Box
}{
   A box region with sides parallel to the axes of a Frame
}{
   \sstdescription{
      The Box class implements a \htmlref{Region}{Region} which represents a box with sides
      parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given
      range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the
      only real difference being that the Interval class allows some axis
      limits to be unspecified. Note, a Box will only look like a box if
      the Frame geometry is approximately flat. For instance, a Box centred
      close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box
      (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a
      pole).
   }
   \sstconstructor{
      \htmlref{astBox}{astBox}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Box class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The Box class does not define any new attributes beyond
      those which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      The Box class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   Channel
}{
   Basic (textual) I/O channel
}{
   \sstdescription{
      The Channel class implements low-level input/output for the AST
      library.  Writing an \htmlref{Object}{Object} to a Channel will generate a textual
      representation of that Object, and reading from a Channel will
      create a new Object from its textual representation.

      Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting text. By default, however,
      a Channel will read from standard input and write to standard
      output. Alternatively, a Channel can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.
   }
   \sstconstructor{
      \htmlref{astChannel}{astChannel}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Channel class inherits from the Object class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Objects, every
      Channel also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Comment}{Comment}: Include textual comments in output?

         \sstitem
         \htmlref{Full}{Full}: Set level of output detail

         \sstitem
         \htmlref{Indent}{Indent}: Indentation increment between objects

         \sstitem
         \htmlref{ReportLevel}{ReportLevel}: Selects the level of error reporting

         \sstitem
         \htmlref{SinkFile}{SinkFile}: The path to a file to which the Channel should write

         \sstitem
         \htmlref{Skip}{Skip}: Skip irrelevant data?

         \sstitem
         \htmlref{SourceFile}{SourceFile}: The path to a file from which the Channel should read

         \sstitem
         \htmlref{Strict}{Strict}: Generate errors instead of warnings?
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Objects, the
      following functions may also be applied to all Channels:

      \sstitemlist{

         \sstitem
         \htmlref{astWarnings}{astWarnings}: Return warnings from the previous read or write

         \sstitem
         \htmlref{astPutChannelData}{astPutChannelData}: Store data to pass to source or sink functions

         \sstitem
         \htmlref{astRead}{astRead}: Read an Object from a Channel

         \sstitem
         \htmlref{astWrite}{astWrite}: Write an Object to a Channel
      }
   }
}
\sstroutine{
   Circle
}{
   A circular or spherical region within a Frame
}{
   \sstdescription{
      The Circle class implements a \htmlref{Region}{Region} which represents a circle or
      sphere within a \htmlref{Frame}{Frame}.
   }
   \sstconstructor{
      \htmlref{astCircle}{astCircle}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Circle class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The Circle class does not define any new attributes beyond
      those which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Regions, the
      following functions may also be applied to all Circles:

      \sstitemlist{

         \sstitem
         \htmlref{astCirclePars}{astCirclePars}: Get the geometric parameters of the Circle
      }
   }
}
\sstroutine{
   CmpFrame
}{
   Compound Frame
}{
   \sstdescription{
      A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames
      (of any class) to be merged together to form a more complex
      Frame. The axes of the two component Frames then appear together
      in the resulting CmpFrame (those of the first Frame, followed by
      those of the second Frame).

      Since a CmpFrame is itself a Frame, it can be used as a
      component in forming further CmpFrames. Frames of arbitrary
      complexity may be built from simple individual Frames in this
      way.

      Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a
      Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap},
      but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region}
      (a sub-class of Frame), then the CmpFrame will use the Region as a
      Mapping when transforming values for axes described by the Region.
      Thus input axis values corresponding to positions which are outside the
      Region will result in bad output axis values.
   }
   \sstconstructor{
      \htmlref{astCmpFrame}{astCmpFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The CmpFrame class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      The CmpFrame class does not define any new attributes beyond
      those which are applicable to all Frames. However, the attributes
      of the component Frames can be accessed as if they were attributes
      of the CmpFrame. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame}
      and a \htmlref{SkyFrame}{SkyFrame}, then the CmpFrame will recognise the \texttt{"} \htmlref{Equinox}{Equinox}\texttt{"}
      attribute and forward access requests to the component SkyFrame.
      Likewise, it will recognise the \texttt{"} \htmlref{RestFreq}{RestFreq}\texttt{"}  attribute and forward
      access requests to the component SpecFrame. An axis index can
      optionally be appended to the end of any attribute name, in which
      case the request to access the attribute will be forwarded to the
      primary Frame defining the specified axis.
   }
   \sstdiytopic{
      Functions
   }{
      The CmpFrame class does not define any new functions beyond those
      which are applicable to all Frames.
   }
}
\sstroutine{
   CmpMap
}{
   Compound Mapping
}{
   \sstdescription{
      A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component
      Mappings (of any class) to be connected together to form a more
      complex Mapping. This connection may either be \texttt{"} in series\texttt{"}
      (where the first Mapping is used to transform the coordinates of
      each point and the second mapping is then applied to the
      result), or \texttt{"} in parallel\texttt{"}  (where one Mapping transforms the
      earlier coordinates for each point and the second Mapping
      simultaneously transforms the later coordinates).

      Since a CmpMap is itself a Mapping, it can be used as a
      component in forming further CmpMaps. Mappings of arbitrary
      complexity may be built from simple individual Mappings in this
      way.
   }
   \sstconstructor{
      \htmlref{astCmpMap}{astCmpMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The CmpMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The CmpMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The CmpMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   CmpRegion
}{
   A combination of two regions within a single Frame
}{
   \sstdescription{
      A CmpRegion is a \htmlref{Region}{Region} which allows two component
      Regions (of any class) to be combined to form a more complex
      Region. This combination may be performed a boolean AND, OR
      or XOR (exclusive OR) operator. If the AND operator is
      used, then a position is inside the CmpRegion only if it is
      inside both of its two component Regions. If the OR operator is
      used, then a position is inside the CmpRegion if it is inside
      either (or both) of its two component Regions. If the XOR operator
      is used, then a position is inside the CmpRegion if it is inside
      one but not both of its two component Regions. Other operators can
      be formed by negating one or both component Regions before using
      them to construct a new CmpRegion.

      The two component Region need not refer to the same coordinate
      \htmlref{Frame}{Frame}, but it must be possible for the
      \htmlref{astConvert}{astConvert}
      function to determine a \htmlref{Mapping}{Mapping} between them (an error will be
      reported otherwise when the CmpRegion is created). For instance,
      a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame}
      with a Region defined within a Galactic SkyFrame. This is
      acceptable because the SkyFrame class knows how to convert between
      these two systems, and consequently the
      astConvert
      function will also be able to convert between them. In such cases,
      the second component Region will be mapped into the coordinate Frame
      of the first component Region, and the Frame represented by the
      CmpRegion as a whole will be the Frame of the first component Region.

      Since a CmpRegion is itself a Region, it can be used as a
      component in forming further CmpRegions. Regions of arbitrary
      complexity may be built from simple individual Regions in this
      way.
   }
   \sstconstructor{
      \htmlref{astCmpRegion}{astCmpRegion}
   }
   \sstdiytopic{
      Inheritance
   }{
      The CmpRegion class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The CmpRegion class does not define any new attributes beyond those
      which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      The CmpRegion class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   DSBSpecFrame
}{
   Dual sideband spectral coordinate system description
}{
   \sstdescription{
      A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents
      positions in a spectrum obtained using a dual sideband instrument.
      Such an instrument produces a spectrum in which each point contains
      contributions from two distinctly different frequencies, one from
      the \texttt{"} lower side band\texttt{"}  (LSB) and one from the \texttt{"} upper side band\texttt{"}  (USB).
      Corresponding LSB and USB frequencies are connected by the fact
      that they are an equal distance on either side of a fixed central
      frequency known as the \texttt{"} Local Oscillator\texttt{"}  (LO) frequency.

      When quoting a position within such a spectrum, it is necessary to
      indicate whether the quoted position is the USB position or the
      corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this
      indication. Another option that the SideBand attribute provides is
      to represent a spectral position by its topocentric offset from the
      LO frequency.

      In practice, the LO frequency is specified by giving the distance
      from the LO frequency to some \texttt{"} central\texttt{"}  spectral position. Typically
      this central position is that of some interesting spectral feature.
      The distance from this central position to the LO frequency is known
      as the \texttt{"} intermediate frequency\texttt{"}  (\htmlref{IF}{IF}). The value supplied for IF can
      be a signed value in order to indicate whether the LO frequency is
      above or below the central position.
   }
   \sstconstructor{
      \htmlref{astDSBSpecFrame}{astDSBSpecFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The DSBSpecFrame class inherits from the SpecFrame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all SpecFrames, every
      DSBSpecFrame also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AlignSideBand}{AlignSideBand}: Should alignment occur between sidebands?

         \sstitem
         \htmlref{DSBCentre}{DSBCentre}: The central position of interest.

         \sstitem
         \htmlref{IF}{IF}: The intermediate frequency used to define the LO frequency.

         \sstitem
         \htmlref{ImagFreq}{ImagFreq}: The image sideband equivalent of the rest frequency.

         \sstitem
         \htmlref{SideBand}{SideBand}: Indicates which sideband the DSBSpecFrame represents.
      }
   }
   \sstdiytopic{
      Functions
   }{
      The DSBSpecFrame class does not define any new functions beyond those
      which are applicable to all SpecFrames.
   }
}
\sstroutine{
   DssMap
}{
   Map points using a Digitised Sky Survey plate solution
}{
   \sstdescription{
      The DssMap class implements a \htmlref{Mapping}{Mapping} which transforms between
      2-dimensional pixel coordinates and an equatorial sky coordinate
      system (right ascension and declination) using a Digitised Sky
      Survey (DSS) astrometric plate solution.

      The input coordinates are pixel numbers along the first and
      second dimensions of an image, where the centre of the first
      pixel is located at (1,1) and the spacing between pixel centres
      is unity.

      The output coordinates are right ascension and declination in
      radians. The celestial coordinate system used (FK4, FK5, etc.)
      is unspecified, and will usually be indicated by appropriate
      keywords in a FITS header.
   }
   \sstconstructor{
      The DssMap class does not have a constructor function.  A DssMap
      is created only as a by-product of reading a \htmlref{FrameSet}{FrameSet} (using
      \htmlref{astRead}{astRead}) from a \htmlref{FitsChan}{FitsChan} which contains FITS header cards
      describing a DSS plate solution, and whose \htmlref{Encoding}{Encoding} attribute is
      set to \texttt{"} DSS\texttt{"} . The result of such a read, if successful, is a
      FrameSet whose base and current Frames are related by a DssMap.
   }
   \sstdiytopic{
      Inheritance
   }{
      The DssMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The DssMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The DssMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Ellipse
}{
   An elliptical region within a 2-dimensional Frame
}{
   \sstdescription{
      The Ellipse class implements a \htmlref{Region}{Region} which represents a ellipse
      within a 2-dimensional \htmlref{Frame}{Frame}.
   }
   \sstconstructor{
      \htmlref{astEllipse}{astEllipse}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Ellipse class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The Ellipse class does not define any new attributes beyond
      those which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Regions, the
      following functions may also be applied to all Ellipses:

      \sstitemlist{

         \sstitem
         \htmlref{astEllipsePars}{astEllipsePars}: Get the geometric parameters of the Ellipse
      }
   }
}
\sstroutine{
   FitsChan
}{
   I/O Channel using FITS header cards to represent Objects
}{
   \sstdescription{
      A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O
      operations involving the use of FITS (Flexible Image Transport
      \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a
      description of that Object composed of FITS header cards, and
      reading from a FitsChan will create a new Object from its FITS
      header card description.

      While a FitsChan is active, it represents a buffer which may
      contain zero or more 80-character \texttt{"} header cards\texttt{"}  conforming to
      FITS conventions. Any sequence of FITS-conforming header cards
      may be stored, apart from the \texttt{"} END\texttt{"}  card whose existence is
      merely implied.  The cards may be accessed in any order by using
      the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"}
      card, to which subsequent operations apply. Searches
      based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new
      cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and
      existing ones may be deleted (\htmlref{astDelFits}{astDelFits}), extracted (\htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}),
      or changed (astSetFits$<$X$>$).

      When you create a FitsChan, you have the option of specifying
      \texttt{"} source\texttt{"}  and \texttt{"} sink\texttt{"}  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 \htmlref{SourceFile}{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 \htmlref{SinkFile}{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 \htmlref{astRead}{astRead}).

      Coordinate system information may be described using FITS header
      cards using several different conventions, termed
      \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a
      FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{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 headers).

      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
      \htmlref{astRetainFits}{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.
   }
   \sstconstructor{
      \htmlref{astFitsChan}{astFitsChan}
   }
   \sstdiytopic{
      Inheritance
   }{
      The FitsChan class inherits from the Channel class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Channels, every

      FitsChan also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AllWarnings}{AllWarnings}: A list of the available conditions

         \sstitem
         \htmlref{Card}{Card}: Index of current FITS card in a FitsChan

         \sstitem
         \htmlref{CardComm}{CardComm}: The comment of the current FITS card in a FitsChan

         \sstitem
         \htmlref{CardName}{CardName}: The keyword name of the current FITS card in a FitsChan

         \sstitem
         \htmlref{CardType}{CardType}: The data type of the current FITS card in a FitsChan

         \sstitem
         \htmlref{CarLin}{CarLin}: Ignore spherical rotations on CAR projections?

         \sstitem
         \htmlref{CDMatrix}{CDMatrix}: Use a CD matrix instead of a PC matrix?

         \sstitem
         \htmlref{Clean}{Clean}: Remove cards used whilst reading even if an error occurs?

         \sstitem
         \htmlref{DefB1950}{DefB1950}: Use FK4 B1950 as default equatorial coordinates?

         \sstitem
         \htmlref{Encoding}{Encoding}: System for encoding Objects as FITS headers

         \sstitem
         \htmlref{FitsAxisOrder}{FitsAxisOrder}: Sets the order of WCS axes within new FITS-WCS headers

         \sstitem
         \htmlref{FitsDigits}{FitsDigits}: Digits of precision for floating-point FITS values

         \sstitem
         \htmlref{Iwc}{Iwc}: Add a \htmlref{Frame}{Frame} describing Intermediate World Coords?

         \sstitem
         \htmlref{Ncard}{Ncard}: Number of FITS header cards in a FitsChan

         \sstitem
         \htmlref{Nkey}{Nkey}: Number of unique keywords in a FitsChan

         \sstitem
         \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"}  algorithm be recognised?

         \sstitem
         \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection?

         \sstitem
         \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Channels, the
      following functions may also be applied to all FitsChans:

      \sstitemlist{

         \sstitem
         \htmlref{astDelFits}{astDelFits}: Delete the current FITS card in a FitsChan

         \sstitem
         \htmlref{astEmptyFits}{astEmptyFits}: Delete all cards in a FitsChan

         \sstitem
         \htmlref{astFindFits}{astFindFits}: Find a FITS card in a FitsChan by keyword

         \sstitem
         \htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}: Get a keyword value from a FitsChan

         \sstitem
         \htmlref{astGetTables}{astGetTables}: Retrieve any FitsTables from a FitsChan

         \sstitem
         \htmlref{astPurgeWCS}{astPurgeWCS}: Delete all WCS-related cards in a FitsChan

         \sstitem
         \htmlref{astPutCards}{astPutCards}: Stores a set of FITS header card in a FitsChan

         \sstitem
         \htmlref{astPutFits}{astPutFits}: Store a FITS header card in a FitsChan

         \sstitem
         \htmlref{astPutTable}{astPutTable}: Store a single \htmlref{FitsTable}{FitsTable} in a FitsChan

         \sstitem
         \htmlref{astPutTables}{astPutTables}: Store multiple FitsTables in a FitsChan

         \sstitem
         \htmlref{astReadFits}{astReadFits}: Read cards in through the source function

         \sstitem
         \htmlref{astRemoveTables}{astRemoveTables}: Remove one or more FitsTables from a FitsChan

         \sstitem
         \htmlref{astRetainFits}{astRetainFits}: Ensure current card is retained in a FitsChan

         \sstitem
         \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}: Store a new keyword value in a FitsChan

         \sstitem
         \htmlref{astShowFits}{astShowFits}: Display the contents of a FitsChan on standard output

         \sstitem
         \htmlref{astTableSource}{astTableSource}: Register a source function for FITS table access

         \sstitem
         \htmlref{astTestFits}{astTestFits}: Test if a keyword has a defined value in a FitsChan

         \sstitem
         \htmlref{astWriteFits}{astWriteFits}: Write all cards out to the sink function

         \sstitem
         AST\_SHOWFITS: Display the contents of a FitsChan on standard output
      }
   }
}
\sstroutine{
   FitsTable
}{
   A representation of a FITS binary table
}{
   \sstdescription{
      The FitsTable class is a representation of a FITS binary table. It
      inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the
      binary data of the main table, and a \htmlref{FitsChan}{FitsChan} (encapsulated within
      the FitsTable) is used to hold the FITS header.

      Note - it is not recommended to use the FitsTable class to store
      very large tables.

      FitsTables are primarily geared towards the needs of the \texttt{"} -TAB\texttt{"}
      algorithm defined in FITS-WCS paper 2, and so do not support all
      features of FITS binary tables. In particularly, they do not
      provide any equivalent to the following features of FITS binary
      tables: \texttt{"} heap\texttt{"}  data (i.e. binary data following the main table),
      columns holding complex values, columns holding variable length
      arrays, scaled columns, column formats, columns holding bit values,
      8-byte integer values or logical values.
   }
   \sstconstructor{
      \htmlref{astFitsTable}{astFitsTable}
   }
   \sstdiytopic{
      Inheritance
   }{
      The FitsTable class inherits from the Table class.
   }
   \sstdiytopic{
      Attributes
   }{
      The FitsTable class does not define any new attributes beyond
      those which are applicable to all Tables.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Tables, the
      following functions may also be applied to all FitsTables:

      \sstitemlist{

         \sstitem
         \htmlref{astColumnNull}{astColumnNull}: Get/set the null value for a column of a FitsTable

         \sstitem
         \htmlref{astColumnSize}{astColumnSize}: Get number of bytes needed to hold a full column of data

         \sstitem
         \htmlref{astGetColumnData}{astGetColumnData}: Retrieve all the data values stored in a column

         \sstitem
         \htmlref{astGetTableHeader}{astGetTableHeader}: Get the FITS headers from a FitsTable

         \sstitem
         \htmlref{astPutColumnData}{astPutColumnData}: Store data values in a column

         \sstitem
         \htmlref{astPutTableHeader}{astPutTableHeader}: Store FITS headers within a FitsTable
      }
   }
}
\sstroutine{
   FluxFrame
}{
   Measured flux description
}{
   \sstdescription{
      A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various systems used to represent the signal level in an
      observation. The particular coordinate system to be used is specified
      by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by
      other attributes such as the units, etc (see the description of the
      System attribute for details).

      All flux values are assumed to be measured at the same frequency or
      wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is
      more appropriate for use with images rather than spectra.
   }
   \sstconstructor{
      \htmlref{astFluxFrame}{astFluxFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The FluxFrame class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      FluxFrame also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{SpecVal}{SpecVal}: The spectral position at which the flux values are measured.
      }
   }
   \sstdiytopic{
      Functions
   }{
      The FluxFrame class does not define any new functions beyond those
      which are applicable to all Frames.
   }
}
\sstroutine{
   Frame
}{
   Coordinate system description
}{
   \sstdescription{
      This class is used to represent coordinate systems. It does this
      in rather the same way that a frame around a graph describes the
      coordinate space in which data are plotted. Consequently, a
      Frame has a \htmlref{Title}{Title} (string) attribute, which describes the
      coordinate space, and contains axes which in turn hold
      information such as Label and Units strings which are used for
      labelling (e.g.) graphical output. In general, however, the
      number of axes is not restricted to two.

      Functions are available for converting Frame coordinate values
      into a form suitable for display, and also for calculating
      distances and offsets between positions within the Frame.

      Frames may also contain knowledge of how to transform to and
      from related coordinate systems.
   }
   \sstconstructor{
      \htmlref{astFrame}{astFrame}
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When used as a \htmlref{Mapping}{Mapping}, a Frame implements a unit (null)
         transformation in both the forward and inverse directions
         (equivalent to a \htmlref{UnitMap}{UnitMap}). The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attribute values are
         both equal to the number of Frame axes.
      }
   }
   \sstdiytopic{
      Inheritance
   }{
      The Frame class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      Frame also has the following attributes (if the Frame has only one
      axis, the axis specifier can be omited from the following attribute
      names):

      \sstitemlist{

         \sstitem
         \htmlref{AlignSystem}{AlignSystem}: Coordinate system used to align Frames

         \sstitem
         \htmlref{Bottom(axis)}{Bottom(axis)}: Lowest axis value to display

         \sstitem
         \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}: Number of digits of precision

         \sstitem
         \htmlref{Direction(axis)}{Direction(axis)}: Display axis in conventional direction?

         \sstitem
         \htmlref{Domain}{Domain}: Coordinate system domain

         \sstitem
         \htmlref{Dut1}{Dut1}: Difference between the UT1 and UTC timescale

         \sstitem
         \htmlref{Epoch}{Epoch}: Epoch of observation

         \sstitem
         \htmlref{Format(axis)}{Format(axis)}: Format specification for axis values

         \sstitem
         \htmlref{InternalUnit(axis)}{InternalUnit(axis)}: Physical units for unformated axis values

         \sstitem
         \htmlref{Label(axis)}{Label(axis)}: \htmlref{Axis}{Axis} label

         \sstitem
         \htmlref{MatchEnd}{MatchEnd}: Match trailing axes?

         \sstitem
         \htmlref{MaxAxes}{MaxAxes}: Maximum number of Frame axes to match

         \sstitem
         \htmlref{MinAxes}{MinAxes}: Minimum number of Frame axes to match

         \sstitem
         \htmlref{Naxes}{Naxes}: Number of Frame axes

         \sstitem
         \htmlref{NormUnit(axis)}{NormUnit(axis)}: Normalised physical units for formatted axis values

         \sstitem
         \htmlref{ObsAlt}{ObsAlt}: Geodetic altitude of observer

         \sstitem
         \htmlref{ObsLat}{ObsLat}: Geodetic latitude of observer

         \sstitem
         \htmlref{ObsLon}{ObsLon}: Geodetic longitude of observer

         \sstitem
         \htmlref{Permute}{Permute}: Permute axis order?

         \sstitem
         \htmlref{PreserveAxes}{PreserveAxes}: Preserve axes?

         \sstitem
         \htmlref{Symbol(axis)}{Symbol(axis)}: Axis symbol

         \sstitem
         \htmlref{System}{System}: Coordinate system used to describe the domain

         \sstitem
         \htmlref{Title}{Title}: Frame title

         \sstitem
         \htmlref{Top(axis)}{Top(axis)}: Highest axis value to display

         \sstitem
         \htmlref{Unit(axis)}{Unit(axis)}: Physical units for formatted axis values
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Mappings, the
      following functions may also be applied to all Frames:

      \sstitemlist{

         \sstitem
         \htmlref{astAngle}{astAngle}: Calculate the angle subtended by two points at a third point

         \sstitem
         \htmlref{astAxAngle}{astAxAngle}: Find the angle from an axis, to a line through two points

         \sstitem
         \htmlref{astAxDistance}{astAxDistance}: Calculate the distance between two axis values

         \sstitem
         \htmlref{astAxNorm}{astAxNorm}: Normalises an array of axis values

         \sstitem
         \htmlref{astAxOffset}{astAxOffset}: Calculate an offset along an axis

         \sstitem
         \htmlref{astConvert}{astConvert}: Determine how to convert between two coordinate systems

         \sstitem
         \htmlref{astDistance}{astDistance}: Calculate the distance between two points in a Frame

         \sstitem
         \htmlref{astFindFrame}{astFindFrame}: Find a coordinate system with specified characteristics

         \sstitem
         \htmlref{astFormat}{astFormat}: Format a coordinate value for a Frame axis

         \sstitem
         \htmlref{astGetActiveUnit}{astGetActiveUnit}: Determines how the Unit attribute will be used

         \sstitem
         \htmlref{astIntersect}{astIntersect}: Find the intersection between two geodesic curves

         \sstitem
         \htmlref{astMatchAxes}{astMatchAxes}: Find any corresponding axes in two Frames

         \sstitem
         \htmlref{astNorm}{astNorm}: Normalise a set of Frame coordinates

         \sstitem
         \htmlref{astOffset}{astOffset}: Calculate an offset along a geodesic curve

         \sstitem
         \htmlref{astOffset2}{astOffset2}: Calculate an offset along a geodesic curve in a 2D Frame

         \sstitem
         \htmlref{astPermAxes}{astPermAxes}: Permute the order of a Frame\texttt{'} s axes

         \sstitem
         \htmlref{astPickAxes}{astPickAxes}: Create a new Frame by picking axes from an existing one

         \sstitem
         \htmlref{astResolve}{astResolve}: Resolve a vector into two orthogonal components

         \sstitem
         \htmlref{astSetActiveUnit}{astSetActiveUnit}: Specify how the Unit attribute should be used

         \sstitem
         \htmlref{astUnformat}{astUnformat}: Read a formatted coordinate value for a Frame axis
      }
   }
}
\sstroutine{
   FrameSet
}{
   Set of inter-related coordinate systems
}{
   \sstdescription{
      A FrameSet consists of a set of one or more Frames (which
      describe coordinate systems), connected together by Mappings
      (which describe how the coordinate systems are inter-related). A
      FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair
      of these Frames (i.e. to convert between any of the coordinate
      systems which it describes).  The individual Frames are
      identified within the FrameSet by an integer index, with Frames
      being numbered consecutively from one as they are added to the
      FrameSet.

      Every FrameSet has a \texttt{"} base\texttt{"}  \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"}  Frame (which
      are allowed to be the same). Any of the Frames may be nominated
      to hold these positions, and the choice is determined by the
      values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold
      the indices of the relevant Frames.  By default, the first Frame
      added to a FrameSet is its base Frame, and the last one added is
      its current Frame.

      The base Frame describes the \texttt{"} native\texttt{"}  coordinate system of
      whatever the FrameSet is used to calibrate (e.g. the pixel
      coordinates of an image) and the current Frame describes the
      \texttt{"} apparent\texttt{"}  coordinate system in which it should be viewed
      (e.g. displayed, etc.). Any further Frames represent a library
      of alternative coordinate systems, which may be selected by
      making them current.

      When a FrameSet is used in a context that requires a Frame,
      (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current
      Frame is used. A FrameSet may therefore be used in place of its
      current Frame in most situations.

      When a FrameSet is used in a context that requires a Mapping,
      the Mapping used is the one between its base Frame and its
      current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"}
      coordinates into \texttt{"} apparent\texttt{"}  ones, and vice versa. Like any
      Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which
      has the effect of interchanging its base and current Frames and
      hence of reversing the Mapping between them.

      Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of
      Frame), either explicitly or as components within CmpFrames. In this
      case the Mapping between a pair of Frames within a FrameSet will
      include the effects of the clipping produced by any Regions included
      in the path between the Frames.
   }
   \sstconstructor{
      \htmlref{astFrameSet}{astFrameSet}
   }
   \sstdiytopic{
      Inheritance
   }{
      The FrameSet class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      FrameSet also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AllVariants}{AllVariants}: List of all variant mappings store with current Frame

         \sstitem
         \htmlref{Base}{Base}: FrameSet base Frame index

         \sstitem
         \htmlref{Current}{Current}: FrameSet current Frame index

         \sstitem
         \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet

         \sstitem
         \htmlref{Variant}{Variant}: Name of variant mapping in use by current Frame

      }
      Every FrameSet also inherits any further attributes that belong
      to its current Frame, regardless of that Frame\texttt{'} s class. (For
      example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{SkyFrame} class, is
      inherited by any FrameSet which has a SkyFrame as its current
      Frame.) The set of attributes belonging to a FrameSet may therefore
      change when a new current Frame is selected.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Frames, the
      following functions may also be applied to all FrameSets:

      \sstitemlist{

         \sstitem
         \htmlref{astAddFrame}{astAddFrame}: Add a Frame to a FrameSet to define a new coordinate
         system

         \sstitem
         \htmlref{astAddVariant}{astAddVariant}: Add a variant Mapping to the current Frame

         \sstitem
         \htmlref{astGetFrame}{astGetFrame}: Obtain a pointer to a specified Frame in a FrameSet

         \sstitem
         \htmlref{astGetMapping}{astGetMapping}: Obtain a Mapping between two Frames in a FrameSet

         \sstitem
         \htmlref{astMirrorVariants}{astMirrorVariants}: Make the current Frame mirror variant Mappings in another Frame

         \sstitem
         \htmlref{astRemapFrame}{astRemapFrame}: Modify a Frame\texttt{'} s relationship to the other Frames in a
         FrameSet

         \sstitem
         \htmlref{astRemoveFrame}{astRemoveFrame}: Remove a Frame from a FrameSet
      }
   }
}
\sstroutine{
   GrismMap
}{
   Transform 1-dimensional coordinates using a grism dispersion equation
}{
   \sstdescription{
      A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
      1-dimensional coordinates using the spectral dispersion equation
      described in FITS-WCS paper III \texttt{"} Representation of spectral
      coordinates in FITS\texttt{"} . This describes the dispersion produced by
      gratings, prisms and grisms.

      When initially created, the forward transformation of a GrismMap
      transforms input \texttt{"} grism parameter\texttt{"}  values into output wavelength
      values. The \texttt{"} grism parameter\texttt{"}  is a dimensionless value which is
      linearly related to position on the detector. It is defined in FITS-WCS
      paper III as \texttt{"} the offset on the detector from the point of intersection
      of the camera axis, measured in units of the effective local length\texttt{"} .
      The units in which wavelength values are expected or returned is
      determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and
      \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will
      also be used for the wavelength values.
   }
   \sstconstructor{
      \htmlref{astGrismMap}{astGrismMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The GrismMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      GrismMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{GrismNR}{GrismNR}: The refractive index at the reference wavelength

         \sstitem
         \htmlref{GrismNRP}{GrismNRP}: Rate of change of refractive index with wavelength

         \sstitem
         \htmlref{GrismWaveR}{GrismWaveR}: The reference wavelength

         \sstitem
         \htmlref{GrismAlpha}{GrismAlpha}: The angle of incidence of the incoming light

         \sstitem
         \htmlref{GrismG}{GrismG}: The grating ruling density

         \sstitem
         \htmlref{GrismM}{GrismM}: The interference order

         \sstitem
         \htmlref{GrismEps}{GrismEps}: The angle between the normal and the dispersion plane

         \sstitem
         \htmlref{GrismTheta}{GrismTheta}: Angle between normal to detector plane and reference ray
      }
   }
   \sstdiytopic{
      Functions
   }{
      The GrismMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Interval
}{
   A region representing an interval on one or more axes of a Frame
}{
   \sstdescription{
      The Interval class implements a \htmlref{Region}{Region} which represents upper
      and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to
      be within the region represented by the Interval, the point must
      satisfy all the restrictions placed on all the axes. The point is
      outside the region if it fails to satisfy any one of the restrictions.
      Each axis may have either an upper limit, a lower limit, both or
      neither. If both limits are supplied but are in reverse order (so
      that the lower limit is greater than the upper limit), then the
      interval is an excluded interval, rather than an included interval.

      Note, The Interval class makes no allowances for cyclic nature of
      some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box}
      should usually be used in these cases since this requires the user
      to think about suitable upper and lower limits,
   }
   \sstconstructor{
      \htmlref{astInterval}{astInterval}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Interval class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The Interval class does not define any new attributes beyond
      those which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      The Interval class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   IntraMap
}{
   Map points using a private transformation function
}{
   \sstdescription{
      The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which
      encapsulates a privately-defined coordinate transformation
      other AST Mapping. This allows you to create Mappings that
      perform any conceivable coordinate transformation.

      However, an IntraMap is intended for use within a single program
      or a private suite of software, where all programs have access
      to the same coordinate transformation functions (i.e. can be
      linked against them). IntraMaps should not normally be stored in
      datasets which may be exported for processing by other software,
      since that software will not have the necessary transformation
      functions available, resulting in an error.

      You must register any coordinate transformation functions to be
      used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap.
   }
   \sstconstructor{
      \htmlref{astIntraMap}{astIntraMap} (also see astIntraReg)
   }
   \sstdiytopic{
      Inheritance
   }{
      The IntraMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      IntraMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{IntraFlag}{IntraFlag}: IntraMap identification string
      }
   }
   \sstdiytopic{
      Functions
   }{
      The IntraMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   KeyMap
}{
   Store a set of key/value pairs
}{
   \sstdescription{
      The KeyMap class is used to store a set of values with associated keys
      which identify the values. The keys are strings. These may be case
      sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and
      trailing spaces are ignored. The value associated with a key can be
      integer (signed 4 and 2 byte, or unsigned 1 byte), floating point
      (single or double precision),
      void pointer,
      character string or AST \htmlref{Object}{Object} pointer. Each
      value can be a scalar or a one-dimensional vector. A KeyMap is
      conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an
      input into an output - the input is the key, and the output is the
      value associated with the key. However, this is only a conceptual
      similarity, and it should be noted that the KeyMap class inherits from
      the Object class rather than the Mapping class. The methods of the
      Mapping class cannot be used with a KeyMap.
   }
   \sstconstructor{
      \htmlref{astKeyMap}{astKeyMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The KeyMap class inherits from the Object class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Objects, every
      KeyMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{KeyCase}{KeyCase}: Sets the case in which keys are stored

         \sstitem
         \htmlref{KeyError}{KeyError}: \htmlref{Report}{Report} an error if the requested key does not exist?

         \sstitem
         \htmlref{SizeGuess}{SizeGuess}: The expected size of the KeyMap.

         \sstitem
         \htmlref{SortBy}{SortBy}: Determines how keys are sorted in a KeyMap.

         \sstitem
         \htmlref{MapLocked}{MapLocked}: Prevent new entries being added to the KeyMap?
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Objects, the
      following functions may also be applied to all KeyMaps:

      \sstitemlist{

         \sstitem
         \htmlref{astMapDefined}{astMapDefined}: Does a KeyMap contain a defined value for a key?

         \sstitem
         \htmlref{astMapGet0$<$X$>$}{astMapGet0$<$X$>$}: Get a named scalar entry from a KeyMap

         \sstitem
         \htmlref{astMapGet1$<$X$>$}{astMapGet1$<$X$>$}: Get a named vector entry from a KeyMap

         \sstitem
         \htmlref{astMapGetElem$<$X$>$}{astMapGetElem$<$X$>$}: Get an element of a named vector entry from a KeyMap

         \sstitem
         \htmlref{astMapHasKey}{astMapHasKey}: Does the KeyMap contain a named entry?

         \sstitem
         \htmlref{astMapKey}{astMapKey}: Return the key name at a given index in the KeyMap

         \sstitem
         \htmlref{astMapLenC}{astMapLenC}: Get the length of a named character entry in a KeyMap

         \sstitem
         \htmlref{astMapLength}{astMapLength}: Get the length of a named entry in a KeyMap

         \sstitem
         \htmlref{astMapCopy}{astMapCopy}: Copy entries from one KeyMap into another

         \sstitem
         \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$}: Add a new scalar entry to a KeyMap

         \sstitem
         \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$}: Add a new vector entry to a KeyMap

         \sstitem
         \htmlref{astMapPutElem$<$X$>$}{astMapPutElem$<$X$>$}: Puts a value into a vector entry in a KeyMap

         \sstitem
         \htmlref{astMapPutU}{astMapPutU}: Add a new entry to a KeyMap with an undefined value

         \sstitem
         \htmlref{astMapRemove}{astMapRemove}: Removed a named entry from a KeyMap

         \sstitem
         \htmlref{astMapRename}{astMapRename}: Rename an existing entry in a KeyMap

         \sstitem
         \htmlref{astMapSize}{astMapSize}: Get the number of entries in a KeyMap

         \sstitem
         \htmlref{astMapType}{astMapType}: Return the data type of a named entry in a map
      }
   }
}
\sstroutine{
   LutMap
}{
   Transform 1-dimensional coordinates using a lookup table
}{
   \sstdescription{
      A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
      1-dimensional coordinates by using linear interpolation in a
      lookup table.

      Each input coordinate value is first scaled to give the index of
      an entry in the table by subtracting a starting value (the input
      coordinate corresponding to the first table entry) and dividing
      by an increment (the difference in input coordinate value
      between adjacent table entries).

      The resulting index will usually contain a fractional part, so
      the output coordinate value is then generated by interpolating
      linearly between the appropriate entries in the table. If the
      index lies outside the range of the table, linear extrapolation
      is used based on the two nearest entries (i.e. the two entries
      at the start or end of the table, as appropriate). If either of the
      entries used for the interplation has a value of AST\_\_BAD, then the
      interpolated value is returned as AST\_\_BAD.

      If the lookup table entries increase or decrease monotonically
      (ignoring any flat sections), then the inverse transformation may
      also be performed.
   }
   \sstconstructor{
      \htmlref{astLutMap}{astLutMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The LutMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      LutMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{LutEpsilon}{LutEpsilon}: The relative error of the values in the table.

         \sstitem
         \htmlref{LutInterp}{LutInterp}: The interpolation method to use between table entries.
      }
   }
   \sstdiytopic{
      Functions
   }{
      The LutMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Mapping
}{
   Inter-relate two coordinate systems
}{
   \sstdescription{
      This class provides the basic facilities for transforming a set
      of coordinates (representing \texttt{"} input\texttt{"}  points) to give a new set
      of coordinates (representing \texttt{"} output\texttt{"}  points).  It is used to
      describe the relationship which exists between two different
      coordinate systems and to implement operations which make use of
      this (such as transforming coordinates and resampling grids of
      data).  However, the Mapping class does not have a constructor
      function of its own, as it is simply a container class for a
      family of specialised Mappings which implement particular types
      of coordinate transformation.
   }
   \sstconstructor{
      None.
   }
   \sstdiytopic{
      Inheritance
   }{
      The Mapping class inherits from the \htmlref{Object}{Object} class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Objects, every
      Mapping also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Invert}{Invert}: Mapping inversion flag

         \sstitem
         \htmlref{IsLinear}{IsLinear}: Is the Mapping linear?

         \sstitem
         \htmlref{IsSimple}{IsSimple}: Has the Mapping been simplified?

         \sstitem
         \htmlref{Nin}{Nin}: Number of input coordinates for a Mapping

         \sstitem
         \htmlref{Nout}{Nout}: Number of output coordinates for a Mapping

         \sstitem
         \htmlref{Report}{Report}: Report transformed coordinates?

         \sstitem
         \htmlref{TranForward}{TranForward}: Forward transformation defined?

         \sstitem
         \htmlref{TranInverse}{TranInverse}: Inverse transformation defined?
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Objects, the
      following functions may also be applied to all Mappings:

      \sstitemlist{

         \sstitem
         \htmlref{astDecompose}{astDecompose}: Decompose a Mapping into two component Mappings

         \sstitem
         \htmlref{astTranGrid}{astTranGrid}: Transform a grid of positions

         \sstitem
         \htmlref{astInvert}{astInvert}: Invert a Mapping

         \sstitem
         \htmlref{astLinearApprox}{astLinearApprox}: Calculate a linear approximation to a Mapping

         \sstitem
         \htmlref{astMapBox}{astMapBox}: Find a bounding box for a Mapping

         \sstitem
         \htmlref{astMapSplit}{astMapSplit}: Split a Mapping up into parallel component Mappings

         \sstitem
         \htmlref{astQuadApprox}{astQuadApprox}: Calculate a quadratic approximation to a 2D Mapping

         \sstitem
         \htmlref{astRate}{astRate}: Calculate the rate of change of a Mapping output

         \sstitem
         \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}: Rebin a region of a data grid

         \sstitem
         \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$}: Rebin a region of a sequence of data grids

         \sstitem
         \htmlref{astResample$<$X$>$}{astResample$<$X$>$}: Resample a region of a data grid

         \sstitem
         \htmlref{astRemoveRegions}{astRemoveRegions}: Remove any Regions from a Mapping

         \sstitem
         \htmlref{astSimplify}{astSimplify}: Simplify a Mapping

         \sstitem
         \htmlref{astTran1}{astTran1}: Transform 1-dimensional coordinates

         \sstitem
         \htmlref{astTran2}{astTran2}: Transform 2-dimensional coordinates

         \sstitem
         \htmlref{astTranN}{astTranN}: Transform N-dimensional coordinates

         \sstitem
         \htmlref{astTranP}{astTranP}: Transform N-dimensional coordinates held in separate arrays
      }
   }
}
\sstroutine{
   MathMap
}{
   Transform coordinates using mathematical expressions
}{
   \sstdescription{
      A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward
      and/or inverse transformation functions using arithmetic operations
      and mathematical functions similar to those available in C. The
      MathMap interprets these functions at run-time, whenever its forward
      or inverse transformation is required. Because the functions are not
      compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to
      describe coordinate transformations in a transportable manner. A
      MathMap therefore provides a flexible way of defining new types of
      Mapping whose descriptions may be stored as part of a dataset and
      interpreted by other programs.
   }
   \sstconstructor{
      \htmlref{astMathMap}{astMathMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The MathMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      MathMap also has the following attributes:
      \sstitemlist{

         \sstitem
         \htmlref{Seed}{Seed}: Random number seed

         \sstitem
         \htmlref{SimpFI}{SimpFI}: Forward-inverse MathMap pairs simplify?

         \sstitem
         \htmlref{SimpIF}{SimpIF}: Inverse-forward MathMap pairs simplify?
      }
   }
   \sstdiytopic{
      Functions
   }{
      The MathMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   MatrixMap
}{
   Map coordinates by multiplying by a matrix
}{
   \sstdescription{
      A MatrixMap is form of \htmlref{Mapping}{Mapping} which performs a general linear
      transformation. Each set of input coordinates, regarded as a
      column-vector, are pre-multiplied by a matrix (whose elements
      are specified when the MatrixMap is created) to give a new
      column-vector containing the output coordinates. If appropriate,
      the inverse transformation may also be performed.
   }
   \sstconstructor{
      \htmlref{astMatrixMap}{astMatrixMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The MatrixMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The MatrixMap class does not define any new attributes beyond
      those which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The MatrixMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   NormMap
}{
   Normalise coordinates using a supplied Frame
}{
   \sstdescription{
      The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate
      values using the
      \htmlref{astNorm}{astNorm} function
      of a supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap
      are both equal to the number of axes in the supplied Frame.

      The forward and inverse transformation of a NormMap are both
      defined but are identical (that is, they do not form a real inverse
      pair in that the inverse transformation does not undo the
      normalisation, instead it reapplies it). However, the
      \htmlref{astSimplify}{astSimplify}
      function will replace neighbouring pairs of forward and inverse
      NormMaps by a single \htmlref{UnitMap}{UnitMap}.
   }
   \sstconstructor{
      \htmlref{astNormMap}{astNormMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The NormMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The NormMap class does not define any new attributes beyond
      those which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The NormMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   NullRegion
}{
   A boundless region within a Frame
}{
   \sstdescription{
      The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}.
      If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion
      represents a Region containing no points. If the Negated attribute of
      a NullRegion is true, the NullRegion represents an infinite Region
      (that is, all points in the coordinate system are inside the NullRegion).
   }
   \sstconstructor{
      \htmlref{astNullRegion}{astNullRegion}
   }
   \sstdiytopic{
      Inheritance
   }{
      The NullRegion class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The NullRegion class does not define any new attributes beyond
      those which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      The NullRegion class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   Object
}{
   Base class for all AST Objects
}{
   \sstdescription{
      This class is the base class from which all other classes in the
      AST library are derived. It provides all the basic Object
      behaviour and Object manipulation facilities required throughout
      the library. There is no Object constructor, however, as Objects
      on their own are not useful.
   }
   \sstconstructor{
      None.
   }
   \sstdiytopic{
      Inheritance
   }{
      The Object base class does not inherit from any other class.
   }
   \sstdiytopic{
      Attributes
   }{
      All Objects have the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Class}{Class}: Object class name

         \sstitem
         \htmlref{ID}{ID}: Object identification string

         \sstitem
         \htmlref{Ident}{Ident}: Permanent Object identification string

         \sstitem
         \htmlref{Nobject}{Nobject}: Number of Objects in class

         \sstitem
         \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes

         \sstitem
         \htmlref{RefCount}{RefCount}: Count of active Object pointers

         \sstitem
         \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes?
      }
   }
   \sstdiytopic{
      Functions
   }{
      The following functions may be applied to all Objects:

      \sstitemlist{

         \sstitem
         \htmlref{astAnnul}{astAnnul}: Annul a pointer to an Object

         \sstitem
         \htmlref{astBegin}{astBegin}: Begin a new AST context

         \sstitem
         \htmlref{astClear}{astClear}: Clear attribute values for an Object

         \sstitem
         \htmlref{astClone}{astClone}: Clone a pointer to an Object

         \sstitem
         \htmlref{astCopy}{astCopy}: Copy an Object

         \sstitem
         \htmlref{astDelete}{astDelete}: Delete an Object

         \sstitem
         \htmlref{astEnd}{astEnd}: End an AST context

         \sstitem
         \htmlref{astEscapes}{astEscapes}: Control whether graphical escape sequences are removed

         \sstitem
         \htmlref{astExempt}{astExempt}: Exempt an Object pointer from AST context handling

         \sstitem
         \htmlref{astExport}{astExport}: Export an Object pointer to an outer context

         \sstitem
         \htmlref{astGet$<$X$>$}{astGet$<$X$>$}: Get an attribute value for an Object

         \sstitem
         \htmlref{astHasAttribute}{astHasAttribute}: Test if an Object has a named attribute

         \sstitem
         \htmlref{astImport}{astImport}: Import an Object pointer to the current context

         \sstitem
         \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$}: Test class membership

         \sstitem
         \htmlref{astLock}{astLock}: Lock an Object for use by the calling thread

         \sstitem
         \htmlref{astToString}{astToString}: Create an in-memory serialisation of an Object

         \sstitem
         \htmlref{astSame}{astSame}: Do two AST pointers refer to the same Object?

         \sstitem
         \htmlref{astSet}{astSet}: Set attribute values for an Object

         \sstitem
         \htmlref{astSet$<$X$>$}{astSet$<$X$>$}: Set an attribute value for an Object

         \sstitem
         \htmlref{astShow}{astShow}: Display a textual representation of an Object on standard
         output

         \sstitem
         \htmlref{astTest}{astTest}: Test if an attribute value is set for an Object

         \sstitem
         \htmlref{astTune}{astTune}: Set or get an integer AST tuning parameter

         \sstitem
         \htmlref{astTuneC}{astTuneC}: Set or get a character AST tuning parameter

         \sstitem
         \htmlref{astUnlock}{astUnlock}: Unlock an Object for use by other threads

         \sstitem
         \htmlref{astFromString}{astFromString}: Re-create an Object from an in-memory serialisation

         \sstitem
         \htmlref{astVersion}{astVersion}: Return the verson of the AST library being used.
      }
   }
}
\sstroutine{
   PcdMap
}{
   Apply 2-dimensional pincushion/barrel distortion
}{
   \sstdescription{
      A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional
      positions to correct for the radial distortion introduced by some
      cameras and telescopes. This can take the form either of pincushion
      or barrel distortion, and is characterized by a single distortion
      coefficient.

      A PcdMap is specified by giving this distortion coefficient and the
      coordinates of the centre of the radial distortion. The forward
      transformation of a PcdMap applies the distortion:

         RD = R $*$ ( 1 $+$ C $*$ R $*$ R )

      where R is the undistorted radial distance from the distortion
      centre (specified by attribute PcdCen), RD is the radial distance
      from the same centre in the presence of distortion, and C is the
      distortion coefficient (given by attribute \htmlref{Disco}{Disco}).

      The inverse transformation of a PcdMap removes the distortion
      produced by the forward transformation. The expression used to derive
      R from RD is an approximate inverse of the expression above.
   }
   \sstconstructor{
      \htmlref{astPcdMap}{astPcdMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The PcdMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      PcdMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient

         \sstitem
         \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion
      }
   }
   \sstdiytopic{
      Functions
   }{
      The PcdMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   PermMap
}{
   Coordinate permutation Mapping
}{
   \sstdescription{
      A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates,
      and possibly also changes the number of coordinates, between its
      input and output.

      In addition to permuting the coordinate order, a PermMap may
      also assign constant values to coordinates. This is useful when
      the number of coordinates is being increased as it allows fixed
      values to be assigned to any new ones.
   }
   \sstconstructor{
      \htmlref{astPermMap}{astPermMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The PermMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The PermMap class does not define any new attributes beyond
      those which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The PermMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Plot
}{
   Provide facilities for 2D graphical output
}{
   \sstdescription{
      This class provides facilities for producing 2D graphical output.
      A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base
      \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"}  coordinate system and is
      associated with a rectangular plotting area in the underlying
      graphics system. This plotting area is where graphical output
      appears. It is defined when the Plot is created.

      The current Frame of a Plot describes a \texttt{"} physical\texttt{"}  coordinate
      system, which is the coordinate system in which plotting
      operations are specified. The results of each plotting operation
      are automatically transformed into graphical coordinates so as
      to appear in the plotting area (subject to any clipping which
      may be in effect).

      Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates
      may often be non-linear, or even discontinuous, most plotting
      does not result in simple straight lines. The basic plotting
      element is therefore not a straight line, but a geodesic curve
      (see \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve} and \htmlref{astPolyCurve}{astPolyCurve}). A Plot also provides facilities for
      drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines
      (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with
      optional coordinate grids (\htmlref{astGrid}{astGrid}).
      A range of Plot attributes is available to allow precise control
      over the appearance of graphical output produced by these
      functions.

      You may select different physical coordinate systems in which to
      plot (including the native graphical coordinate system itself)
      by selecting different Frames as the current Frame of a Plot,
      using its \htmlref{Current}{Current} attribute.  You may also set up clipping (see
      \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and
      this may be done in any of the coordinate systems associated
      with the Plot, not necessarily the one you are plotting in.

      Like any FrameSet, a Plot may also be used as a Frame. In this
      case, it behaves like its current Frame, which describes the
      physical coordinate system.

      When used as a Mapping, a Plot describes the inter-relation
      between graphical coordinates (its base Frame) and physical
      coordinates (its current Frame).  It differs from a normal
      FrameSet, however, in that an attempt to transform points which
      lie in clipped areas of the Plot will result in bad coordinate
      values (AST\_\_BAD).
   }
   \sstconstructor{
      \htmlref{astPlot}{astPlot}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Plot class inherits from the FrameSet class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all FrameSets, every
      Plot also has the following attributes:

      \sstitemlist{

         \sstitem
         Abbrev: Abbreviate leading fields?

         \sstitem
         \htmlref{Border}{Border}: Draw a border around valid regions of a Plot?

         \sstitem
         \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary?

         \sstitem
         \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR?

         \sstitem
         \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element

         \sstitem
         \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot?

         \sstitem
         \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot?

         \sstitem
         \htmlref{Escape}{Escape}: Allow changes of character attributes within strings?

         \sstitem
         \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot

         \sstitem
         \htmlref{Font(element)}{Font(element)}: Character font for a Plot element

         \sstitem
         \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values

         \sstitem
         \htmlref{Grf}{Grf}: Select the graphics interface to use.

         \sstitem
         \htmlref{Grid}{Grid}: Draw grid lines for a Plot?

         \sstitem
         \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink?

         \sstitem
         \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot

         \sstitem
         \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot?

         \sstitem
         \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright?

         \sstitem
         \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot

         \sstitem
         \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values

         \sstitem
         \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically?

         \sstitem
         \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically?

         \sstitem
         \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot

         \sstitem
         \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot

         \sstitem
         \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot

         \sstitem
         \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot?

         \sstitem
         \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot

         \sstitem
         \htmlref{Size(element)}{Size(element)}: Character size for a Plot element

         \sstitem
         \htmlref{Style(element)}{Style(element)}: Line style for a Plot element

         \sstitem
         \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot?

         \sstitem
         \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot

         \sstitem
         \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot?

         \sstitem
         \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title

         \sstitem
         \htmlref{Tol}{Tol}: Plotting tolerance

         \sstitem
         \htmlref{Width(element)}{Width(element)}: Line width for a Plot element
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all FrameSets, the
      following functions may also be applied to all Plots:

      \sstitemlist{

         \sstitem
         \htmlref{astBBuf}{astBBuf}: Begin a new graphical buffering context

         \sstitem
         \htmlref{astBorder}{astBorder}: Draw a border around valid regions of a Plot

         \sstitem
         \htmlref{astBoundingBox}{astBoundingBox}: Returns a bounding box for previously drawn graphics

         \sstitem
         \htmlref{astClip}{astClip}: Set up or remove clipping for a Plot

         \sstitem
         \htmlref{astCurve}{astCurve}: Draw a geodesic curve

         \sstitem
         \htmlref{astEBuf}{astEBuf}: End the current graphical buffering context

         \sstitem
         \htmlref{astGenCurve}{astGenCurve}: Draw a generalized curve

         \sstitem
         \htmlref{astGetGrfContext}{astGetGrfContext}: Get the graphics context for a Plot

         \sstitem
         \htmlref{astGrfPop}{astGrfPop}: Retrieve previously saved graphics functions

         \sstitem
         \htmlref{astGrfPush}{astGrfPush}: Save the current graphics functions

         \sstitem
         \htmlref{astGrfSet}{astGrfSet}: Register a graphics routine for use by a Plot

         \sstitem
         \htmlref{astGrid}{astGrid}: Draw a set of labelled coordinate axes

         \sstitem
         \htmlref{astGridLine}{astGridLine}: Draw a grid line (or axis) for a Plot

         \sstitem
         \htmlref{astMark}{astMark}: Draw a set of markers for a Plot

         \sstitem
         \htmlref{astPolyCurve}{astPolyCurve}: Draw a series of connected geodesic curves

         \sstitem
         \htmlref{astRegionOutline}{astRegionOutline}: Draw the outline of an AST \htmlref{Region}{Region}

         \sstitem
         \htmlref{astText}{astText}: Draw a text string for a Plot
      }
   }
   \sstdiytopic{
      Graphical Elements
   }{
      The colour index, character font, character size, line style and
      line width used for plotting can be set independently for
      various elements of the graphical output produced by a Plot.
      The different graphical elements are identified by appending the
      strings listed below as subscripts to the Plot attributes
      Colour(element), Font(element), Size(element), Style(element)
      and Width(element). These strings are case-insensitive and
      unambiguous abbreviations may be used. Elements of the graphical
      output which relate to individual axes can be referred to either
      independently (e.g. \texttt{"} (Grid1)\texttt{"}  and \texttt{"} (Grid2)\texttt{"}  ) or together (e.g.
      \texttt{"} (Grid)\texttt{"} ):

      \sstitemlist{

         \sstitem
         Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using astGrid

         \sstitem
         Axis1: Axis line drawn through tick marks on axis 1 using astGrid

         \sstitem
         Axis2: Axis line drawn through tick marks on axis 2 using astGrid

         \sstitem
         Border: The Plot border drawn using astBorder, astGrid or astRegionOutline

         \sstitem
         Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve

         \sstitem
         Grid: Grid lines drawn using astGridLine or astGrid

         \sstitem
         Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid

         \sstitem
         Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid

         \sstitem
         Markers: Graphical markers (symbols) drawn using astMark

         \sstitem
         NumLab: Numerical axis labels drawn using astGrid

         \sstitem
         NumLab1: Numerical labels for axis 1 drawn using astGrid

         \sstitem
         NumLab2: Numerical labels for axis 2 drawn using astGrid

         \sstitem
         Strings: Text strings drawn using astText

         \sstitem
         TextLab: Descriptive axis labels drawn using astGrid

         \sstitem
         TextLab1: Descriptive label for axis 1 drawn using astGrid

         \sstitem
         TextLab2: Descriptive label for axis 2 drawn using astGrid

         \sstitem
         Ticks: Tick marks (both major and minor) drawn using astGrid

         \sstitem
         Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid

         \sstitem
         Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid

         \sstitem
         \htmlref{Title}{Title}: The Plot title drawn using astGrid
      }
   }
}
\sstroutine{
   Plot3D
}{
   Provide facilities for 3D graphical output
}{
   \sstdescription{
      A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities
      for producing 3D graphical output, including fully annotated 3D
      coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional
      \texttt{"} graphical\texttt{"}  coordinate system. The axes of this coordinate system are
      assumed to be right-handed (that is, if X appears horizontally to the
      right and Y vertically upwards, then Z is out of the screen towards
      the viewer), and are assumed to be equally scaled (that is, the same
      units are used to measure positions on each of the 3 axes). The upper
      and lower bounds of a volume within this graphical coordinate system
      is specified when the Plot3D is created, and all subsequent graphics
      are \texttt{"} drawn\texttt{"}  in this volume.

      The Plot3D class does not itself include any ability to draw on a
      graphics device. Instead it calls upon function in an externally
      supplied module (the \texttt{"} grf3d\texttt{"}  module) to do the required drawing.
      A module should be written that implements the functions of the
      grf3d interface using the facilities of a specific graphics system
      This module should then be linked into the application so that the
      Plot3D class can use its functions (see the description of the
      \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface
      defines a few simple functions for drawing primitives such as straight
      lines, markers and character strings. These functions all accept
      positions in the 3D graphics coordinate system (the base Frame of the
      Plot3D), and so the grf3d module must also manage the projection of
      these 3D coordinates onto the 2D viewing surface, including the choice
      of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"}  position, direction of viewing, etc. The AST
      library includes a sample implementation of the grf3d interface
      based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This
      implementation also serves to document the grf3d interface itself and
      should be consulted for details before writing a new implementation.

      The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"}  3-dimensional
      coordinate system, which is the coordinate system in which plotting
      operations are specified when invoking the methods of the Plot3D
      class. The results of each plotting operation are automatically
      transformed into 3D graphical coordinates before being plotted
      using the facilities of the grf3d module linked into the application.
      Note, at least one of the three axes of the current Frame must be
      independent of the other two current Frame axes.

      You may select different physical coordinate systems in which to
      plot (including the native graphical coordinate system itself)
      by selecting different Frames as the current Frame of a Plot3D,
      using its \htmlref{Current}{Current} attribute.

      Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this
      case, it behaves like its current Frame, which describes the
      physical coordinate system.

      When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation
      between 3D graphical coordinates (its base Frame) and 3D physical
      coordinates (its current Frame).

      Although the Plot3D class inherits from the Plot class, several of
      the facilities of the Plot class are not available in the Plot3D
      class, and an error will be reported if any attempt is made to use
      them. Specifically, the Plot3D class does not support clipping
      using the
      \htmlref{astClip}{astClip} function.
      Nor does it support the specification of graphics primitive functions
      at run-time using the
      \htmlref{astGrfSet}{astGrfSet}, \htmlref{astGrfPop}{astGrfPop}, \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGetGrfContext}{astGetGrfContext} functions.
   }
   \sstconstructor{
      \htmlref{astPlot3D}{astPlot3D}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Plot3D class inherits from the Plot class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Plots, every
      Plot3D also has the following attributes:

      \sstitemlist{

         \sstitem
         Norm: Normal vector defining the 2D plane used for text and markers

         \sstitem
         \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated.

      }
      Some attributes of the Plot class refer to specific physical
      coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic
      Plot, the axis index must be 1 or 2, but for a Plot3D the axis index
      can be 1, 2 or 3.

      Certain Plot attributes are ignored by the Plot3D class (e.g. Edge,
      \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation
      for details. All other Plot attributes can be set for a specific
      plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"}
      or \texttt{"} \_YZ\texttt{"}  to the end of the Plot attribute name. For instance,
      \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"}  refers to the \texttt{"} Grid\texttt{"}  attribute for the plane spanning
      the second (Y) and third (Z) axes of the 3-d plot.
   }
   \sstdiytopic{
      Functions
   }{
       The Plot3D class does not define any new functions beyond those
       which are applicable to all Plots. Note, however, that the
       following methods inherited from the Plot class cannot be used with
       a Plot3D and will report an error if called:
      \sstitemlist{

         \sstitem
         \htmlref{astBoundingBox}{astBoundingBox}, astClip, \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve},
         astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, \htmlref{astGridLine}{astGridLine},
         \htmlref{astPolyCurve}{astPolyCurve}.
      }
   }
}
\sstroutine{
   PointList
}{
   A collection of points in a Frame
}{
   \sstdescription{
      The PointList class implements a \htmlref{Region}{Region} which represents a collection
      of points in a \htmlref{Frame}{Frame}.
   }
   \sstconstructor{
      \htmlref{astPointList}{astPointList}
   }
   \sstdiytopic{
      Inheritance
   }{
      The PointList class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Regions, every
      PointList also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList
      }
   }
   \sstdiytopic{
      Functions
   }{
      The PointList class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   PolyMap
}{
   Map coordinates using polynomial functions
}{
   \sstdescription{
      A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial
      transformation.  Each output coordinate is a polynomial function of
      all the input coordinates. The coefficients are specified separately
      for each output coordinate. The forward and inverse transformations
      are defined independantly by separate sets of coefficients. If no
      inverse transformation is supplied, an iterative method can be used
      to evaluate the inverse based only on the forward transformation.
   }
   \sstconstructor{
      \htmlref{astPolyMap}{astPolyMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The PolyMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      PolyMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation?

         \sstitem
         \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse

         \sstitem
         \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Objects, the
      following functions may also be applied to all Mappings:

      \sstitemlist{

         \sstitem
         \htmlref{astPolyTran}{astPolyTran}: Fit a PolyMap inverse or forward transformation
      }
   }
}
\sstroutine{
   Polygon
}{
   A polygonal region within a 2-dimensional Frame
}{
   \sstdescription{
      The Polygon class implements a polygonal area, defined by a
      collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices
      are connected together by geodesic curves within the encapsulated Frame.
      For instance, if the encapsulated Frame is a simple Frame then the
      geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then
      the geodesics will be great circles. Note, the vertices must be
      supplied in an order such that the inside of the polygon is to the
      left of the boundary as the vertices are traversed. Supplying them
      in the reverse order will effectively negate the polygon.

      Within a SkyFrame, neighbouring vertices are always joined using the
      shortest path. Thus if an edge of 180 degrees or more in length is
      required, it should be split into section each of which is less
      than 180 degrees. The closed path joining all the vertices in order
      will divide the celestial sphere into two disjoint regions. The
      inside of the polygon is the region which is circled in an
      anti-clockwise manner (when viewed from the inside of the celestial
      sphere) when moving through the list of vertices in the order in
      which they were supplied when the Polygon was created (i.e. the
      inside is to the left of the boundary when moving through the
      vertices in the order supplied).
   }
   \sstconstructor{
      \htmlref{astPolygon}{astPolygon}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Polygon class inherits from the \htmlref{Region}{Region} class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Regions, every
      Polygon also has the following attributes:
      \sstitemlist{

         \sstitem
         \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices?
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Regions, the
      following functions may also be applied to all Polygons:

      \sstitemlist{

         \sstitem
         \htmlref{astDownsize}{astDownsize}: Reduce the number of vertices in a Polygon.

         \sstitem
         \htmlref{astConvex$<$X$>$}{astConvex$<$X$>$}: Create a Polygon giving the convex hull of a pixel array

         \sstitem
         \htmlref{astOutline$<$X$>$}{astOutline$<$X$>$}: Create a Polygon outlining values in a pixel array
      }
   }
}
\sstroutine{
   Prism
}{
   An extrusion of a region into higher dimensions
}{
   \sstdescription{
      A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region
      into one or more orthogonal dimensions (specified by another Region).
      If the Region to be extruded has N axes, and the Region defining the
      extrusion has M axes, then the resulting Prism will have (M$+$N) axes.
      A point is inside the Prism if the first N axis values correspond to
      a point inside the Region being extruded, and the remaining M axis
      values correspond to a point inside the Region defining the extrusion.

      As an example, a cylinder can be represented by extruding an existing
      \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the
      Interval would have a single axis and would specify the upper and
      lower limits of the cylinder along its length.
   }
   \sstconstructor{
      \htmlref{astPrism}{astPrism}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Prism class inherits from the Region class.
   }
   \sstdiytopic{
      Attributes
   }{
      The Prism class does not define any new attributes beyond those
      which are applicable to all Regions.
   }
   \sstdiytopic{
      Functions
   }{
      The Prism class does not define any new functions beyond those
      which are applicable to all Regions.
   }
}
\sstroutine{
   RateMap
}{
   Mapping which represents differentiation
}{
   \sstdescription{
      A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the
      Jacobian matrix of another Mapping. The Mapping for which the
      Jacobian is required is specified when the new RateMap is created,
      and is referred to as the \texttt{"} encapsulated Mapping\texttt{"}  below.

      The number of inputs to a RateMap is the same as the number of inputs
      to its encapsulated Mapping. The number of outputs from a RateMap
      is always one. This one output equals the rate of change of a
      specified output of the encapsulated Mapping with respect to a
      specified input of the encapsulated Mapping (the input and output
      to use are specified when the RateMap is created).

      A RateMap which has not been inverted does not define an inverse
      transformation. If a RateMap has been inverted then it will define
      an inverse transformation but not a forward transformation.
   }
   \sstconstructor{
      \htmlref{astRateMap}{astRateMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The RateMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The RateMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The RateMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Region
}{
   Represents a region within a coordinate system
}{
   \sstdescription{
      This class provides the basic facilities for describing a region within
      a specified coordinate system. However, the Region class does not
      have a constructor function of its own, as it is simply a container
      class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc,
      which implement Regions with particular shapes.

      All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region
      is created. This Frame describes the coordinate system in which the
      Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"}  below.
      Constructors will also typically required one or more positions to be
      supplied which define the location and extent of the region. These
      positions must be supplied within the encapsulated Frame.

      The Region class inherits from the Frame class, and so a Region can be
      supplied where-ever a Frame is expected. In these cases, supplying a
      Region is equivalent to supplying a reference to its encapsulated Frame.
      Thus all the methods of the Frame class can be used on the Region class.
      For instance, the
      \htmlref{astFormat}{astFormat} function
      may be used on a Region to format an axis value.

      In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort
      of Mapping. Transforming positions by supplying a Region to one of the
      astTran$<$X$>$ functions
      is the way to determine if a given position is inside or outside the
      Region. When used as a Mapping, most classes of Frame are equivalent to
      a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a
      Region acts like a UnitMap only for input positions which are within the
      area represented by the Region. Input positions which are outside the
      area produce bad output values (i.e. the output values are equal to
      AST\_\_BAD). This behaviour is the same for both the forward and the
      inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"}
      is not a true inverse of the forward transformation, since applying
      the forward transformation to a point outside the Region, and then
      applying the inverse transformation results, in a set of AST\_\_BAD axis
      values rather than the original axis values. If required, the
      \htmlref{astRemoveRegions}{astRemoveRegions}
      function can be used to remove the \texttt{"} masking\texttt{"}  effect of any Regions
      contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by
      replacing each Region with a UnitMap or equivalent Frame (depending
      on the context in which the Region is used).

      If the coordinate system represented by the Region is changed (by
      changing the values of one or more of the attribute which the Region
      inherits from its encapsulated Frame), the area represented by
      the Region is mapped into the new coordinate system. For instance, let\texttt{'} s
      say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being
      supplied to the constructor so that the Circle describes a circular
      area on the sky in FK4 equatorial coordinates. Since Region inherits
      from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute
      will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then
      changed from FK4 to FK5, the circular area represented by the Region
      will automatically be mapped from the FK4 system into the FK5 system.
      In general, changing the coordinate system in this way may result in the
      region changing shape - for instance, a circle may change into an
      ellipse if the transformation from the old to the new coordinate system
      is linear but with different scales on each axis. Thus the specific
      class of a Region cannot be used as a guarantee of the shape in any
      particular coordinate system. If the
      \htmlref{astSimplify}{astSimplify} function
      is used on a Region, it will endeavour to return a new Region of
      a sub-class which accurately describes the shape in the current
      coordinate system of the Region (but this may not always be possible).

      It is possible to negate an existing Region so that it represents all
      areas of the encapsulated Frame except for the area specified when
      the Region was created.
   }
   \sstconstructor{
      None.
   }
   \sstdiytopic{
      Inheritance
   }{
      The Region class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      Region also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system?

         \sstitem
         \htmlref{Negated}{Negated}: Has the original region been negated?

         \sstitem
         \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region?

         \sstitem
         \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region

         \sstitem
         \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest

         \sstitem
         \htmlref{Bounded}{Bounded}: Is the Region bounded?

      }
      Every Region also inherits any further attributes that belong
      to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For
      example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is
      inherited by any Region which represents a SkyFrame.)
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Frames, the
      following functions may also be applied to all Regions:

      \sstitemlist{

         \sstitem
         \htmlref{astGetRegionBounds}{astGetRegionBounds}: Get the bounds of a Region

         \sstitem
         \htmlref{astGetRegionFrame}{astGetRegionFrame}: Get a copy of the Frame represent by a Region

         \sstitem
         \htmlref{astGetRegionFrameSet}{astGetRegionFrameSet}: Get a copy of the Frameset encapsulated by a Region

         \sstitem
         \htmlref{astGetRegionMesh}{astGetRegionMesh}: Get a mesh of points covering a Region

         \sstitem
         \htmlref{astGetRegionPoints}{astGetRegionPoints}: Get the positions that define a Region

         \sstitem
         \htmlref{astGetUnc}{astGetUnc}: Obtain uncertainty information from a Region

         \sstitem
         \htmlref{astMapRegion}{astMapRegion}: Transform a Region into a new coordinate system

         \sstitem
         \htmlref{astNegate}{astNegate}: Toggle the value of the Negated attribute

         \sstitem
         \htmlref{astOverlap}{astOverlap}: Determines the nature of the overlap between two Regions

         \sstitem
         \htmlref{astMask$<$X$>$}{astMask$<$X$>$}: Mask a region of a data grid

         \sstitem
         \htmlref{astSetUnc}{astSetUnc}: Associate a new uncertainty with a Region

         \sstitem
         \htmlref{astShowMesh}{astShowMesh}: Display a mesh of points on the surface of a Region
      }
   }
}
\sstroutine{
   SelectorMap
}{
   A Mapping that locates positions within one of a set of alternate
   Regions
}{
   \sstdescription{
      A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains
      a given input position.

      A SelectorMap encapsulates a number of Regions that all have the same
      number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of
      inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes
      spanned by one of the encapsulated Region. All SelectorMaps have only
      a single output. SelectorMaps do not define an inverse transformation.

      For each input position, the forward transformation of a SelectorMap
      searches through the encapsulated Regions (in the order supplied when
      the SelectorMap was created) until a Region is found which contains
      the input position. The index associated with this Region is
      returned as the SelectorMap output value (the index value is the
      position of the Region within the list of Regions supplied when the
      SelectorMap was created, starting at 1 for the first Region). If an
      input position is not contained within any Region, a value of zero is
      returned by the forward transformation.

      If a compound Mapping contains a SelectorMap in series with its own
      inverse, the combination of the two adjacent SelectorMaps will be
      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
      \htmlref{astSimplify}{astSimplify}.

      In practice, SelectorMaps are often used in conjunction with SwitchMaps.
   }
   \sstconstructor{
      \htmlref{astSelectorMap}{astSelectorMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SelectorMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The SelectorMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The SelectorMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   ShiftMap
}{
   Add a constant value to each coordinate
}{
   \sstdescription{
      A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a
      specified constant value.
   }
   \sstconstructor{
      \htmlref{astShiftMap}{astShiftMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The ShiftMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The ShiftMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The ShiftMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   SkyAxis
}{
   Store celestial axis information
}{
   \sstdescription{
      The SkyAxis class is used to store information associated with a
      particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST
      library and has no constructor function. You should encounter it
      only within textual output (e.g. from \htmlref{astWrite}{astWrite}).
   }
   \sstconstructor{
      None.
   }
   \sstdiytopic{
      Inheritance
   }{
      The SkyAxis class inherits from the \htmlref{Axis}{Axis} class.
   }
}
\sstroutine{
   SkyFrame
}{
   Celestial coordinate system description
}{
   \sstdescription{
      A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes
      celestial longitude/latitude coordinate systems. The particular
      celestial coordinate system to be represented is specified by
      setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default
      is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or
      an \htmlref{Epoch}{Epoch}.

      For each of the supported celestial coordinate systems, a SkyFrame
      can apply an optional shift of origin to create a coordinate system
      representing offsets within the celestial coordinate system from some
      specified reference point. This offset coordinate system can also be
      rotated to define new longitude and latitude axes. See attributes
      SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}.

      All the coordinate values used by a SkyFrame are in
      radians. These may be formatted in more conventional ways for
      display by using \htmlref{astFormat}{astFormat}.
      For a SkyFrame, the Unit attribute describes the formatted value of
      a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a
      formatted axis value contains colon-separated fields for hours, minutes
      and seconds. On the other hand, the InternalUnit attribute for a
      SkyFrame is always set to \texttt{"} rad\texttt{"}  (i.e. radians), indicating that the
      unformatted (i.e. floating point) axis values used by application code
      are always in units of radians
   }
   \sstconstructor{
      \htmlref{astSkyFrame}{astSkyFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SkyFrame class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      SkyFrame also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system?

         \sstitem
         \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times?

         \sstitem
         \htmlref{Equinox}{Equinox}: Epoch of the mean equinox

         \sstitem
         IsLatAxis: Is the specified axis the latitude axis?

         \sstitem
         IsLonAxis: Is the specified axis the longitude axis?

         \sstitem
         \htmlref{LatAxis}{LatAxis}: Index of the latitude axis

         \sstitem
         \htmlref{LonAxis}{LonAxis}: Index of the longitude axis

         \sstitem
         \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]?

         \sstitem
         \htmlref{Projection}{Projection}: Sky projection description.

         \sstitem
         SkyRef: Position defining location of the offset coordinate system

         \sstitem
         \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system

         \sstitem
         SkyRefP: Position defining orientation of the offset coordinate system

         \sstitem
         \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those
      functions
      applicable to all Frames, the following
      functions
      may also be applied to all SkyFrames:

      \sstitemlist{

         \sstitem
         \htmlref{astSkyOffsetMap}{astSkyOffsetMap}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates
      }
   }
}
\sstroutine{
   SlaMap
}{
   Sequence of celestial coordinate conversions
}{
   \sstdescription{
      An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
      represent a sequence of conversions between standard celestial
      (longitude, latitude) coordinate systems.

      When an SlaMap is first created, it simply performs a unit
      (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd}
      function, a series of coordinate conversion steps may then be
      added, selected from those provided by the SLALIB Positional
      Astronomy Library (Starlink User Note SUN/67). This allows
      multi-step conversions between a variety of celestial coordinate
      systems to be assembled out of the building blocks provided by
      SLALIB.

      For details of the individual coordinate conversions available,
      see the description of the astSlaAdd function.
   }
   \sstconstructor{
      \htmlref{astSlaMap}{astSlaMap} (also see astSlaAdd)
   }
   \sstdiytopic{
      Inheritance
   }{
      The SlaMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The SlaMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Mappings, the
      following function may also be applied to all SlaMaps:

      \sstitemlist{

         \sstitem
         \htmlref{astSlaAdd}{astSlaAdd}: Add a celestial coordinate conversion to an SlaMap
      }
   }
}
\sstroutine{
   SpecFluxFrame
}{
   Compound spectrum/flux Frame
}{
   \sstdescription{
      A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single
      2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used
      to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents
      spectral position and the second axis represents flux.
   }
   \sstconstructor{
      \htmlref{astSpecFluxFrame}{astSpecFluxFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class.
   }
   \sstdiytopic{
      Attributes
   }{
      The SpecFluxFrame class does not define any new attributes beyond
      those which are applicable to all CmpFrames. However, the attributes
      of the component Frames can be accessed as if they were attributes
      of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise
      the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"}  attribute and forward access requests to the component
      SpecFrame. An axis index can optionally be appended to the end of any
      attribute name, in which case the request to access the attribute will
      be forwarded to the primary Frame defining the specified axis.
   }
   \sstdiytopic{
      Functions
   }{
      The SpecFluxFrame class does not define any new functions beyond those
      which are applicable to all CmpFrames.
   }
}
\sstroutine{
   SpecFrame
}{
   Spectral coordinate system description
}{
   \sstdescription{
      A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various coordinate systems used to describe positions within
      an electro-magnetic spectrum. The particular coordinate system to be
      used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the
      default is wavelength) qualified, as necessary, by other attributes
      such as the rest frequency, the standard of rest, the epoch of
      observation, units, etc (see the description of the System attribute
      for details).

      By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made
      to represent offsets from a given spectral position, rather than absolute
      spectral values.
   }
   \sstconstructor{
      \htmlref{astSpecFrame}{astSpecFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SpecFrame class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      SpecFrame also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system?

         \sstitem
         \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames

         \sstitem
         \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000)

         \sstitem
         \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000)

         \sstitem
         \htmlref{RestFreq}{RestFreq}: Rest frequency

         \sstitem
         \htmlref{SourceSys}{SourceSys}: Source velocity spectral system

         \sstitem
         \htmlref{SourceVel}{SourceVel}: Source velocity

         \sstitem
         \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame

         \sstitem
         \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values

         \sstitem
         \htmlref{StdOfRest}{StdOfRest}: Standard of rest

      }
      Several of the Frame attributes inherited by the SpecFrame class
      refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)},
      \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional,
      it allows these attributes to be specified without an axis index.
      So for instance, \texttt{"} Unit\texttt{"}  is allowed in place of \texttt{"} Unit(1)\texttt{"} .
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Frames, the
      following functions may also be applied to all SpecFrames:

      \sstitemlist{

         \sstitem
         \htmlref{astSetRefPos}{astSetRefPos}: Set reference position in any celestial system

         \sstitem
         \htmlref{astGetRefPos}{astGetRefPos}: Get reference position in any celestial system
      }
   }
}
\sstroutine{
   SpecMap
}{
   Sequence of spectral coordinate conversions
}{
   \sstdescription{
      A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
      represent a sequence of conversions between standard spectral
      coordinate systems.

      When an SpecMap is first created, it simply performs a unit
      (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd}
      function, a series of coordinate conversion steps may then be
      added. This allows multi-step conversions between a variety of
      spectral coordinate systems to be assembled out of a set of building
      blocks.

      Conversions are available to transform between standards of rest.
      Such conversions need to know the source position as an RA and DEC.
      This information can be supplied in the form of parameters for
      the relevant conversions, in which case the SpecMap is 1-dimensional,
      simply transforming the spectral axis values. This means that the
      same source position will always be used by the SpecMap. However, this
      may not be appropriate for an accurate description of a 3-D spectral
      cube, where changes of spatial position can produce significant
      changes in the Doppler shift introduced when transforming between
      standards of rest. For this situation, a 3-dimensional SpecMap can
      be created in which axes 2 and 3 correspond to the source RA and DEC
      The SpecMap simply copies values for axes 2 and 3 from input to
      output), but modifies axis 1 values (the spectral axis) appropriately.

      For details of the individual coordinate conversions available,
      see the description of the astSpecAdd function.
   }
   \sstconstructor{
      \htmlref{astSpecMap}{astSpecMap} (also see astSpecAdd)
   }
   \sstdiytopic{
      Inheritance
   }{
      The SpecMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The SpecMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Mappings, the
      following function may also be applied to all SpecMaps:

      \sstitemlist{

         \sstitem
         \htmlref{astSpecAdd}{astSpecAdd}: Add a spectral coordinate conversion to an SpecMap
      }
   }
}
\sstroutine{
   SphMap
}{
   Map 3-d Cartesian to 2-d spherical coordinates
}{
   \sstdescription{
      A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a
      3-dimensional Cartesian coordinate system into a 2-dimensional
      spherical coordinate system (longitude and latitude on a unit
      sphere centred at the origin). It works by regarding the input
      coordinates as position vectors and finding their intersection
      with the sphere surface. The inverse transformation always
      produces points which are a unit distance from the origin
      (i.e. unit vectors).
   }
   \sstconstructor{
      \htmlref{astSphMap}{astSphMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SphMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      SphMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere?

         \sstitem
         \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole
      }
   }
   \sstdiytopic{
      Functions
   }{
      The SphMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Stc
}{
   Represents an instance of the IVOA STC class
}{
   \sstdescription{
      The Stc class is an implementation of the IVOA STC class which forms
      part of the IVOA Space-Time Coordinate Metadata system. See:

      http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html

      The Stc class does not have a constructor function of its own, as it
      is simply a container class for a family of specialised sub-classes
      including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation}
      and \htmlref{StcObsDataLocation}{StcObsDataLocation}.
   }
   \sstconstructor{
      astStc
   }
   \sstdiytopic{
      Inheritance
   }{
      The Stc class inherits from the \htmlref{Region}{Region} class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Regions, every
      Stc also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region.
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Regions, the
      following functions may also be applied to all Stc\texttt{'} s:

      \sstitemlist{

         \sstitem
         \htmlref{astGetStcRegion}{astGetStcRegion}: Get a pointer to the encapsulated Region

         \sstitem
         \htmlref{astGetStcCoord}{astGetStcCoord}: Get information about an AstroCoords element

         \sstitem
         \htmlref{astGetStcNCoord}{astGetStcNCoord}: Returns the number of AstroCoords elements in an Stc
      }
   }
}
\sstroutine{
   StcCatalogEntryLocation
}{
   Correspond to the IVOA STCCatalogEntryLocation class
}{
   \sstdescription{
      The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of the datasets contained in some VO resource.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstconstructor{
      \htmlref{astStcCatalogEntryLocation}{astStcCatalogEntryLocation}
   }
   \sstdiytopic{
      Inheritance
   }{
      The StcCatalogEntryLocation class inherits from the Stc class.
   }
   \sstdiytopic{
      Attributes
   }{
      The StcCatalogEntryLocation class does not define any new attributes beyond
      those which are applicable to all Stcs.
   }
   \sstdiytopic{
      Functions
   }{
      The StcCatalogEntryLocation class does not define any new functions beyond those
      which are applicable to all Stcs.
   }
}
\sstroutine{
   StcObsDataLocation
}{
   Correspond to the IVOA ObsDataLocation class
}{
   \sstdescription{
      The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coordinate space occupied by a particular observational dataset.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html

      An STC ObsDataLocation element specifies the extent of the
      observation within a specified coordinate system, and also specifies
      the observatory location within a second coordinate system.

      The AST StcObsDataLocation class inherits from Stc, and therefore
      an StcObsDataLocation can be used directly as an Stc. When used
      in this way, the StcObsDataLocation describes the location of the
      observation (not the observatory).

      Eventually, this class will have a method for returning an Stc
      describing the observatory location. However, AST currently does not
      include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar
      system positions. Therefore, the provision for returning observatory
      location as an Stc is not yet available. However, for terrestrial
      observations, the position of the observatory can still be recorded
      using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated
      within the Stc representing the observation location (this assumes
      the observatory is located at sea level).
   }
   \sstconstructor{
      \htmlref{astStcObsDataLocation}{astStcObsDataLocation}
   }
   \sstdiytopic{
      Inheritance
   }{
      The StcObsDataLocation class inherits from the Stc class.
   }
   \sstdiytopic{
      Attributes
   }{
      The StcObsDataLocation class does not define any new attributes beyond
      those which are applicable to all Stcs.
   }
   \sstdiytopic{
      Functions
   }{
      The StcObsDataLocation class does not define any new functions beyond those
      which are applicable to all Stcs.
   }
}
\sstroutine{
   StcResourceProfile
}{
   Correspond to the IVOA STCResourceProfile class
}{
   \sstdescription{
      The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of the datasets contained in some VO resource.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstconstructor{
      \htmlref{astStcResourceProfile}{astStcResourceProfile}
   }
   \sstdiytopic{
      Inheritance
   }{
      The StcResourceProfile class inherits from the Stc class.
   }
   \sstdiytopic{
      Attributes
   }{
      The StcResourceProfile class does not define any new attributes beyond
      those which are applicable to all Stcs.
   }
   \sstdiytopic{
      Functions
   }{
      The StcResourceProfile class does not define any new functions beyond those
      which are applicable to all Stcs.
   }
}
\sstroutine{
   StcSearchLocation
}{
   Correspond to the IVOA SearchLocation class
}{
   \sstdescription{
      The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
      the coverage of a query.

      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
   }
   \sstconstructor{
      \htmlref{astStcSearchLocation}{astStcSearchLocation}
   }
   \sstdiytopic{
      Inheritance
   }{
      The StcSearchLocation class inherits from the Stc class.
   }
   \sstdiytopic{
      Attributes
   }{
      The StcSearchLocation class does not define any new attributes beyond
      those which are applicable to all Stcs.
   }
   \sstdiytopic{
      Functions
   }{
      The StcSearchLocation class does not define any new functions beyond those
      which are applicable to all Stcs.
   }
}
\sstroutine{
   StcsChan
}{
   I/O Channel using STC-S to represent Objects
}{
   \sstdescription{
      A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S
      I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
      STC-S description of that Object, and reading from an StcsChan will
      create a new Object from its STC-S description.

      When an STC-S description is read using
      \htmlref{astRead}{astRead},
      the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC
      AstroCoords (i.e. a single point of interest within the coordinate frame
      described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC
      AstrCoordsArea (i.e. an area or volume of interest within the coordinate
      frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap}
      containing the uninterpreted property values read form the STC-S
      description, or 4) a KeyMap containing any combination of the first
      3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps}
      control which of the above is returned by
      astRead.

      When an STC-S description is created from an AST Object using
      astWrite,
      the AST Object must be either a Region or a KeyMap. If it is a
      Region, it is assumed to define the AstroCoordsArea or (if the
      Region is a single point) the AstroCoords to write to the STC-S
      description. If the Object is a KeyMap, it may contain an entry
      with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the
      AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} ,
      holding a Region (a PointList) to be used to create the
      AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding
      a KeyMap that contains uninterpreted property values to be used as
      defaults for any STC-S properties that are not determined by the
      other supplied Regions. In addition, a KeyMap supplied to
      astWrite
      may itself hold the default STC-S properties (rather than defaults
      being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"}  entry in the
      supplied KeyMap).

      The
      astRead and astWrite
      functions work together so that any Object returned by
      astRead can immediately be re-written using astWrite.

      Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting text. These functions
      should perform any conversions needed between external character
      encodings and the internal ASCII encoding. If no such functions
      are supplied, a Channel will read from standard input and write
      to standard output.

      Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.

      Support for STC-S is currently based on the IVOA document \texttt{"} STC-S:
      Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} ,
      version 1.30 (dated 5th December 2007), available at
      http://www.ivoa.net/Documents/latest/STC-S.html. Note, this
      document is a recommednation only and does not constitute an accepted
      IVOA standard.

      The full text of version 1.30 is supported by the StcsChan class,
      with the following exceptions and provisos:

      \sstitemlist{

         \sstitem
         When reading an STC-S phrase, case is ignored except when reading
         units strings.

         \sstitem
         There is no support for multiple intervals specified within a
         TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval.

         \sstitem
         If the ET timescale is specified, TT is used instead.

         \sstitem
         If the TEB timescale is specified, TDB is used instead.

         \sstitem
         The LOCAL timescale is not supported.

         \sstitem
         The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a
         reference position to be specified. Consequently, any $<$refpos$>$
         specified within the Time or Space sub-phrase of an STC-S document
         is ignored.

         \sstitem
         The Convex identifier for the space sub-phrase is not supported.

         \sstitem
         The GEO\_C and GEO\_D space frames are not supported.

         \sstitem
         The UNITSPHERE and SPHER3 space flavours are not supported.

         \sstitem
         If any Error values are supplied in a space sub-phrase, then the
         number of values supplied should equal the number of spatial axes,
         and the values are assumed to specify an error box (i.e. error
         circles, ellipses, etc, are not supported).

         \sstitem
         The spectral and redshift sub-phrases do not support the
         following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos,
         EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS,
         NEPTUNE, PLUTO.

         \sstitem
         Error values are supported but error ranges are not.

         \sstitem
         Resolution, PixSize and Size values are ignored.

         \sstitem
         Space velocity sub-phrases are ignored.
      }
   }
   \sstconstructor{
      \htmlref{astStcsChan}{astStcsChan}
   }
   \sstdiytopic{
      Inheritance
   }{
      The StcsChan class inherits from the Channel class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Channels, every
      StcsChan also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S?

         \sstitem
         \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S?

         \sstitem
         \htmlref{StcsLength}{StcsLength}: Controls output buffer length

         \sstitem
         \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S?
      }
   }
   \sstdiytopic{
      Functions
   }{
      The StcsChan class does not define any new functions beyond those
      which are applicable to all Channels.
   }
}
\sstroutine{
   SwitchMap
}{
   A Mapping that encapsulates a set of alternate Mappings
}{
   \sstdescription{
      A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate
      Mappings, each of which is used to transform positions within a
      particular region of the input or output coordinate system of the
      SwitchMap.

      A SwitchMap can encapsulate any number of Mappings, but they must
      all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the
      same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself
      inherits these same values for its Nin and Nout attributes. Each of
      these Mappings represents a \texttt{"} route\texttt{"}  through the switch, and are
      referred to as \texttt{"} route\texttt{"}  Mappings below. Each route Mapping transforms
      positions between the input and output coordinate space of the entire
      SwitchMap, but only one Mapping will be used to transform any given
      position. The selection of the appropriate route Mapping to use with
      any given input position is made by another Mapping, called the
      \texttt{"} selector\texttt{"}  Mapping. Each SwitchMap encapsulates two selector
      Mappings in addition to its route Mappings; one for use with the
      SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector
      Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation
      (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping
      must have the same number of inputs as the route Mappings, but
      should have only one output. Likewise, the inverse selector Mapping
      must have the same number of outputs as the route Mappings, but
      should have only one input.

      When the SwitchMap is used to transform a position in the forward
      direction (from input to output), each supplied input position is
      first transformed by the forward transformation of the forward selector
      Mapping. This produces a single output value for each input position
      referred to as the selector value. The nearest integer to the selector
      value is found, and is used to index the array of route Mappings (the
      first supplied route Mapping has index 1, the second route Mapping has
      index 2, etc). If the nearest integer to the selector value is less
      than 1 or greater than the number of route Mappings, then the SwitchMap
      output position is set to a value of AST\_\_BAD on every axis. Otherwise,
      the forward transformation of the selected route Mapping is used to
      transform the supplied input position to produce the SwitchMap output
      position.

      When the SwitchMap is used to transform a position in the inverse
      direction (from \texttt{"} output\texttt{"}  to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"}  position
      is first transformed by the inverse transformation of the inverse
      selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"}
      position. Again, the nearest integer to the selector value is found,
      and is used to index the array of route Mappings. If this selector
      index value is within the bounds of the array of route Mappings, then
      the inverse transformation of the selected route Mapping is used to
      transform the supplied \texttt{"} output\texttt{"}  position to produce the SwitchMap
      \texttt{"} input\texttt{"}  position. If the selector index value is outside the bounds
      of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"}  position is
      set to a value of AST\_\_BAD on every axis.

      In practice, appropriate selector Mappings should be chosen to
      associate a different route Mapping with each region of coordinate
      space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly
      appropriate for this purpose.

      If a compound Mapping contains a SwitchMap in series with its own
      inverse, the combination of the two adjacent SwitchMaps will be
      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
      \htmlref{astSimplify}{astSimplify}.
   }
   \sstconstructor{
      \htmlref{astSwitchMap}{astSwitchMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The SwitchMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The SwitchMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The SwitchMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   Table
}{
   A 2-dimensional table of values
}{
   \sstdescription{
      The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional
      table of values. The
      astMapGet... and astMapPut...
      methods provided by the KeyMap class should be used for storing and
      retrieving values from individual cells within a Table. Each entry
      in the KeyMap represents a single cell of the table and has an
      associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"}  where \texttt{"} $<$COL$>$\texttt{"}  is the
      upper-case name of a table column and \texttt{"} i\texttt{"}  is the row index (the
      first row is row 1). Keys of this form should always be used when
      using KeyMap methods to access entries within a Table.

      Columns must be declared using the
      \htmlref{astAddColumn}{astAddColumn}
      method before values can be stored within them. This also fixes the
      type and shape of the values that may be stored in any cell of the
      column. Cells may contain scalar or vector values of any data type
      supported by the KeyMap class. Multi-dimensional arrays may also be
      stored, but these must be vectorised when storing and retrieving
      them within a table cell. All cells within a single column must
      have the same type and shape, as specified when the column is added
      to the Table.

      Tables may have parameters that describe global properties of the
      entire table. These are stored as entries in the parent KeyMap and
      can be access using the get and set method of the KeyMap class.
      However, parameters must be declared using the
      \htmlref{astAddParameter}{astAddParameter}
      method before being accessed.

      Note - since accessing entries within a KeyMap is a relatively slow
      process, it is not recommended to use the Table class to store
      very large tables.
   }
   \sstconstructor{
      \htmlref{astTable}{astTable}
   }
   \sstdiytopic{
      Inheritance
   }{
      The Table class inherits from the KeyMap class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all KeyMaps, every
      Table also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column

         \sstitem
         \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column

         \sstitem
         \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column

         \sstitem
         \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column

         \sstitem
         ColumnUnit(column): The unit string describing each value in a column

         \sstitem
         \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table

         \sstitem
         \htmlref{Nrow}{Nrow}: The number of rows currently in the Table

         \sstitem
         \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table
      }
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all KeyMaps, the
      following functions may also be applied to all Tables:

      \sstitemlist{

         \sstitem
         \htmlref{astAddColumn}{astAddColumn}: Add a new column definition to a Table

         \sstitem
         \htmlref{astAddParameter}{astAddParameter}: Add a new global parameter definition to a Table

         \sstitem
         \htmlref{astColumnName}{astColumnName}: Return the name of the column with a given index

         \sstitem
         \htmlref{astColumnShape}{astColumnShape}: Return the shape of the values in a named column

         \sstitem
         \htmlref{astHasColumn}{astHasColumn}: Checks if a column exists in a Table

         \sstitem
         \htmlref{astHasParameter}{astHasParameter}: Checks if a global parameter exists in a Table

         \sstitem
         \htmlref{astParameterName}{astParameterName}: Return the name of the parameter with a given index

         \sstitem
         \htmlref{astPurgeRows}{astPurgeRows}: Remove all empty rows from a Table

         \sstitem
         \htmlref{astRemoveColumn}{astRemoveColumn}: Remove a column from a Table

         \sstitem
         \htmlref{astRemoveParameter}{astRemoveParameter}: Remove a global parameter from a Table

         \sstitem
         \htmlref{astRemoveRow}{astRemoveRow}: Remove a row from a Table
      }
   }
}
\sstroutine{
   TimeFrame
}{
   Time coordinate system description
}{
   \sstdescription{
      A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
      represents various coordinate systems used to describe positions in
      time.

      A TimeFrame represents a moment in time as either an Modified Julian
      Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch,
      as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be
      specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame
      representing time offsets from the specified zero point.

      Even though JD and MJD are defined as being in units of days, the
      TimeFrame class allows other units to be used (via the Unit attribute)
      on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1
      hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs
      can be described in units other than the usual years. Besselian epoch
      are always represented in units of (tropical) years.

      The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that
      is, the physical process used to define the rate of flow of time).
      MJD, JD and Julian epoch can be used to represent a time in any
      supported time scale. However, Besselian epoch may only be used with the
      \texttt{"} TT\texttt{"}  (Terrestrial Time) time scale. The list of supported time scales
      includes universal time and siderial time. Strictly, these represent
      angles rather than time scales, but are included in the list since
      they are in common use and are often thought of as time scales.

      When a time value is formatted it can be formated either as a simple
      floating point value, or as a Gregorian date (see the Format
      attribute).
   }
   \sstconstructor{
      \htmlref{astTimeFrame}{astTimeFrame}
   }
   \sstdiytopic{
      Inheritance
   }{
      The TimeFrame class inherits from the Frame class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Frames, every
      TimeFrame also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames

         \sstitem
         \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours.

         \sstitem
         \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values

         \sstitem
         \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame

      }
      Several of the Frame attributes inherited by the TimeFrame class
      refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)},
      \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional,
      it allows these attributes to be specified without an axis index.
      So for instance, \texttt{"} Unit\texttt{"}  is allowed in place of \texttt{"} Unit(1)\texttt{"} .
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Frames, the
      following functions may also be applied to all TimeFrames:

      \sstitemlist{

         \sstitem
         \htmlref{astCurrentTime}{astCurrentTime}: Return the current system time
      }
   }
}
\sstroutine{
   TimeMap
}{
   Sequence of time coordinate conversions
}{
   \sstdescription{
      A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be
      used to represent a sequence of conversions between standard time
      coordinate systems.

      When a TimeMap is first created, it simply performs a unit
      (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd}
      function, a series of coordinate conversion steps may then be
      added. This allows multi-step conversions between a variety of
      time coordinate systems to be assembled out of a set of building
      blocks.

      For details of the individual coordinate conversions available,
      see the description of the astTimeAdd function.
   }
   \sstconstructor{
      \htmlref{astTimeMap}{astTimeMap} (also see astTimeAdd)
   }
   \sstdiytopic{
      Inheritance
   }{
      The TimeMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The TimeMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      In addition to those functions applicable to all Mappings, the
      following function may also be applied to all TimeMaps:

      \sstitemlist{

         \sstitem
         \htmlref{astTimeAdd}{astTimeAdd}: Add a time coordinate conversion to an TimeMap
      }
   }
}
\sstroutine{
   TranMap
}{
   Mapping with specified forward and inverse transformations
}{
   \sstdescription{
      A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of
      a supplied Mapping with the inverse transformation of another
      supplied Mapping, ignoring the un-used transformation in each
      Mapping (indeed the un-used transformation need not exist).

      When the forward transformation of the TranMap is referred to, the
      transformation actually used is the forward transformation of the
      first Mapping supplied when the TranMap was constructed. Likewise,
      when the inverse transformation of the TranMap is referred to, the
      transformation actually used is the inverse transformation of the
      second Mapping supplied when the TranMap was constructed.
   }
   \sstconstructor{
      \htmlref{astTranMap}{astTranMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The TranMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The TranMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The TranMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   UnitMap
}{
   Unit (null) Mapping
}{
   \sstdescription{
      A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the
      coordinates supplied to it. They are simply copied. This can be
      useful if a Mapping is required (e.g. to pass to another
      function) but you do not want it to have any effect.
      The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and
      are specified when it is created.
   }
   \sstconstructor{
      \htmlref{astUnitMap}{astUnitMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The UnitMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The UnitMap class does not define any new attributes beyond
      those which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The UnitMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   UnitNormMap
}{
   Convert a vector to a unit vector and its norm, relative to a specified centre
}{
   \sstdescription{
      The forward transformation of a UnitNormMap subtracts the specified centre
      and then transforms the resulting vector to a unit vector and the vector norm.
      The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs
      are in the same order as the input; the final output is the norm.

      The inverse transformation of a UnitNormMap multiplies each component
      of the provided vector by the provided norm and adds the specified centre.
      The output contains one fewer coordinate than the input: the initial Nin inputs
      are in the same order as the output; the final input is the norm.

      UnitNormMap enables radially symmetric transformations, as follows:
      \sstitemlist{

         \sstitem
         apply a UnitNormMap to produce a unit vector and norm (radius)

         \sstitem
         apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged

         \sstitem
         apply the same UnitNormMap in the inverse direction to produce the result
      }
   }
   \sstconstructor{
      \htmlref{astUnitNormMap}{astUnitNormMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class.
   }
   \sstdiytopic{
      Attributes
   }{
      The UnitNormMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The UnitNormMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   WcsMap
}{
   Implement a FITS-WCS sky projection
}{
   \sstdescription{
      This class is used to represent sky coordinate projections as
      described in the FITS world coordinate system (FITS-WCS) paper II
      \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"}  by M. Calabretta
      and E.W. Griesen. This paper defines a set of functions, or sky
      projections, which transform longitude-latitude pairs representing
      spherical celestial coordinates into corresponding pairs of Cartesian
      coordinates (and vice versa).

      A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these
      sky projections and applies them to a specified pair of coordinates.
      All the projections in the FITS-WCS paper are supported, plus the now
      deprecated \texttt{"} TAN with polynomial correction terms\texttt{"}  projection which
      is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology,
      the transformation is between \texttt{"} native spherical\texttt{"}  and \texttt{"} projection
      plane\texttt{"}  coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} .
      These coordinates may, optionally, be embedded in a space with more
      than two dimensions, the remaining coordinates being copied unchanged.
      Note, however, that for consistency with other AST facilities, a
      WcsMap handles coordinates that represent angles in radians (rather
      than the degrees used by FITS-WCS).

      The type of FITS-WCS projection to be used and the coordinates
      (axes) to which it applies are specified when a WcsMap is first
      created. The projection type may subsequently be determined
      using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts
      may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute.

      Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"}  to be
      associated with each axis. These specify the precise form of the
      projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"}  is
      the integer axis index (starting at 1), and m is an integer
      \texttt{"} parameter index\texttt{"}  in the range 0 to 99. The number of projection
      parameters required by each projection, and their meanings, are
      dependent upon the projection type (most projections either do not
      use any projection parameters, or use parameters 1 and 2 associated
      with the latitude axis). Before creating a WcsMap you should consult
      the FITS-WCS paper for details of which projection parameters are
      required, and which have defaults. When creating the WcsMap, you must
      explicitly set values for all those required projection parameters
      which do not have defaults defined in this paper.
   }
   \sstconstructor{
      \htmlref{astWcsMap}{astWcsMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The WcsMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      WcsMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection

         \sstitem
         \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection

         \sstitem
         \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters

         \sstitem
         PVMax: Maximum number of FITS-WCS projection parameters

         \sstitem
         \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes

         \sstitem
         \htmlref{WcsType}{WcsType}: FITS-WCS projection type
      }
   }
   \sstdiytopic{
      Functions
   }{
      The WcsMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   WinMap
}{
   Map one window on to another by scaling and shifting each axis
}{
   \sstdescription{
      A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular
      window in one coordinate system into a similar window in another
      coordinate system by scaling and shifting each axis (the window
      edges being parallel to the coordinate axes).

      A WinMap is specified by giving the coordinates of two opposite
      corners (A and B) of the window in both the input and output
      coordinate systems.
   }
   \sstconstructor{
      \htmlref{astWinMap}{astWinMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The WinMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      The WinMap class does not define any new attributes beyond those
      which are applicable to all Mappings.
   }
   \sstdiytopic{
      Functions
   }{
      The WinMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   XmlChan
}{
   I/O Channel using XML to represent Objects
}{
   \sstdescription{
      A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O
      operations. Writing an \htmlref{Object}{Object} to an XmlChan (using
      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
      XML description of that Object, and reading from an XmlChan will
      create a new Object from its XML description.

      Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"}
      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
      by reading and writing the resulting XML text. These functions
      should perform any conversions needed between external character
      encodings and the internal ASCII encoding. If no such functions
      are supplied, a Channel will read from standard input and write
      to standard output.

      Alternatively, an XmlChan can be told to read or write from
      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
      in which case no sink or source function need be supplied.
   }
   \sstconstructor{
      \htmlref{astXmlChan}{astXmlChan}
   }
   \sstdiytopic{
      Inheritance
   }{
      The XmlChan class inherits from the Channel class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Channels, every
      XmlChan also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML

         \sstitem
         \htmlref{XmlLength}{XmlLength}: Controls output buffer length

         \sstitem
         \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing
      }
   }
   \sstdiytopic{
      Functions
   }{
      The XmlChan class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\sstroutine{
   ZoomMap
}{
   Zoom coordinates about the origin
}{
   \sstdescription{
      The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"}
      transformation by multiplying all coordinate values by the same
      scale factor (the inverse transformation is performed by
      dividing by this scale factor). The number of coordinate values
      representing each point is unchanged.
   }
   \sstconstructor{
      \htmlref{astZoomMap}{astZoomMap}
   }
   \sstdiytopic{
      Inheritance
   }{
      The ZoomMap class inherits from the Mapping class.
   }
   \sstdiytopic{
      Attributes
   }{
      In addition to those attributes common to all Mappings, every
      ZoomMap also has the following attributes:

      \sstitemlist{

         \sstitem
         \htmlref{Zoom}{Zoom}: ZoomMap scale factor
      }
   }
   \sstdiytopic{
      Functions
   }{
      The ZoomMap class does not define any new functions beyond those
      which are applicable to all Mappings.
   }
}
\normalsize

\cleardoublepage
\section{\label{ss:commanddescriptions}UNIX Command Descriptions}
The commands described here are provided for use from the UNIX shell
to assist with developing software which uses AST. To use these
commands, you should ensure that the directory
``/star/bin''\footnote{Or the equivalent directory if AST is installed
in a non-standard location.} is on your PATH.
\small
\sstroutine{
   ast\_link
}{
   Link a program with the AST library
}{
   \sstdescription{
      This command should be used when building programs which use the AST
      library, in order to generate the correct arguments to allow the compiler
      to link your program. The arguments generated are written to standard
      output but may be substituted into the compiler command line in the
      standard UNIX way using backward quotes (see below).

      By default, it is assumed that you are building a stand-alone program
      which does not produce graphical output. However, switches are provided
      for linking other types of program.
   }
   \sstinvocation{
      cc program.c -L/star/lib `ast\_link [switches]` -o program
   }
   \sstexamples{
      \sstexamplesubsection{
         cc display.c -L/star/lib `ast\_link -pgplot` -o display
      }{
         Compiles and links a C program called ``display\texttt{'} \texttt{'}  which uses
         the standard version of PGPLOT for graphical output.
      }
      \sstexamplesubsection{
         cc plotit.c -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit
      }{
         Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'}
         switch indicates that graphical output will be delivered through
         a graphical interface which you have implemented yourself, which
         corresponds to the interface required by the current version of AST.
         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
         reference.
      }
      \sstexamplesubsection{
         cc plotit.c -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit
      }{
         Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'}
         switch indicates that graphical output will be delivered through
         a graphical interface which you have implemented yourself, which
         corresponds to the interface required by version 2.0 of AST.
         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
         reference.
      }
   }
   \sstdiytopic{
      Switches
   }{
      The following switches may optionally be given to this command to
      modify its behaviour:

      \sstitemlist{

         \sstitem
         ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.

         \sstitem
         ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.

         \sstitem
         ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages
         produced by the AST library are delivered via the Starlink EMS (Error
         Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default,
         error messages are simply written to standard error.

         \sstitem
         ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages
         produced by the AST library are delivered via the DRAMA Ers (Error
         Reporting Service) library. By default, error messages are simply
         written to standard error.

         \sstitem
         ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
         2D graphics system is used to display output from the AST library. You
         should use this option only if you have implemented an interface to a
         new graphics system yourself and wish to provide your own arguments for
         linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'}  switches in
         that it assumes that your graphics module implements the complete
         interface required by the current version of AST. If future versions of
         AST introduce new functions to the graphics interface, this switch will
         cause ``unresolved symbol\texttt{'} \texttt{'}  errors to occur during linking, warning you
         that you need to implement new functions in your graphics module. To
         avoid such errors, you can use one of the other, version-specific,
         switches in place of the ``-grf\texttt{'} \texttt{'}  switch, but these will cause run-time
         errors to be reported if any AST function is invoked which requires
         facilities not in the implemented interface.

         \sstitem
         ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'}  switch.
         It indicates that you want to link with your own graphics module
         which implements the 2D graphics interface required by V2.0 of AST.

         \sstitem
         ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own
         graphics module which implements the 2D graphics interface required by
         V3.2 of AST.

         \sstitem
         ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own
         graphics module which implements the 2D graphics interface required by
         V5.6 of AST.

         \sstitem
         ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how
         error messages produced by the AST library should be delivered. You
         should use this option only if you have implemented an interface to a
         new error delivery system yourself and wish to provide your own
         arguments for linking with it.

         \sstitem
         ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'}  switch,
         but is retained in order to allow applications to be linked with a
         graphics module which implements the 2D interface used by AST V2.0. It
         is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'}  switch.

         \sstitem
         ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
         graphical output from the AST library is displayed via the
         Starlink version of the PGPLOT graphics package (which uses GKS
         for its output). By default, no 2D graphics package is linked and
         this will result in an error at run time if AST routines are
         invoked that attempt to generate graphical output.

         \sstitem
         ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
         graphical output from the AST library is displayed via
         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
         package. By default, no 2D graphics package is linked and this will
         result in an error at run time if AST routines are invoked that
         attempt to generate graphical output.

         \sstitem
         ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
         3D graphics system is used to display output from the AST library. You
         should use this option only if you have implemented an interface to a
         new 3D graphics system yourself and wish to provide your own arguments
         for linking with it.

         \sstitem
         ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
         graphical output from the AST library is displayed via the
         Starlink version of the PGPLOT graphics package (which uses GKS
         for its output). By default, no 3D graphics package is linked and
         this will result in an error at run time if AST routines are
         invoked that attempt to generate graphical output.

         \sstitem
         ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
         graphical output from the AST library is displayed via
         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
         package. By default, no 3D graphics package is linked and this will
         result in an error at run time if AST routines are invoked that
         attempt to generate graphical output.
      }
   }
   \sstdiytopic{
      ERFA \& PAL
   }{
      The AST distribution includes bundled copies of the ERFA and PAL
      libraries. These will be used for fundamental positional astronomy
      calculations unless the \texttt{"} --with-external\_pal\texttt{"}  option was used when
      AST was configured. If \texttt{"} --with-external\_pal\texttt{"}  is used, this script
      will include \texttt{"} -lpal\texttt{"}  in the returned list of linking options, and
      the user should then ensure that external copies of the PAL and
      ERFA libraries are available (ERFA functions are used within PAL).
   }
}
\sstroutine{
   ast\_link\_adam
}{
   Link an ADAM program with the AST library
}{
   \sstdescription{
      This command should only be used when building Starlink ADAM programs
      which use the AST library, in order to generate the correct arguments
      to allow the ADAM ``alink\texttt{'} \texttt{'}  command to link the program. The arguments
      generated are written to standard output but may be substituted into
      the ``alink\texttt{'} \texttt{'}  command line in the standard UNIX way using backward
      quotes (see below).

      By default, it is assumed that you are building an ADAM program which
      does not produce graphical output. However, switches are provided for
      linking other types of program. This command should not be used when
      building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'}  command
      instead.
   }
   \sstinvocation{
      alink program.o -L/star/lib `ast\_link\_adam [switches]`
   }
   \sstexamples{
      \sstexamplesubsection{
         alink display.o -L/star/lib `ast\_link\_adam -pgplot`
      }{
         Links an ADAM program ``display\texttt{'} \texttt{'}  which uses the standard
         version of PGPLOT for graphical output.
      }
      \sstexamplesubsection{
         alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf` -lgrf
      }{
         Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\texttt{'} \texttt{'}
         switch indicates that graphical output will be delivered through
         a graphical interface which you have implemented yourself, which
         corresponds to the interface required by the current version of AST.
         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
         reference.
      }
      \sstexamplesubsection{
         alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf
      }{
         Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\_v2.0\texttt{'} \texttt{'}
         switch indicates that graphical output will be delivered through
         a graphical interface which you have implemented yourself, which
         corresponds to the interface required by version 2.0 of AST. Here,
         this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
         reference.
      }
   }
   \sstdiytopic{
      Switches
   }{
      The following switches may optionally be given to this command to
      modify its behaviour:

      \sstitemlist{

         \sstitem
         ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.

         \sstitem
         ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.

         \sstitem
         ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
         2D graphics system is used to display output from the AST library. You
         should use this option only if you have implemented an interface to a
         new graphics system yourself and wish to provide your own arguments for
         linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'}  switches in
         that it assumes that your graphics module implements the complete
         interface required by the current version of AST. If future versions of
         AST introduce new functions to the graphics interface, this switch will
         cause ``unresolved symbol\texttt{'} \texttt{'}  errors to occur during linking, warning you
         that you need to implement new functions in your graphics module. To
         avoid such errors, you can use one of the other, version-specific,
         switches in place of the ``-grf\texttt{'} \texttt{'}  switch, but these will cause run-time
         errors to be reported if any AST function is invoked which requires
         facilities not in the implemented interface.

         \sstitem
         ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'}  switch.
         It indicates that you want to link with your own graphics module which
         implements the 2D graphics interface required by V2.0 of AST.

         \sstitem
         ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics
         module which implements the 2D graphics interface required by V3.2 of AST.

         \sstitem
         ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics
         module which implements the 2D graphics interface required by V5.6 of AST.

         \sstitem
         ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how
         error messages produced by the AST library should be delivered. You
         should use this option only if you have implemented an interface to a
         new error delivery system yourself and wish to provide your own
         arguments for linking with it. By default, error messages are delivered
         in the standard ADAM way via the EMS Error Message Service (Starlink
         \htmlref{System}{System} Note SSN/4).

         \sstitem
         ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'}  switch,
         but is retained in order to allow applications to be linked with a
         graphics module which implements the interface used by AST V2.0. It is
         equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'}  switch.

         \sstitem
         ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
         graphical output from the AST library is displayed via the
         Starlink version of the PGPLOT graphics package (which uses GKS
         for its output). By default, no graphics package is linked and
         this will result in an error at run time if AST routines are
         invoked that attempt to generate graphical output.

         \sstitem
         ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
         graphical output from the AST library is displayed via the
         standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
         package. By default, no graphics package is linked and this will
         result in an error at run time if AST routines are invoked that
         attempt to generate graphical output.

         \sstitem
         ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
         3D graphics system is used to display output from the AST library. You
         should use this option only if you have implemented an interface to a
         new 3D graphics system yourself and wish to provide your own arguments
         for linking with it.

         \sstitem
         ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
         graphical output from the AST library is displayed via the
         Starlink version of the PGPLOT graphics package (which uses GKS
         for its output). By default, no 3D graphics package is linked and
         this will result in an error at run time if AST routines are
         invoked that attempt to generate graphical output.

         \sstitem
         ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
         graphical output from the AST library is displayed via
         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
         package. By default, no 3D graphics package is linked and this will
         result in an error at run time if AST routines are invoked that
         attempt to generate graphical output.
      }
   }
   \sstdiytopic{
      SLALIB
   }{
      The AST distribution includes a cut down subset of the C version of
      the SLALIB library written by Pat Wallace. This subset contains only
      the functions needed by the AST library. It is built as part of the
      process of building AST and is distributed under GPL (and is thus
      compatible with the AST license). Previous version of this script
      allowed AST applications to be linked against external SLALIB
      libraries (either Fortran or C) rather than the internal version.
      The current version of this script does not provide this option,
      and always uses the internal SLALIB library. However, for backward
      compatibility, this script still allows the \texttt{"} -fsla\texttt{"}  and \texttt{"} -csla\texttt{"}  flags
      (previously used for selecting which version of SLALIB to use) to be
      specified, but they will be ignored.
   }
}
\normalsize

\cleardoublepage
\section{\label{ss:memoryfunctions}AST Memory Management and Utility Functions}
AST provides a memory management layer that can be used in place of
system functions such as \texttt{malloc}, \texttt{free}, \texttt{realloc},
\emph{etc.} The AST replacements for these functions ( \texttt{\htmlref{astMalloc}{astMalloc}},
\texttt{\htmlref{astFree}{astFree}} and \texttt{\htmlref{astRealloc}{astRealloc}}) add extra information to each
allocated memory block that allows AST to check the validity of supplied
pointers. For example, this extra information allows \texttt{astFree} to
detect if the supplied pointer has already been freed, and if so to issue
an appropriate error message. The existence of this extra information is
invisible to outside callers, and stored in a header block located just
before the returned memory block.

In addition to the standard functions, AST provides other memory management
functions, such as:

\begin{description}
\item [\texttt{\htmlref{astStore}{astStore}}] - stores data in dynamically allocated memory, allocating
the memory (or adjusting the size of previously allocated memory) to match
the amount of data to be stored.
\item [\texttt{\htmlref{astGrow}{astGrow}}] - allocates and expands memory to hold an adjustable-sized array.
\item [\texttt{\htmlref{astAppendString}{astAppendString}}] - allocates and expands memory to hold a
concatenated string.
\end{description}

Theses are just a few of the available utilities functions in the AST
memory management layer. Prototypes for all AST memory management
functions are included in the header file ``\texttt{ast.h}''.

An important restriction on these functions is that pointers created by
other memory management functions, such as the system version of \texttt{malloc} \emph{etc.}, should never supplied to an AST memory management
function. Only pointers created by AST should be used by these functions.

In addition to memory management functions, AST provides various other
utility functions, such as a basic regular expression facility, and other
string manipulation functions. These are also documented in this appendix.

The AST memory management layer is implemented on top of the usual \texttt{malloc}, {tt free} and \texttt{realloc} functions. By default these will be
the standard functions provided by <stdlib.h>. However, the facilities of
the STARMEM package (included in the Starlink Software Collection) can be
used to specify alternative functions to use. This requires that AST be
configured using the ``--with-starmem'' option when it is built.

The STARMEM package provides a wrapper for the standard malloc
implementation that enables the user to switch malloc schemes at runtime
by setting the STARMEM\_MALLOC environment variable. Currently allowed
values for this variable are:

\begin{description}
\item [SYSTEM] - standard system malloc/free - the default
\item [DL] - Doug Lea's malloc/free
\item [GC] - Hans-Boehm Garbage Collection
\end{description}

\small
\sstroutine{
   astAppendString
}{
   Append a string to another string which grows dynamically
}{
   \sstdescription{
      This function appends one string to another dynamically
      allocated string, extending the dynamic string as necessary to
      accommodate the new characters (plus the final null).
   }
   \sstsynopsis{
      char $*$astAppendString( char $*$str1, int $*$nc, const char $*$str2 )
   }
   \sstparameters{
      \sstsubsection{
         str1
      }{
         Pointer to the null-terminated dynamic string, whose memory
         has been allocated using an AST memory allocation function.
         If no space has yet been allocated for this string, a NULL
         pointer may be given and fresh space will be allocated by this
         function.
      }
      \sstsubsection{
         nc
      }{
         Pointer to an integer containing the number of characters in
         the dynamic string (excluding the final null). This is used
         to save repeated searching of this string to determine its
         length and it defines the point where the new string will be
         appended. Its value is updated by this function to include
         the extra characters appended.

         If \texttt{"} str1\texttt{"}  is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"}  will
         be ignored and zero will be used.
      }
      \sstsubsection{
         str2
      }{
         Pointer to a constant null-terminated string, a copy of which
         is to be appended to \texttt{"} str1\texttt{"} .
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAppendString()
      }{
         A possibly new pointer to the dynamic string with the new string
         appended (its location in memory may have to change if it has to
         be extended, in which case the original memory is automatically
         freed by this function). When the string is no longer required,
         its memory should be freed using \htmlref{astFree}{astFree}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If this function is invoked with the global error status set
         or if it should fail for any reason, then the returned pointer
         will be equal to \texttt{"} str1\texttt{"}  and the dynamic string contents will be
         unchanged.
      }
   }
}
\sstroutine{
   astAppendStringf
}{
   Append a string to another string, allowing printf format specifiers
}{
   \sstdescription{
      This function appends one string to another dynamically
      allocated string, extending the dynamic string as necessary to
      accommodate the new characters (plus the final null). It is the
      same as \htmlref{astAppendString}{astAppendString}, except that the \texttt{"} str2\texttt{"}  string ay include
      printf format specifiers.
   }
   \sstsynopsis{
      char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... )
   }
   \sstparameters{
      \sstsubsection{
         str1
      }{
         Pointer to the null-terminated dynamic string, whose memory
         has been allocated using an AST memory allocation function.
         If no space has yet been allocated for this string, a NULL
         pointer may be given and fresh space will be allocated by this
         function.
      }
      \sstsubsection{
         nc
      }{
         Pointer to an integer containing the number of characters in
         the dynamic string (excluding the final null). This is used
         to save repeated searching of this string to determine its
         length and it defines the point where the new string will be
         appended. Its value is updated by this function to include
         the extra characters appended.

         If \texttt{"} str1\texttt{"}  is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"}  will
         be ignored and zero will be used.
      }
      \sstsubsection{
         str2
      }{
         Pointer to a constant null-terminated string, a copy of which
         is to be appended to \texttt{"} str1\texttt{"} . It may contain format
         specifications such as used with the C \texttt{"} printf\texttt{"}  family of
         functions.
      }
      \sstsubsection{
         ...
      }{
         Additional optional arguments (as used by e.g. \texttt{"} printf\texttt{"} )
         which specify values which are to be substituted into the \texttt{"} str2\texttt{"}
         string in place of any format specifications.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astAppendString()
      }{
         A possibly new pointer to the dynamic string with the new string
         appended (its location in memory may have to change if it has to
         be extended, in which case the original memory is automatically
         freed by this function). When the string is no longer required,
         its memory should be freed using \htmlref{astFree}{astFree}.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If this function is invoked with the global error status set
         or if it should fail for any reason, then the returned pointer
         will be equal to \texttt{"} str1\texttt{"}  and the dynamic string contents will be
         unchanged.
      }
   }
}
\sstroutine{
   astCalloc
}{
   Allocate and initialise memory
}{
   \sstdescription{
      This function allocates memory in a similar manner to the
      standard C \texttt{"} calloc\texttt{"}  function, but with improved security
      (against memory leaks, etc.) and with error reporting. It also
      fills the allocated memory with zeros.

      Like \htmlref{astMalloc}{astMalloc}, it allows zero-sized memory allocation
      (without error), resulting in a NULL returned pointer value.
   }
   \sstsynopsis{
      void $*$astCalloc( size\_t nmemb, size\_t size )
   }
   \sstparameters{
      \sstsubsection{
         nmemb
      }{
         The number of array elements for which memory is to be allocated.
      }
      \sstsubsection{
         size
      }{
         The size of each array element, in bytes.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astCalloc()
      }{
         If successful, the function returns a pointer to the start of
         the allocated memory region. If the size allocated is zero, this
         will be a NULL pointer.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      }
   }
}
\sstroutine{
   astChr2Double
}{
   read a double value from a string
}{
   \sstdescription{
      This function reads a double from the supplied null-terminated string,
      ignoring leading and trailing white space. AST\_\_BAD is ereturned
      without error if the string is not a numerical value.
   }
   \sstsynopsis{
      double astChr2Double( const char $*$str )
   }
   \sstparameters{
      \sstsubsection{
         str
      }{
         Pointer to the string.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChr2Double()
      }{
         The double value, or AST\_\_BAD.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of AST\_\_BAD is returned if this function is invoked with
         the global error status set or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astChrCase
}{
   Convert a string to upper or lower case
}{
   \sstdescription{
      This function converts a supplied string to upper or lower case,
      storing the result in a supplied buffer. The \htmlref{astStringCase}{astStringCase} function
      is similar, but stores the result in a dynamically allocated buffer.
   }
   \sstsynopsis{
      void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status )
   }
   \sstparameters{
      \sstsubsection{
         in
      }{
         Pointer to the null terminated string to be converted. If this
         is NULL, the supplied contents of the \texttt{"} out\texttt{"}  string are used as
         the input string.
      }
      \sstsubsection{
         out
      }{
         Pointer to the buffer to receive the converted string. The
         length of this buffer is given by \texttt{"} blen\texttt{"} . If NULL is supplied
         for \texttt{"} in\texttt{"} , then the supplied contents of \texttt{"} out\texttt{"}  are converted and
         written back into \texttt{"} out\texttt{"}  over-writing the supplied contents.
      }
      \sstsubsection{
         upper
      }{
         If non-zero, the string is converted to upper case. Otherwise it
         is converted to lower case.
      }
      \sstsubsection{
         blen
      }{
         The length of the output buffer. Ignored if \texttt{"} in\texttt{"}  is NULL. No
         more than \texttt{"} blen - 1\texttt{"}  characters will be copied from \texttt{"} in\texttt{"}  to
         \texttt{"} out\texttt{"} , and a terminating null character will then be added.
      }
   }
}
\sstroutine{
   astChrLen
}{
   Determine the used length of a string
}{
   \sstdescription{
      This function returns the used length of a string. This excludes any
      trailing white space or non-printable characters (such as the
      trailing null character).
   }
   \sstsynopsis{
      size\_t astChrLen( const char $*$string )
   }
   \sstparameters{
      \sstsubsection{
         string
      }{
         Pointer to the string.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrLen()
      }{
         The number of characters in the supplied string, not including the
         trailing newline, and any trailing white-spaces or non-printable
         characters.
      }
   }
}
\sstroutine{
   astChrMatch
}{
   Case insensitive string comparison
}{
   \sstdescription{
      This function compares two null terminated strings for equality,
      discounting differences in case and any trailing white space in either
      string.
   }
   \sstsynopsis{
      int astChrMatch( const char $*$str1, const char $*$str2 )
   }
   \sstparameters{
      \sstsubsection{
         str1
      }{
         Pointer to the first string.
      }
      \sstsubsection{
         str2
      }{
         Pointer to the second string.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrMatch()
      }{
         Non-zero if the two strings match, otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero is returned if this function is invoked with the
         global error status set or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astChrMatchN
}{
   Case insensitive string comparison of at most N characters
}{
   \sstdescription{
      This function compares two null terminated strings for equality,
      discounting differences in case and any trailing white space in either
      string. No more than \texttt{"} n\texttt{"}  characters are compared.
   }
   \sstsynopsis{
      int astChrMatchN( const char $*$str1, const char $*$str2, size\_t n )
   }
   \sstparameters{
      \sstsubsection{
         str1
      }{
         Pointer to the first string.
      }
      \sstsubsection{
         str2
      }{
         Pointer to the second string.
      }
      \sstsubsection{
         n
      }{
         Maximum number of characters to compare.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrMatchN()
      }{
         Non-zero if the two strings match, otherwise zero.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero is returned if this function is invoked with the
         global error status set or if it should fail for any reason.
      }
   }
}
\sstroutine{
   astChrSplit
}{
   Extract words from a supplied string
}{
   \sstdescription{
      This function extracts all space-separated words form the supplied
      string and returns them in an array of dynamically allocated strings.
   }
   \sstsynopsis{
      char $*$$*$astChrSplit\_( const char $*$str, int $*$n )
   }
   \sstparameters{
      \sstsubsection{
         str
      }{
         Pointer to the string to be split.
      }
      \sstsubsection{
         n
      }{
         Address of an int in which to return the number of words returned.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrSplit()
      }{
         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a word extracted from the supplied string. Each
         of these words will have no leading or trailing white space.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      }
   }
}
\sstroutine{
   astChrSplitC
}{
   Split a string using a specified character delimiter
}{
   \sstdescription{
      This function extracts all sub-strings separated by a given
      character from the supplied string and returns them in an array
      of dynamically allocated strings. The delimiter character itself
      is not included in the returned strings.

      Delimiter characters that are preceded by \texttt{"} $\backslash$\texttt{"}  are not used as
      delimiters but are included in the returned word instead (without
      the \texttt{"} $\backslash$\texttt{"} ).
   }
   \sstsynopsis{
      char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n )
   }
   \sstparameters{
      \sstsubsection{
         str
      }{
         Pointer to the string to be split.
      }
      \sstsubsection{
         c
      }{
         The delimiter character.
      }
      \sstsubsection{
         n
      }{
         Address of an int in which to return the number of words returned.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrSplitC()
      }{
         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a word extracted from the supplied string.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      }
   }
}
\sstroutine{
   astChrSplitRE
}{
   Extract sub-strings matching a specified regular expression
}{
   \sstdescription{
      This function compares the supplied string with the supplied
      regular expression. If they match, each section of the test string
      that corresponds to a parenthesised sub-string in the regular
      expression is copied and stored in the returned array.
   }
   \sstsynopsis{
      char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n,
                            const char $*$$*$matchend )
   }
   \sstparameters{
      \sstsubsection{
         str
      }{
         Pointer to the string to be split.
      }
      \sstsubsection{
         regexp
      }{
         The regular expression. See \texttt{"} Template Syntax:\texttt{"}  in the \htmlref{astChrSub}{astChrSub}
         prologue. Note, this function differs from astChrSub in that any
         equals signs (=) in the regular expression are treated literally.
      }
      \sstsubsection{
         n
      }{
         Address of an int in which to return the number of sub-strings
         returned.
      }
      \sstsubsection{
         matchend
      }{
         A pointer to a location at which to return a pointer to the
         character that follows the last character within the supplied test
         string that matched any parenthesises sub-section of \texttt{"} regexp\texttt{"} . A
         NULL pointer is returned if no matches were found. A NULL pointer
         may be supplied if the location of the last matching character is
         not needed.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrSplitRE()
      }{
         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
         Each element is a pointer to a dynamically allocated character
         string containing a sub-string extracted from the supplied string.
         The array itself, and the strings within it, should all be freed
         using \htmlref{astFree}{astFree} when no longer needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If a parenthesised sub-string in the regular expression is matched
         by more than one sub-string within the test string, then only the
         first is returned. To return multiple matches, the regular
         expression should include multiple copies of the parenthesised
         sub-string (for instance, separated by \texttt{"} .$+$?\texttt{"}  if the intervening
         string is immaterial).

         \sstitem
         A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied string contains no words.
      }
   }
}
\sstroutine{
   astChrSub
}{
   Performs substitutions on a supplied string
}{
   \sstdescription{
      This function checks a supplied test string to see if it matches a
      supplied template. If it does, specified sub-sections of the test
      string may optionally be replaced by supplied substitution strings.
      The resulting string is returned.
   }
   \sstsynopsis{
      char $*$astChrSub( const char $*$test, const char $*$pattern,
                       const char $*$subs[], int nsub )
   }
   \sstparameters{
      \sstsubsection{
         test
      }{
         The string to be tested.
      }
      \sstsubsection{
         pattern
      }{
         The template string. See \texttt{"} Template Syntax:\texttt{"}  below.
      }
      \sstsubsection{
         subs
      }{
         An array of strings that are to replace the sections of the test
         string that match each parenthesised sub-string in \texttt{"} pattern\texttt{"} . The
         first element of \texttt{"} subs\texttt{"}  replaces the part of the test string that
         matches the first parenthesised sub-string in the template, etc.

         If \texttt{"} nsub\texttt{"}  is zero, then the \texttt{"} subs\texttt{"}  pointer is ignored. In this
         case, substitution strings may be specified by appended them to
         the end of the \texttt{"} pattern\texttt{"}  string, separated by \texttt{"} =\texttt{"}  characters.
         Note, if you need to include a literal \texttt{"} =\texttt{"}  character in the
         pattern, precede it by an escape \texttt{"} $\backslash$\texttt{"}  character.
      }
      \sstsubsection{
         nsub
      }{
         The number of substitution strings supplied in array \texttt{"} subs\texttt{"} .
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astChrSub()
      }{
         A pointer to a dynamically allocated string holding the result
         of the substitutions, or NULL if the test string does not match
         the template string. This string should be freed using \htmlref{astFree}{astFree}
         when no longer needed. If no substituions are specified then a
         copy of the test string is returned if it matches the template.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A NULL pointer is returned if this function is invoked with the
         global error status set or if it should fail for any reason, or if
         the supplied test string does not match the template.
      }
   }
   \sstdiytopic{
      Template Syntax
   }{
      The template syntax is a minimal form of regular expression, The
      quantifiers allowed are \texttt{"} $*$\texttt{"} , \texttt{"} ?\texttt{"} , \texttt{"} $+$\texttt{"} , \texttt{"} \{n\}\texttt{"} , \texttt{"} $*$?\texttt{"}  and \texttt{"} $+$?\texttt{"}  (the
      last two are non-greedy - they match the minimum length possible
      that still gives an overall match to the template). The only
      constraints allowed are \texttt{"} $\wedge$\texttt{"}  and \texttt{"} \$\texttt{"} . The following atoms are allowed:

      \sstitemlist{

         \sstitem
         [chars]: Matches any of the specified characters.

         \sstitem
         [$\wedge$chars]: Matches anything but the specified characters.

         \sstitem
         .: Matches any single character.

         \sstitem
         x: Matches the character x so long as x has no other significance.

         \sstitem
         $\backslash$x: Always matches the character x (except for [dDsSwW]).

         \sstitem
         $\backslash$d: Matches a single digit.

         \sstitem
         $\backslash$D: Matches anything but a single digit.

         \sstitem
         $\backslash$w: Matches any alphanumeric character, and \texttt{"} \_\texttt{"} .

         \sstitem
         $\backslash$W: Matches anything but alphanumeric characters, and \texttt{"} \_\texttt{"} .

         \sstitem
         $\backslash$s: Matches white space.

         \sstitem
         $\backslash$S: Matches anything but white space.

      }
      Note, minus signs (\texttt{"} -\texttt{"} ) within brackets have no special significance,
      so ranges of characters must be specified explicitly.

      Multiple template strings can be concatenated, using the \texttt{"} $|$\texttt{"}
      character to separate them. The test string is compared against
      each one in turn until a match is found.

      Parentheses are used within each template to identify sub-strings
      that are to be replaced by the strings supplied in \texttt{"} sub\texttt{"} .

      If \texttt{"} nsub\texttt{"}  is supplied as zero, then substitution strings may be
      specified by appended them to the end of the \texttt{"} pattern\texttt{"}  string,
      separated by \texttt{"} =\texttt{"}  characters. If \texttt{"} nsub\texttt{"}  is not zero, then any
      substitution strings appended to the end of \texttt{"} pattern\texttt{"}  are ignored.

      Each element of \texttt{"} subs\texttt{"}
      may contain a reference to a token of the
      form \texttt{"} \$1\texttt{"} , \texttt{"} \$2\texttt{"} , etc. The \texttt{"} \$1\texttt{"}  token will be replaced by the part
      of the test string that matched the first parenthesised sub-string
      in \texttt{"} pattern\texttt{"} . The \texttt{"} \$2\texttt{"}  token will be replaced by the part of the
      test string that matched the second parenthesised sub-string in
      \texttt{"} pattern\texttt{"} , etc.
   }
}
\sstroutine{
   astChrTrunc
}{
   Terminate a string to exclude trailing spaces
}{
   \sstdescription{
      This function pokes a null character into the supplied string to
      remove any trailing spaces.
   }
   \sstsynopsis{
      void astChrTrunc( char $*$text )
   }
   \sstparameters{
      \sstsubsection{
         text
      }{
         The string to be truncated.
      }
   }
}
\sstroutine{
   astFree
}{
   Free previously allocated memory
}{
   \sstdescription{
      This function frees memory that has previouly been dynamically
      allocated using one of the AST memory function.
   }
   \sstsynopsis{
      void $*$astFree( void $*$ptr )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to previously allocated memory. An error will result
         if the memory has not previously been allocated by another
         function in this module. However, a NULL pointer value is
         accepted (without error) as indicating that no memory has yet
         been allocated, so that no action is required.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFree()
      }{
         Always returns a NULL pointer.
      }
   }
}
\sstroutine{
   astFreeDouble
}{
   Free previously double allocated memory
}{
   \sstdescription{
      This function frees memory that has previouly been dynamically
      allocated using one of the AST memory function. It assumes that
      the supplied pointer is a pointer to an array of pointers. Each
      of these pointers is first freed, and then the supplied pointer
      is freed.

      Note, this routine should not be used with arrays allocated
      by \htmlref{astGrow}{astGrow} since astGrow over-allocates and so there may be
      non-initialised pointers at the end of the array.
   }
   \sstsynopsis{
      void $*$astFreeDouble( void $*$ptr )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to previously allocated memory. An error will result
         if the memory has not previously been allocated by another
         function in this module. However, a NULL pointer value is
         accepted (without error) as indicating that no memory has yet
         been allocated, so that no action is required.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astFreeDouble()
      }{
         Always returns a NULL pointer.
      }
   }
}
\sstroutine{
   astGrow
}{
   Allocate memory for an adjustable array
}{
   \sstdescription{
      This function allocates memory in which to store an array of
      data whose eventual size is unknown. It should be invoked
      whenever a new array size is determined and will appropriately
      increase the amount of memory allocated when necessary. In
      general, it will over-allocate in anticipation of future growth
      so that the amount of memory does not need adjusting on every
      invocation.
   }
   \sstsynopsis{
      void $*$astGrow( void $*$ptr, int n, size\_t size )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to previously allocated memory (or NULL if none has
         yet been allocated).
      }
      \sstsubsection{
         n
      }{
         Number of array elements to be stored (may be zero).
      }
      \sstsubsection{
         size
      }{
         The size of each array element.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astGrow()
      }{
         If the memory was allocated successfully, a pointer to the start
         of the possibly new memory region is returned (this may be the
         same as the original pointer).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         When new memory is allocated, the existing contents are preserved.

         \sstitem
         This function does not free memory once it is allocated, so
         the size allocated grows to accommodate the maximum size of the
         array (or \texttt{"} high water mark\texttt{"} ). Other memory handling routines may
         be used to free the memory (or alter its size) if necessary.

         \sstitem
         If this function is invoked with the global error status set,
         or if it fails for any reason, the original pointer value is
         returned and the memory contents are unchanged.
      }
   }
}
\sstroutine{
   astIsDynamic
}{
   Returns a flag indicating if memory was allocated dynamically
}{
   \sstdescription{
      This function takes a pointer to a region of memory and tests if
      the memory has previously been dynamically allocated using other
      functions from this module. It does this by checking for the
      presence of a \texttt{"} magic\texttt{"}  number in the header which precedes the
      allocated memory. If the magic number is not present (or the
      pointer is invalid for any other reason), zero is returned.
      Otherwise 1 is returned.
   }
   \sstsynopsis{
      int astIsDynamic\_( const void $*$ptr )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to test.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astIsDynamic()
      }{
         Non-zero if the memory was allocated dynamically. Zero is returned
         if the supplied pointer is NULL.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero is returned if this function is invoked with
         the global error status set, or if it fails for any reason.
      }
   }
}
\sstroutine{
   astMalloc
}{
   Allocate memory
}{
   \sstdescription{
      This function allocates memory in a similar manner to the
      standard C \texttt{"} malloc\texttt{"}  function, but with improved security
      (against memory leaks, etc.) and with error reporting. It also
      allows zero-sized memory allocation (without error), resulting
      in a NULL returned pointer value.
   }
   \sstsynopsis{
      void $*$astMalloc( size\_t size )
   }
   \sstparameters{
      \sstsubsection{
         size
      }{
         The size of the memory region required (may be zero).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMalloc()
      }{
         If successful, the function returns a pointer to the start of
         the allocated memory region. If the size allocated is zero, this
         will be a NULL pointer.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      }
   }
}
\sstroutine{
   astMemCaching
}{
   Controls whether allocated but unused memory is cached in this module
}{
   \sstdescription{
      This function sets a flag indicating if allocated but unused memory
      should be cached or not. It also returns the original value of the
      flag.

      If caching is switched on or off as a result of this call, then the
      current contents of the cache are discarded.

      Note, each thread has a separate cache. Calling this function
      affects only the currently executing thread.
   }
   \sstsynopsis{
      int astMemCaching( int newval )
   }
   \sstparameters{
      \sstsubsection{
         newval
      }{
         The new value for the MemoryCaching tuning parameter (see
         \htmlref{astTune}{astTune} in objectc.c). If AST\_\_TUNULL is supplied, the current
         value is left unchanged.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astMemCaching()
      }{
         The original value of the MemoryCaching tuning parameter.
      }
   }
}
\sstroutine{
   astRealloc
}{
   Change the size of a dynamically allocated region of memory
}{
   \sstdescription{
      This function changes the size of a dynamically allocated region
      of memory, preserving its contents up to the minimum of the old
      and new sizes. This may involve copying the contents to a new
      location, so a new pointer is returned (and the old memory freed
      if necessary).

      This function is similar to the standard C \texttt{"} realloc\texttt{"}  function
      except that it provides better security against programming
      errors and also supports the allocation of zero-size memory
      regions (indicated by a NULL pointer).
   }
   \sstsynopsis{
      void $*$astRealloc( void $*$ptr, size\_t size )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to previously allocated memory (or NULL if the
         previous size of the allocated memory was zero).
      }
      \sstsubsection{
         size
      }{
         New size required for the memory region. This may be zero, in
         which case a NULL pointer is returned (no error results). It
         should not be negative.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astRealloc()
      }{
         If the memory was reallocated successfully, a pointer to the
         start of the new memory region is returned (this may be the same
         as the original pointer). If size was given as zero, a NULL
         pointer is returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         If this function is invoked with the error status set, or if
         it fails for any reason, the original pointer value is returned
         and the memory contents are unchanged. Note that this behaviour
         differs from that of the standard C \texttt{"} realloc\texttt{"}  function which
         returns NULL if it fails.
      }
   }
}
\sstroutine{
   astRemoveLeadingBlanks
}{
   Remove any leading white space from a string
}{
   \sstdescription{
      This function moves characters in the supplied string to the left
      in order to remove any leading white space.
   }
   \sstsynopsis{
      void astRemoveLeadingBlanks( char $*$string )
   }
   \sstparameters{
      \sstsubsection{
         string
      }{
         Pointer to the string.
      }
   }
}
\sstroutine{
   astSizeOf
}{
   Determine the size of a dynamically allocated region of memory
}{
   \sstdescription{
      This function returns the size of a region of dynamically
      allocated memory.
   }
   \sstsynopsis{
      size\_t astSizeOf( const void $*$ptr )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to dynamically allocated memory (or NULL if the size
         of the allocated memory was zero).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astSizeOf()
      }{
         The allocated size. This will be zero if a NULL pointer was
         supplied (no error will result).
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A value of zero is returned if this function is invoked with
         the global error status set, or if it fails for any reason.
      }
   }
}
\sstroutine{
   astStore
}{
   Store data in dynamically allocated memory
}{
   \sstdescription{
      This function stores data in dynamically allocated memory,
      allocating the memory (or adjusting the size of previously
      allocated memory) to match the amount of data to be stored.
   }
   \sstsynopsis{
      void $*$astStore( void $*$ptr, const void $*$data, size\_t size )
   }
   \sstparameters{
      \sstsubsection{
         ptr
      }{
         Pointer to previously allocated memory (or NULL if none has
         yet been allocated).
      }
      \sstsubsection{
         data
      }{
         Pointer to the start of the data to be stored. This may be
         given as NULL if there are no data, in which case it will be
         ignored and this function behaves like \htmlref{astRealloc}{astRealloc}, preserving
         the existing memory contents.
      }
      \sstsubsection{
         size
      }{
         The total size of the data to be stored and/or the size of
         memory to be allocated. This may be zero, in which case the
         data parameter is ignored, any previously-allocated memory is
         freed and a NULL pointer is returned.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStore()
      }{
         If the data were stored successfully, a pointer to the start of
         the possibly new memory region is returned (this may be the same
         as the original pointer). If size was given as zero, a NULL
         pointer is returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         This is a convenience function for use when storing data of
         arbitrary size in memory which is to be allocated
         dynamically. It is appropriate when the size of the data will
         not change frequently because the size of the memory region will
         be adjusted to fit the data on every invocation.

         \sstitem
         If this function is invoked with the error status set, or if
         it fails for any reason, the original pointer value is returned
         and the memory contents are unchanged.
      }
   }
}
\sstroutine{
   astString
}{
   Create a C string from an array of characters
}{
   \sstdescription{
      This function allocates memory to hold a C string and fills the
      string with the sequence of characters supplied. It then
      terminates the string with a null character and returns a
      pointer to its start. The memory used for the string may later
      be de-allocated using \htmlref{astFree}{astFree}.

      This function is intended for constructing null terminated C
      strings from arrays of characters which are not null terminated,
      such as when importing a character argument from a Fortran 77
      program.
   }
   \sstsynopsis{
      char $*$astString( const char $*$chars, int nchars )
   }
   \sstparameters{
      \sstsubsection{
         chars
      }{
         Pointer to the array of characters to be used to fill the string.
      }
      \sstsubsection{
         nchars
      }{
         The number of characters in the array (zero or more).
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astString()
      }{
         If successful, the function returns a pointer to the start of
         the allocated string. If the number of characters is zero, a
         zero-length string is still allocated and a pointer to it is
         returned.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      }
   }
}
\sstroutine{
   astStringArray
}{
   Create an array of C strings from an array of characters
}{
   \sstdescription{
      This function turns an array of fixed-length character data into
      a dynamicllay allocated array of null-terminated C strings with
      an index array that may be used to access them.

      The array of character data supplied is assumed to hold \texttt{"} nel\texttt{"}
      adjacent fixed-length strings (without terminating nulls), each
      of length \texttt{"} len\texttt{"}  characters. This function allocates memory and
      creates a null-terminated copy of each of these strings. It also
      creates an array of \texttt{"} nel\texttt{"}  pointers which point at the start of
      each of these new strings. A pointer to this index array is
      returned.

      The memory used is allocated in a single block and should later
      be de-allocated using \htmlref{astFree}{astFree}.
   }
   \sstsynopsis{
      char $*$$*$astStringArray( const char $*$chars, int nel, int len )
   }
   \sstparameters{
      \sstsubsection{
         chars
      }{
         Pointer to the array of input characters. The number of characters
         in this array should be at least equal to (nel $*$ len).
      }
      \sstsubsection{
         nel
      }{
         The number of fixed-length strings in the input character
         array. This may be zero but should not be negative.
      }
      \sstsubsection{
         len
      }{
         The number of characters in each fixed-length input
         string. This may be zero but should not be negative.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStringArray()
      }{
         A pointer to the start of the index array, which contains \texttt{"} nel\texttt{"}
         pointers pointing at the start of each null-terminated output
         string.

         The returned pointer should be passed to astFree to de-allocate
         the memory used when it is no longer required. This will free
         both the index array and the memory used by the strings it
         points at.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A NULL pointer will also be returned if the value of \texttt{"} nel\texttt{"}  is
         zero, in which case no memory is allocated.

         \sstitem
         A pointer value of NULL will also be returned if this function
         is invoked with the global error status set or if it fails for
         any reason.
      }
   }
}
\sstroutine{
   astStringCase
}{
   Convert a string to upper or lower case
}{
   \sstdescription{
      This function converts a supplied string to upper or lower case,
      storing the result in dynamically allocated memory. The \htmlref{astChrCase}{astChrCase}
      function is similar, but stores the result in a supplied buffer.
   }
   \sstsynopsis{
      char $*$astStringCase( const char string, int upper )
   }
   \sstparameters{
      \sstsubsection{
         string
      }{
         Pointer to the null terminated string to be converted.
      }
      \sstsubsection{
         upper
      }{
         If non-zero, the string is converted to upper case. Otherwise it
         is converted to lower case.
      }
   }
   \sstreturnedvalue{
      \sstsubsection{
         astStringCase()
      }{
         If successful, the function returns a pointer to the start of
         the allocated string. The returned memory should be freed using
         \htmlref{astFree}{astFree} when no longer needed.
      }
   }
   \sstnotes{
      \sstitemlist{

         \sstitem
         A pointer value of NULL is returned if this function is
         invoked with the global error status set or if it fails for any
         reason.
      }
   }
}
\normalsize

\newpage
\section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage}

This appendix gives details of the \htmlref{FitsChan}{FitsChan} class
implementation of the conventions described in the FITS-WCS papers
available at
\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are
used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan
has the value ``FITS-WCS'' (whether set explicitly or defaulted). It
should always be possible for a \htmlref{FrameSet}{FrameSet} to be read
(using the
\htmlref{astRead}{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 \emph{written} to a FitsChan using the
\htmlref{astWrite}{astWrite}
function. For instance, if the current \htmlref{Frame}{Frame} of a
FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{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 CTYPE\emph{i} keywords.

\subsection{Paper I - General Linear Coordinates}
When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} 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 \htmlref{Frame}{Frame} (\emph{i.e.} not a
\htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}).

\htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword
defined by FITS-WCS paper I.

\begin{table}[htbp]
\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
\hline
\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline

\fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS
Frame - only written if different to NAXIS.}

\fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS
\htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference
Point'' below).}

\fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always
written (see ``Choice of Reference Point'' below).}

\fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only
written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is
set to zero.}

\fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only
written in FITS-AIPS and FITS-AIPS++ encodings.}

\fitskey{CTYPE\emph{ia}}{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).}

\fitskey{CUNIT\emph{ia}}{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.}

\fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS
Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to
zero.}

\fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS
Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to
a non-zero value.}

\fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes
are linear.}

\fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.}

\fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{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.}

\fitskey{CRDER\emph{ia}}{Ignored.}{Not used.}

\fitskey{CSYER\emph{ia}}{Ignored.}{Not used.}

\hline
\end{tabular}
\vspace{3.mm}
\caption{Use of FITS-WCS Paper I keywords}
\label{tab:fitspaper1}
\end{table}

\subsubsection{Requirements for a Successful Write Operation}
When writing a \htmlref{FrameSet}{FrameSet} in which the WCS
\htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan},
success depends on the \htmlref{Mapping}{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.

\subsubsection{Use and Choice of CTYPE\emph{i} keywords}
When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the
Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from
the CNAME\emph{i} keywords, if present in the header. Otherwise they are set
from the CTYPE\emph{i} comments strings in the header, so long as each
axis has a unique non-blank comment. Otherwise, the Label attributes are
set to the CTYPE\emph{i} 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 CTYPE\emph{i} 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
\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which
case the CTYPE\emph{i} value is derived from the \htmlref{System}{System}
attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping}
according to the conventions of papers II and III, as described below.

\subsubsection{Choice of Reference Point}
When writing a \htmlref{FrameSet}{FrameSet} to a
\htmlref{FitsChan}{FitsChan}, the pixel coordinates of the
reference point for linear axes (i.e. the CRPIX\emph{j} values) are
chosen as follows:

\begin{itemize}
\item If the FrameSet is being written to a FitsChan which previously
contained a set of axis descriptions with the same identifying letter,
then the previous CRVAL\emph{j}values are converted into the coordinate system
of the \htmlref{Frame}{Frame} being written (if possible). These values are then
transformed into the pixel Frame, and the closest integer pixel values
are used as the CRPIX keywords.
\item If the above step could not be performed for any reason, the
central pixel is used as the reference point. This requires the image
dimensions to be present in the FitsChan in the form of a set of
NAXIS\emph{j} keyword values.
\item If both the above two steps failed for any axis, then the pixel
reference position is set to a value of 1.0 on the pixel axis.
\end{itemize}

The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding
CRVAL\emph{j}values.

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


\subsubsection{Choice of Axis Ordering}
When reading a \htmlref{FrameSet}{FrameSet} from a
\htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current
\htmlref{Frame}{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 CD\emph{i\_j} or PC\emph{i\_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.

\subsubsection{Alternate Axis Descriptions}
When reading a \htmlref{FrameSet}{FrameSet} from a
\htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions,
each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added
to the final FrameSet, connected via an appropriate
\htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{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.

\subsection{Paper II - Celestial Coordinates}
These conventions are used when reading a \htmlref{FrameSet}{FrameSet}
from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i}
values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame}
is a \htmlref{SkyFrame}{SkyFrame}.

\htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword
whose meaning is defined or extended by FITS-WCS paper II.

\begin{table}[htbp]
\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
\hline
\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline

\fitskey{CTYPE\emph{ia}}{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 \htmlref{System}{System} attribute
of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the
\htmlref{WcsMap}{WcsMap} within the FrameSet.}

\fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.}

\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values
are stored as attributes of a WcsMap within this Mapping).}{Values are
obtained from the WcsMap in the pixel to WCS Mapping.}

\fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also
stored as a \htmlref{PVi\_m}{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).}

\fitskey{LATPOLE\emph{a}}{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).}

\fitskey{RADESYS\emph{a}}{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.}

\fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute
of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of
the SkyFrame.}

\fitskey{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.}

\fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{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).}

\hline
\end{tabular}
\vspace{3.mm}
\caption{Use of FITS-WCS Paper II keywords}
\label{tab:fitspaper2}
\end{table}

\subsubsection{Requirements for a Successful Write Operation}
When writing a \htmlref{FrameSet}{FrameSet} in which the WCS
\htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a
\htmlref{FitsChan}{FitsChan}, success depends on the following conditions
being met:

\begin{enumerate}
\item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame
in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}.
\item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear.
\item The Mapping after the WcsMap (\emph{i.e.} from native spherical to
celestial coordinates) is a spherical rotation for the
celestial axes, and linear for any other axes.
\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan,
and the longitude and latitude axes are separable. In this case the Mapping will
be described by a pair of 1-dimensional look-up tables, using the ``-TAB''
algorithm described in FITS-WCS paper III.
\end{enumerate}

If none of the above conditions hold, the write operation will be
unsuccessful.

\subsubsection{Choice of LONPOLE/LATPOLE}
When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan},
the choice of LONPOLE and LATPOLE values is determined as follows:

\begin{enumerate}

\item If the projection represented by the \htmlref{WcsMap}{WcsMap} is
azimuthal, then any values set for attributes ``PV\emph{i}\_3''
and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis)
within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a
FrameSet from a FITS-WCS header
results in the original LONPOLE and LATPOLE values being stored within a
WcsMap within the FrameSet. Consequently, if a FrameSet is read from a
FITS-WCS header and it is subsequently written out to a new FITS-WCS
header, the original LONPOLE and LATPOLE values will usually be used in
the new header (the exception being if the WcsMap has been explicitly
modified before being written out again). Any extra rotation of the sky
is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is
possible only if the projection is azimuthal).

\item If the projection represented by the WcsMap is azimuthal but no
values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4''
attributes within the WcsMap, then the default LONPOLE and LATPOLE values
are used. This results in no LONPOLE or LATPOLE keywords being stored in
the header since default values are never stored. Any extra rotation of
the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this
is possible only if the projection is azimuthal).

\item If the projection represented by the WcsMap is not azimuthal,
then the values of LONPOLE and LATPOLE are found by transforming the
coordinates of the celestial north pole (\emph{i.e} longitude zero,
latitude $+\pi/2$) into native spherical coordinates using the inverse of
the \htmlref{Mapping}{Mapping} which follows the WcsMap.

\end{enumerate}

\subsubsection{User Defined Fiducial Points}
When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters
PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis
``\emph{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 \emph{before} the \htmlref{WcsMap}{WcsMap} which converts
IWC into
native spherical coordinates. The values of these projection parameters,
if supplied, are stored as the corresponding \htmlref{PVi\_m}{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 CRVAL\emph{i}
keywords and the corresponding pixel coordinates as the CRPIX\emph{j}
keywords.

\subsubsection{Common Non-Standard Features}
A collection of common non-standard features are supported when reading a
\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{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:

\begin{itemize}
\item EQUINOX keywords with string values equal to a date preceded
by the letter B or J (\emph{e.g.} ``B1995.0'').

\item EQUINOX or EPOCH keywords with value zero  (these are converted to
B1950).

\item The IRAF ``ZPX'' projection is represented by a
\htmlref{WcsMap}{WcsMap} with type of
AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn}
keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the
WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic
ZPN projection by including ``lngcor'' or ``latcor'' terms. These are
supported if they use half cross-terms, in either simple or Chebyshev
representation.

\item The IRAF ``TNX'' projection is represented by a WcsMap with type of
AST\_\_TPN (a distorted TAN projection retained within the WcsMap class
from an early draft of the FITS-WCS paper II). Projection parameter values
are read from any WAT\emph{i\_nnn} keywords, and corresponding PV
attributes are set in the WcsMap. If the TNX projection cannot be
converted exactly into an AST\_\_TPN projection, ASTWARN keywords are
added to the FitsChan containing a warning message (but only if the
\htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently,
TNX projections that use half cross-terms, in either simple or Chebyshev
representation, are supported.

\item ``QV'' parameters for TAN projections (as produced by
\xref{AUTOASTROM}{sun242}{}
\footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}}
are renamed to the equivalent ``PV'' parameters.

\item TAN projections that have associated ``PV'' parameters on the
latitude axis are converted to the corresponding TPN (distorted TAN)
projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute
of the FitsChan class.

\end{itemize}

\subsection{Paper III - Spectral Coordinates}
These conventions are used when reading a \htmlref{FrameSet}{FrameSet}
from a \htmlref{FitsChan}{FitsChan} which includes appropriate
CTYPE\emph{i} values, and when writing a FrameSet in which
the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}.

\htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword
whose meaning is defined or extended by FITS-WCS paper III.

\begin{table}[htbp]
\begin{footnotesize}
\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
\hline
\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline

\fitskey{CTYPE\emph{ia}}{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 \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the
SpecFrame and the nature of the pixel to SpecFrame
\htmlref{Mapping}{Mapping}.}

\fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of
the SpecFrame (note, SpecFrames always have an ``active'' Units attribute
(see \htmlref{astSetActiveUnit}{astSetActiveUnit}).}{Always written.}

\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values
are stored as attributes of a \htmlref{GrismMap}{GrismMap}).}
{Set from the attributes of the GrismMap, if present, and if set explicitly.}

\fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{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.}

\fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.}

\fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and
\htmlref{ObsLat}{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).}

\fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of
the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has
been set explicitly.}

\fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the
SpecFrame
(all systems are supported except CMBDIPOL).} {Set from the SourceVRF
attribute of the SpecFrame.}

\fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{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).}

\fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the
SpecFrame that define the standard of rest and the observers position.}

\fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{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.}

\fitskey{RESTWAV\emph{a}}{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.}

\fitskey{CNAME\emph{ia}}{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.}
\hline
\end{tabular}
\end{footnotesize}
\vspace{3.mm}
\caption{Use of FITS-WCS Paper III keywords}
\label{tab:fitspaper3}
\end{table}

\subsubsection{Requirements for a Successful Write Operation}
When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a
\htmlref{FitsChan}{FitsChan}, the write operation is successful only if
the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame
in the FrameSet) to the SpecFrame satisfies one of the following conditions:

\begin{enumerate}
\item It is linear.
\item It is logarithmic.
\item It is linear if the SpecFrame were to be re-mapped into one of the
other spectral systems supported by FITS-WCS paper III.
\item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from
pixel coordinates to grism parameter) is linear, and the Mapping after the
GrismMap is either null or represents a change of spectral system from wavelength (air or
vacuum) to one of the supported spectral systems.
\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan.
\end{enumerate}

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.\footnote{If 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.}

\subsubsection{Common Non-Standard Features}
The following non-standard features are supported when reading spectral
axes from a \htmlref{FitsChan}{FitsChan}:

\begin{itemize}
\item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes
(specified in early drafts of paper III) to the corresponding
``-X2P'' form.
\item Conversion of ``RESTFREQ'' to ``RESTFRQ''
\end{itemize}

\subsection{Paper IV - Coordinate Distortions}

This paper proposes that an additional 4 character code be appended to
the end of the CTYPE\emph{i} keyword to specify the nature of any
distortion away from the basic algorithm described by the first 8
characters of the CTYPE\emph{i} value. Currently AST ignores all such
codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{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 \htmlref{Mapping}{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
CTYPE\emph{i} keywords will include no distortion code.

\subsubsection{The ``-SIP'' distortion code}

The Spitzer Space Telescope project
(\url{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
\url{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 CTYPE\emph{i} 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
CRPIX\emph{j} values.

This system is a strictly 2 dimensional system. When reading a
\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{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
\htmlref{PolyMap}{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 (\emph{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 CTYPE\emph{i} keyword values.

\newpage
\section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes}

\subsection{Changes Introduced in V1.1}

The following describes the most significant changes which occurred in
the AST library between versions V1.0 and V1.1 (not the most recent
version):

\begin{enumerate}

\item A new ``How To\ldots'' section (\secref{ss:howto}) has been
added to this document. It contains simple recipies for performing
commonly-required operations using AST.

\item A new \htmlref{astUnformat}{astUnformat} function has been provided to read formatted
coordinate values for the axes of a \htmlref{Frame}{Frame}
(\secref{ss:unformattingaxisvalues}). In essence, this function is the
inverse of \htmlref{astFormat}{astFormat}. It may be used to decode user-supplied formatted
values representing coordinates, turning them into numerical values
for processing. Celestial coordinates may also be read using this
function (\secref{ss:unformattingskyaxisvalues}) and free-format input
is supported.

\item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting
celestial coordinate values now allows the degrees/hours field to be
omitted, so that celestial coordinates may be given in (\emph{e.g.})
arc-minutes and/or arc-seconds
(\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours
field is no longer included by default.  A new ``t'' format specifier
has been introduced (see the Format attribute) to allow minutes and/or
seconds of time to be specified if required.

\item A new function \htmlref{astMapBox}{astMapBox} has been introduced. This allows you to
find the extent of a ``bounding box'' which just encloses another box
after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to
calculate the size which an image would have if it were transformed by
the Mapping.

\item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced
(\secref{ss:intramaps}). This is a specialised form of Mapping which
encapsulates a privately-defined coordinate transformation function
(\emph{e.g.}\ written in C) so that it may be used like any other AST
Mapping. This allows you to create Mappings that perform any
conceivable coordinate transformation.

\item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically
preserved whenever changes are made to any attributes which affect the
current Frame (either by setting or clearing their values). This is
accomplished by appropriately re-mapping the current Frame to account
for any change to the coordinate system which it represents
(\secref{ss:framesetintegrity}).

\item The internal structure of a FrameSet is now automatically tidied
to eliminate redundant nodes whenever any of its Frames is removed or
re-mapped. Automatic simplification of any compound Mappings which
result may also occur. The effect of this change is to prevent the
accumulation of unnecessary structure in FrameSets which are
repeatedly modified.

\item Some improvements have been made to the algorithms for
simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}.

\item The textual representation used for some Objects
(\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed
slightly, but remains compatible with earlier versions of AST.

\item Interfaces to the internal functions and macros used by AST for
handling memory and error conditions are now provided \emph{via} the
``ast.h'' header file. This is for the benefit of those writing
(\emph{e.g.}) new graphics interfaces for AST.

\item A problem has been fixed which could result when using \htmlref{astRead}{astRead}
to read FITS headers in which the CDELT value is zero. Previously,
this could produce a Mapping whose inverse transformation was not
defined and this could unnecessarily restrict the use to which it
could be put. The problem has been overcome by supplying a suitable
small CDELT value for FITS axes which have only a single pixel.

\item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap}
to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of
a compound Mapping which is being simplified using astSimplify.


\item A problem has been fixed which could prevent tick marks being
drawn on a coordinate axis close to a singularity in the coordinate
system.
\end{enumerate}

\subsection{Changes Introduced in V1.2}

The following describes the most significant changes which occurred in
the AST library between versions V1.1 and V1.2 (not the most recent
version):

\begin{enumerate}
\item A new function, \htmlref{astPolyCurve}{astPolyCurve}, has been introduced to allow more
efficient plotting of multiple geodesic curves
(\secref{ss:plottinggeodesics}).

\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced
to perform resampling of gridded data such as images
(\emph{i.e.}\ re-gridding) under the control of a geometrical
transformation specified by a \htmlref{Mapping}{Mapping}.

\item The command-line options ``$-$pgp'' and ``$-$pgplot'', which
were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and
``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option
``$-$pgp'' now causes linking with the Starlink version of PGPLOT
(which uses GKS to generate its output), while ``$-$pgplot'' links
with the standard (or ``native'') version of PGPLOT.

\item The function \htmlref{astMapBox}{astMapBox} has been changed to execute more quickly,
although this has been achieved at the cost of some loss of robustness
when used with difficult Mappings.

\item A new value of ``FITS-IRAF'' has been introduced for the
\htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an
interim solution to the problem of storing coordinate system
information in FITS headers, until the proposed new FITS-WCS standard
becomes stable.

\item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by
reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame}
of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to
``GRID''. This reflects the fact that this Frame represents FITS data
grid coordinates (equivalent to FITS pixel coordinates---see
\secref{ss:domainconventions}). Previously, this Domain value was not
set.

\item \htmlref{astFindFits}{astFindFits} now ignores trailing spaces in its keyword template.

\item \htmlref{astPutFits}{astPutFits} now recognises ``D'' and ``d'' as valid exponent
characters in floating point numbers.

\item The FitsChan class is now more tolerant of common minor
violations of the FITS standard.

\item The FitsChan class now incorporates an improved test for the
linearity of Mappings, allowing more reliable conversion of AST data
into FITS (using ``foreign'' FITS encodings).

\item Some further improvements have been made to the algorithms for
simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}.

\item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap}
class. This allows improved simplification of compound Mappings
(CmpMaps) involving SphMaps and typically improves performance when
handling FITS world coordinate information.

\item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of
AST\_\_BAD automatically to all output coordinates. If certain output
coordinates do not depend on the affected input coordinate(s) because
the relevant matrix elements are zero, then they may now remain valid.

\item A minor bug has been corrected which could cause certain
projections which involve half the celestial sphere to produce valid
coordinates for the other (unprojected) half of the sphere as well.

\item A bug has been fixed which could occasionally cause \htmlref{astConvert}{astConvert}
to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was
possible when, in fact, it wasn't.
\end{enumerate}

\subsection{Changes Introduced in V1.3}

The following describes the most significant changes which occurred in
the AST library between versions V1.2 and V1.3 (not the most recent
version):

\begin{enumerate}
\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to
provide	efficient resampling of gridded data, such as spectra and
images, under the control of a geometrical transformation specified by
a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported.

\item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised
form of Mapping which implements 2-dimensional pincushion or barrel
distortion.

\item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too
many digits when formatting floating point values for inclusion in a
FITS header if the numerical value was in the range -0.00099999\ldots
to -0.0001.

\item A bug has been fixed which could cause a FitsChan to lose the
comment associated with a string value in a FITS header.

\item A FitsChan now reports an error if it reads a FITS header which
identifies a non-standard sky projection (previously, this was
accepted without error and a Cartesian projection used instead).

\item A bug has been fixed which could prevent conversion between the
coordinate systems represented by two CmpFrames. This could only occur
if the CmpFrames contained a relatively large number of nested Frames.

%\item A bug has been fixed which could cause a program to crash if
%FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet}
%had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The
%problem could only occur if the nested structure was loaded from a data
%c+
%file (using \htmlref{astRead}{astRead}).
%c-
%f+
%file (using AST\_READ).
%f-
%
\item Further improvements have been made to the simplification of
compound Mappings, including fixes for several bugs which could cause
indefinite looping or unwanted error messages.

\item Some memory leaks have been fixed.

\item A small number of documentation errors have been corrected.
\end{enumerate}

\subsection{Changes Introduced in V1.4}

The following describes the most significant changes which have occurred
in the AST library between versions V1.3 and V1.4 (not the most recent
version):

\begin{enumerate}
\item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of
\htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a
flexible and transportable way using arithmetic operations and
mathematical functions similar to those available in C.

\item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation functions
used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{astIntraReg}{astIntraReg}) now
require a ``this'' pointer as their first parameter. \textbf{Existing
implementations will not continue to work correctly with this version
of AST unless this parameter is added.} There is no need for existing
software to make use of this pointer, but it must be present.

This change has been introduced so that transformation functions can gain
access to IntraMap attributes.

\item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap
class. This allows the transformation functions used by IntraMaps to
adapt to produce the required transformation on a per-IntraMap basis
(\secref{ss:intraflag}).

\item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the
length of major and minor tick marks on coordinate axes, may now be
subscripted using an axis number. This allows tick marks of different
lengths to be used on each axis. It also allows tick marks to be
suppressed on one axis only by setting the length to zero.

\item The value of the Plot attribute NumLab, which controls the
plotting of numerical labels on coordinate axes, no longer has any
effect on whether labelling of a coordinate grid is interior or
exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute).

\item The \htmlref{FitsChan}{FitsChan} class now provides some support for the
IRAF-specific ``ZPX'' sky projection, which is converted transparently
into the equivalent FITS ``ZPN'' projection (see the description of the
\htmlref{Encoding}{Encoding} attribute for details).

\item The FitsChan class now recognises the coordinate system ``ICRS''
(International Celestial Reference \htmlref{System}{System}) as equivalent to
``FK5''. This is an interim measure and full support for the
(exceedingly small) difference between ICRS and FK5 will be added at a
future release.

Note that ``ICRS'' is not yet recognised as a coordinate system by other
classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the
importation of foreign data.

\item A bug in the FitsChan class has been fixed which could result in
longitude values being incorrect by 180 degrees when using cylindrical
sky projections, such as the FITS ``CAR'' projection.

\item A bug in the FitsChan class has been fixed which could result in
the FITS sky projection parameters ProjP(0) to ProjP(9) being
incorrectly named PROJP1 to PROJP10 when written out as FITS cards.

\item A bug in the FitsChan class has been fixed which could cause
confusion between the FITS-IRAF and FITS-WCS encoding schemes if both
a CD matrix and a PC matrix are erroneously present in a FITS header.

\item Some minor memory leaks have been fixed.

\item A small number of documentation errors have been corrected.
\end{enumerate}

\subsection{Changes Introduced in V1.5}

The following describes the most significant changes which have
occurred in the AST library between versions V1.4 and V1.5 (not the most
recent version):

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft
FITS WCS standard, described in the two papers ``Representation of world
coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th
November, 1999), and ``Representation of celestial coordinates in FITS''
(M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are
available at
\url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}.

The FITS-WCS encoding now uses these updated conventions. The main
changes are:

\begin{itemize}
\item Rotation and scaling of pixel axes is now represented by a matrix
of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and
\texttt{CDELTj} keywords.
\item \htmlref{Projection}{Projection} parameters are now associated with particular axes and
are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm}
keywords.
\item The tangent plane projection (``TAN'') can now include optional
polynomial correction terms.
\item An entire set of keywords must be supplied for each set of secondary
axis descriptions, and each such keyword must finish with a single
character indicating which set it belongs to. This means that keywords
which previously occupied eight characters have been shorten to seven to
leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}.
\end{itemize}

\item Two new encodings have been added to the FitsChan class:
\begin{description}

\item [FITS-PC] This encoding uses the conventions of the now superseded
FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords
\texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation.
These are the conventions which were used by the FITS-WCS encoding prior
to version 1.5 of AST. This encoding is provided to allow existing data
which use these conventions to be read. It should not in general be used
to create new data.

\item [FITS-AIPS] This encoding is based on the conventions described in the
document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen
(revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu
/fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and
\texttt{CDELTi} keywords to describe axis rotation and scaling.

\end{description}

\item The FitsChan class now provides some support for the IRAF-specific
``TNX'' sky projection, which is converted transparently into the
equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding}
attribute for details).

\item FrameSets originally read from a DSS encoded FITS header can now be
written out using the FITS-WCS encoding (a TAN projection with correction
terms will be used) in addition to the DSS encoding. The reverse is also
possible: FrameSets originally read from a FITS-WCS encoded FITS header
and which use a TAN projection can now be written out using the DSS
encoding.

\item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet}
conforms to the FITS-WCS model has been improved so that FrameSets
including more complex mixtures of parallel and serial Mappings
can be written out using the FITS-WCS encoding.

\item The FitsChan class has been changed so that long strings included in
the description of an \htmlref{Object}{Object} can be saved and restored without truncation
when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles,
mathematical expressions, \emph{etc.} were truncated if they exceeded the
capacity of a single FITS header card. They are now split over several
header cards so that they can be restored without truncation. Note, this
facility is only available when using NATIVE encoding.

\item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which
can be used to select potentially dangerous conditions under which
warnings should be issued. These conditions include (for instance)
unsupported features within non-standard projections, missing keywords
for which default values will be used, \emph{etc}.

\item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the
FITS-WCS encoding in the FitsChan class:
\begin{itemize}
\item Projection parameters are now associated with a particular axis and
are specified using a new set of attributes called PVj\_m. Here, ``j'' is
the index of an axis of WcsMap, and ``m'' is the index of the projection
parameter.
\item The old attributes ProjP(0) to ProjP(9) are still available but are
now deprecated in favour of the new PVj\_m attributes. They are interpreted
as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of
the latitude axis.
\item The GLS projection projection has been renamed as SFL, but the
AST\_\_GLS type has been retained as an alias for AST\_\_SFL.
\end{itemize}

\end{enumerate}

\subsection{Changes Introduced in V1.6}

The following describes the most significant changes which have
occurred in the AST library between versions V1.5 and V1.6:

\begin{enumerate}

\item The C interface to several methods (\htmlref{astTranN}{astTranN}, \htmlref{astMark}{astMark} and
\htmlref{astPolyCurve}{astPolyCurve}) have been changed to make them easier to call from C++.
Parameters which previously had type ``double (*)[]'' have been changed
to the simpler ``double *''. Using the old types may result in non-fatal
compiler warnings, but should not change the behaviour of the methods.

\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups
of tick marks to be skipped when using very small gaps.

\item A bug has been fixed in the Plot class which could cause axes to be
labeled outside the visible window, resulting in no axes being visible.

\item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the
WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of
the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding
Frames in the returned FrameSet. When writing a FrameSet to a FITS header
the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the
header.

\item The FITS-WCS encoding used by the FitsChan class now attempts to
retain the identification letter associated with multiple axis
descriptions. When reading a FrameSet from a FITS header, the identification
letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a
FrameSet to a FITS header, the identification letter is read from the
Ident attribute of each Frame. The letter to associate with each Frame
can be changed by assigning a new value to the Frame's Ident attribute.

\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the
FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to
``Unknown'' if the CTYPE keywords in the supplied header refers to an
unknown celestial coordinate system. Previously, a Frame was used instead
of a SkyFrame.

\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the
FitsChan class no longer report an error if the FITS header contains no
CTYPE keywords. It is assumed that a missing CTYPE keyword implies that
the world coordinate system is linear and identically equal to
``intermediate world coordinates''.

\item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute
of the FitsChan class. This value causes warnings to be issued if CTYPE
keywords are missing from foreign encodings.

\item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan
class. This is a read-only, space separated list of all the known condition
names which can be specified in the Warnings attribute.

\item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in
a FrameSet read using a foreign encoding. The Title is based on the Domain
name of the Frame. If the Frame has no Domain name, the default Title
supplied by the Frame class is retained.

\item The FitsChan class uses the comments associated with CTYPE
keywords as axis labels when reading a foreign encoding. This behaviour
has been modified so that the default labels provided by the Frame class
are retained (instead of using the CTYPE comments) if any of the CTYPE
comments are identical.

\item A new ``interpolation'' scheme identified by the symbolic constant
AST\_\_BLOCKAVE has been added to the AST\_RESAMPLE$<$X$>$ set of
functions. The new scheme calculates each output pixel value by finding
the mean of the input pixels in a box centred on the output pixel.

\item The SkyFrame class can now be used to represent an arbitrary spherical
coordinate system by setting its System attribute to ``Unknown''.

\item The indices of the latitude and longitude axes of a SkyFrame can
now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The
effects of any axis permutation is taken into account.

\item A new attribute called Ident has been added to the \htmlref{Object}{Object} class.
This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID)
its value is transferred to the new Object when a copy is made.

\item A bug has been fixed which could prevent complex CmpFrames
behaving correctly (for instance, resulting in the failure of attempts
to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself).

\end{enumerate}

\subsection{Changes Introduced in V1.7}

The following describes the most significant changes which have
occurred in the AST library between versions V1.6 and V1.7:

\begin{enumerate}

\item The \htmlref{Frame}{Frame} class has a new method called
\htmlref{astAngle}{astAngle}
which returns the angle subtended by two points at a third point within a
2 or 3 dimensional Frame.

\item The Frame class has a new method called
\htmlref{astOffset2}{astOffset2}
which calculates a position which is offset away from a given starting
point by a specified distance along a geodesic curve which passes
through the starting point at a given position angle. It can only be used
with 2-dimensional Frames.

\item The Frame class has a new method called
\htmlref{astAxDistance}{astAxDistance}
which returns the increment between two supplied axis values. For
axes belonging to SkyFrames, the returned value is normalized into
the range $\pm\pi$.

\item The Frame class has a new method called
\htmlref{astAxOffset}{astAxOffset}
which returns an axis value a given increment away from a specified axis
value. For axes belonging to SkyFrames, the returned value is normalized into
the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude
axes).

\item The \htmlref{Plot}{Plot} class has a new method called
\htmlref{astGenCurve}{astGenCurve}
which allows generalised user-defined curves to be drawn. The curve is
defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve
into the corresponding position in the current Frame of the Plot. The new
method then maps these current Frame position into graphics coordinates,
taking care of any non-linearities or discontinuities in the mapping.

\item The Plot class has a new method called
\htmlref{astGrfSet}{astGrfSet}
which allows the underlying primitive graphics functions to be selected
at run-time. Previously, the functions used by the Plot class to produce
graphics could only be selected at link-time, using the options of the
\htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride
the functions established at link-time, by specifying alternative
primitive graphics routines. In addition, the two new Plot methods
\htmlref{astGrfPush}{astGrfPush} and \htmlref{astGrfPop}{astGrfPop}
allow the current graphics routines to be saved and restore on a
first-in-last-out stack, allowing temporary changes to be made to the set
of registered graphics routines.

\item The DrawAxes attribute of the Plot class can now be specified
independantly for each axis, by appending the axis index to the
end of the attribute name.

\item A bug has been fixed in the Plot class which could result in axis
labels being drawn on inappropriate edges of the plotting box when using
``interior'' labelling.

\item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps
to be corrupted after transforming any points.

\item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause
inappropriate ordering of headers within a FitsChan when writing or
reading objects using NATIVE encodings.

\item A bug has been fixed in the FitsChan class which could cause the
celestial longitude of a pixel to be estimated incorrectly by 180 degrees
if the reference point is at either the north or the south pole.

\end{enumerate}


\subsection{Changes Introduced in V1.8-2}

The following describes the most significant changes which have
occurred in the AST library between versions V1.7 and V1.8-2:

\begin{enumerate}

\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows
   longitude values to be displayed in the range $-\pi$ to $+\pi$, instead
   of the usual range zero to $2.\pi$.

\item Some new
functions (\htmlref{astAngle}{astAngle}, \htmlref{astAxAngle}{astAxAngle}, \htmlref{astResolve}{astResolve}, \htmlref{astOffset2}{astOffset2}, \htmlref{astAxOffset}{astAxOffset},
\htmlref{astAxDistance}{astAxDistance})
have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space
to be performed without needing to know the underlying geometry
of the co-ordinate system (for instance, whether it is Cartesian or
spherical).

Note, version 1.8-1 contained many of these facilities, but
some have been changed in version 1.8-2. Particularly, positions angles
are now referred to the second Frame axis for \emph{all} classes of Frames
(including SkyFrames), and the
astBear function has been replaced by astAxAngle.

\end{enumerate}

\subsection{Changes Introduced in V1.8-3}

The following describes the most significant changes which
occurred in the AST library between versions V1.8-2 and V1.8-3:

\begin{enumerate}

\item A new method called \htmlref{astDecompose}{astDecompose} has been added to the \htmlref{Mapping}{Mapping} class
which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and
\htmlref{CmpFrame}{CmpFrame} objects.

\item Functions within proj.c and wcstrig.c have been renamed to avoid name
clashes with functions in more recent versions of Mark Calabretta's wcslib
library.

\end{enumerate}

\subsection{Changes Introduced in V1.8-4}

The following describes the most significant changes which
occurred in the AST library between versions V1.8-3 and V1.8-4:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be
used to select the default reference frame and equinox to be used if
a FitsChan with foreign encoding contains no indication of the
reference frame or equinox.

\item A bug has been fixed in the FitsChan class which could prevent
\htmlref{astWrite}{astWrite} from creating a set of FITS headers from an otherwise valid
\htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding.

\item A bug has been fixed in the FitsChan class which could cause
\htmlref{astRead}{astRead} to mis-interpret the FITS CROTA keyword when using FITS-AIPS
encoding.

\end{enumerate}

\subsection{Changes Introduced in V1.8-5}

The following describes the most significant changes which
occurred in the AST library between versions V1.8-4 and V1.8-5:

\begin{enumerate}

\item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2,
Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2.
These allow graphical attributes (colour, width, etc) to be set for each
axis individually. Previously, graphical attributes could only be set for
both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs,
TextLabs and Ticks.

\end{enumerate}


\subsection{Changes Introduced in V1.8-7}

The following describes the most significant changes which
occurred in the AST library between versions V1.8-5 and V1.8-7:

\begin{enumerate}

\item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class
which controls the way CAR projections are handled when reading a
\htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR
projection to represent a simple linear transformation between pixel
coordinates and celestial sky coordinates. This is not consistent with
the definition of the CAR projection in the draft FITS-WCS standard, which
requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native
spherical coordinates to celestial spherical coordinates, thus making the
Mapping non-linear. Setting CarLin to 1 forces
\htmlref{astRead}{astRead}
to ignore the FITS-WCS standard and treat any CAR projections as simple
linear Mappings from pixel coordinates to celestial coordinates.

\item A bug has been fixed which could result in axis Format attributes
set by the user being ignored under certain circumstances.

\item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class
has been fixed. This bug could result in extra ticks marks being displayed at
inappropriate positions. This bug manifested itself, for instance, if the
Mapping represented by the Plot was a simple Cartesian to Polar Mapping.
In this example, the bug caused tick marks to be drawn at negative radius
values.

\item A bug has been fixed which could prevent attribute settings from
being read correctly by
\htmlref{astSet}{astSet},
etc., on certain platforms (MacOS, for instance).

\end{enumerate}

\subsection{Changes Introduced in V1.8-8}

The following describes the most significant changes which
occurred in the AST library between versions V1.8-7 and V1.8-8:

\begin{enumerate}

\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause
problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS
information stored in the form of Digitised Digitised Sky Survey (DSS)
keywords. These problems only occurred for DSS fields in the southern
hemisphere, and resulted in pixel positions being mapped to sky positions
close to the corresponding \emph{northern} hemispshere field.

\item A new method called
\htmlref{astBoundingBox}{astBoundingBox}
has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of
the previous graphical output produced by a Plot method.

\item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class
which suppresses the graphical output normally produced by Plot methods.
All the calculations needed to produce the normal output are still
performed however, and so the bounding box returned by the new
astBoundingBox
method is still usable.

\item Bugs have been fixed related to the appearance of graphical output
produced by the Plot class. These bugs were to do with the way in which
graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.)
interacted with the corresponding generic element (e.g.
\texttt{Colour(axes)}, etc.).

\end{enumerate}


\subsection{Changes Introduced in V1.8-13}

The following describes the most significant changes which occurred
in the AST library between versions V1.8-8 and V1.8-13:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords
are only produced by \htmlref{astWrite}{astWrite} when necessary. For zenithal projections such as
TAN, the LONPOLE keyword can always take its default value and so is
not included in the FITS header produced by astWrite.
Previously, the unnecessary production of a LONPOLE keyword could prevent
FrameSets being written out using encodings which do not support the
LONPOLE keyword (such as FITS-IRAF).

\item The FitsChan class has been modified to retain leading and trailing
spaces within COMMENT cards.

\item The FitsChan class has been modified to only use CTYPE comments as
axis labels if all non-celestial axes have unique non-blank comments
(otherwise the CTYPE keyword values are used as labels).

\item The FitsChan class has been modified so that it does not append a
trailing ``Z'' character to the end of DATE-OBS keyword values.

\item The FitsChan class has been modified to use latest list of FITS-WCS
projections, as described in the FITS-WCS paper II, ``Representations of
celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23
April 2002). Support has been retained for the polynomial correction
terms which previous drafts have allowed to be associated with TAN
projections.

\item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN
(which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN
projection type now represents a simple TAN projection and has no
associated projection parameters. In addition, the usage of projection
parameters has been brought into line with the the FITS-WCS paper II.

\item The WcsMap class has been modified so that a ``get'' operation on a
projection parameter attribute will return the default value defined in the
FITS-WCS paper II if no value has been set for the attribute. Previously, a
value of AST\_\_BAD was returned in such a situation.

\item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which
allow a ``plottable range'' to be specified for each Frame axis. The grid
produced by the \htmlref{astGrid}{astGrid} method will not extend beyond these limits.

\end{enumerate}

\subsection{Changes Introduced in V2.0}

Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by
applications linked with earlier versions of AST. This applies to Frame
descriptions created using:
\begin{itemize}
\item the \htmlref{Channel}{Channel} class
\item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used
\item the \htmlref{astShow}{astShow} function
\end{itemize}

Applications must be re-linked with AST V2.0 in order to be able to read
Frame descriptions created by AST v2.0.

The following describes the most significant changes which have
occurred in the AST library between versions V1.8-13 and V2.0 (the
current version):

\begin{enumerate}

\item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame}
class has been changed from ``CMP'' to a string formed by concatenating
the Domain attributes of the two component Frames, separated by a minus
sign. If both component Domains are blank, then the old default of
``CMP'' is retained for the CmpFrame Domain.

\item The implementation of the
\htmlref{astWrite}{astWrite} function
within the FitsChan class has been modified. It will now attempt to
produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the
number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the
\htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This
has always been possible with NATIVE encoding, but has not previously
been possible for foreign encodings. The WCSAXES keyword is used to store
the number of WCS axes in the FITS header.

\item Another change to the
astWrite function
within the FitsChan class is that the ordering of ``foreign'' axes
(\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix
as diagonal as possible - any element of axis transposition is removed by
this re-ordering as recommended in FITS-WCS paper I. Previously the
ordering was determined by the order of the axes in the Current Frame of
the supplied FrameSet. This change does not affect NATIVE encoding.

\item Support for spectral coordinate systems has been introduced
throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}.
The SpecFrame is a 1-dimensional Frame which can be used to describe
positions within an electromagnetic spectrum in various systems
(wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred
to various standards of rest (topocentric, geocentric, heliocentric
LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral
axis values between these various systems and standards of rest. Note,
FitsChans which have a foreign encoding (\emph{i.e.} any encoding other
than NATIVE) are not yet able to read or write these new classes.

\item Facilities have been added to the Frame class which allow
differences in axis units to be taken into account when finding a Mapping
between two Frames. In previous versions of AST, the Unit attribute was a
purely descriptive item intended only for human readers - changing the
value of Unit made no difference to the behaviour of the Frame. As of
version 2.0, the Unit attribute can influence the nature of the Mappings
between Frames. For instance, if the
astFindrame or \htmlref{astConvert}{astConvert}
method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m''
and another Axis with Unit set to ``km'', then the method will return a
\htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes.
These facilities assume that units are specified following the rules
included in FITS-WCS paper I (\emph{Representation of World
Coordinates in FITS}, Greisen \& Calabretta).

In order to minimise the risk of breaking existing software, the default
behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.}
to retain the previous behaviour). However, the new Frame method
\htmlref{astSetActiveUnit}{astSetActiveUnit}
may be used to ``activate'' (or deactivate) the new facilities within a
specific Frame. Note, the new SpecFrame class is different to the simple
Frame class in that the new facilities for handling units are always active
within a SpecFrame.

\item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been
moved to the parent Frame class. This enables all sub-classes of Frame
(such as the new SpecFrame class) to share these attributes, and to provide
suitable options for each class.

\item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows
control over the alignment process performed by the methods
\htmlref{astFindFrame}{astFindFrame} and astConvert.


\item The CmpFrame class has been modified so that attributes of a
component Frame can be accessed without needing to extract the Frame first.
To do this, append an axis index to the end of the attribute name. For
instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order),
then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the
``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute
of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently
``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the
CmpFrame will refer to the System attribute of the SpecFrame, whereas the
``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the
System attribute of the SkyFrame (the ``System'' attribute without an axis
specifier will refer to the System attribute of the CmpFrame as a whole,
since System is an attribute of all Frames, and a CmpFrame is a Frame and
so has its own System value which is independant of the System attributes
of its component Frames).

\item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit
overlapping axis labels, and the abbreviation of redundant leading fields
within sexagesimal axis labels, have been improved to avoid some anomolous
behaviour in previous versions.

\item The curve drawing algorithm used by the Plot class has been
modified to reduce the chance of it ``missing'' small curve sections,
such as may be produced if a grid line cuts across the plot very close to
a corner. Previously, these missed sections could sometimes result in
axis labels being omitted.

\item A new function
(\htmlref{astVersion}{astVersion})
has been added to return the version of the AST library in use.

\item Bugs have been fixed in the Plot class which caused serious problems
when plotting high precision data. These problems could range from the
omission of some tick marks to complete failure to produce a plot.

\end{enumerate}

Programs which are statically linked will need to be re-linked in
order to take advantage of these new facilities.


\subsection{Changes Introduced in V3.0}

The following describes the most significant changes which
occurred in the AST library between versions V2.0 and V3.0:

\begin{enumerate}

\item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring
the FITS-WCS encoding into line with the current versions of the FITS-WCS
papers (see
\url{http://www.atnf.csiro.au/people/mcalabre/WCS/}):

\begin{itemize}

\item The rotation and scaling of the pixel axes may now be specified using
either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute
called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which
set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS
header.

\item The FITS-WCS encoding now supports most of the conventions
described in FITS-WCS paper III for the description of spectral
coordinates. The exceptions are that the SSYSOBS keyword is not
supported, and WCS stored in tabular form (as indicated by the ``-TAB''
algorithm code) is not supported.


\item User-specified fiducial points for WCS projections are now
supported by FitsChans which use FITS-WCS encoding. This use keywords
PVi\_0, PVi\_1 and PVi\_2 for the longitude axis.

\item  When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3
and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE
and LATPOLE keywords which may be present. When writing a FITS-WCS header,
both forms are written out.

\item The number of WCS axes is stored in the WCSAXES keyword if its value
would be different to that of the NAXIS keyword.

\item Helio-ecliptic coordinates are now supported by FitsChans which use
FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The
resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all
the usual facilities, such as conversion to other celestial systems, are
available.

\item The FITS-WCS encoding now supports most of the conventions
described in FITS-WCS paper III for the description of spectral
coordinates. The exceptions are that the SSYSOBS keyword is not
supported, and WCS stored in tabular form (as indicated by the ``-TAB''
algorithm code) is not supported.

\item When reading a FITS-WCS header, a FitsChan will now ignore any
distortion codes which are present in CTYPE keywords. Here, a ``distortion
code'' is the final group of four characters in a CTYPE value of the
form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception
to this is that the ``-SIP'' distortion code (as used by the Spitzer
Space Telescope project - see
\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is
interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent
the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes
can only be read, not written. A FrameSet which uses a PolyMap will not
in general be able to be written out to a FitsChan using any foreign
encoding (although NATIVE encoding can of course be used).

\item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values
``BadVal'' (which gives warnings about conversion errors when reading
FITS keyword values), ``Distortion'' (which gives warnings about
unsupported distortion codes within CTYPE values), and ``BadMat'' (which
gives a warning if the rotation/scaling matrix cannot be inverted).

\item When writing a FrameSet to a FitsChan which uses a non-Native
encoding, the comment associated with any card already in the FitsChan
will be retained if the keyword value being written is the same as the
keyword value already in the FitsChan.

\item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN
projection with polynomial distortion terms) can now be written to a
FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard
``-TAN'' code is used within the CTYPE values, and the distortion
coefficients are encoded in keywords of the form `` QVi\_ma'', which are
directly analogous to the standard ``PVi\_ma'' projection parameter keywords.
Thus a FITS reader which does not recognise the QV keywords will still
be able to read the header, but the distortion will be ignored.

\item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value
of the Encoding attribute.

\item A new appendix has been added to SUN/210 and SUN/211 giving details
of the implementation provided by the FitsChan class of the
conventions contained in the first four FITS-WCS papers.
\end{itemize}

\item The SkyFrame class now supports two new coordinate systems ``ICRS''
and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames
has been changed from ``FK5'' to ``ICRS''.

\item The
\htmlref{astRate}{astRate}
function has been added which allows an estimate to be made of the rate of
change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs.

\item All attribute names for Frames of any class may now include an optional
axis specifier. This includes those attributes which describe a property
of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be
specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases
such as this, where the attribute describes a property of the whole
Frame, axis specifiers will usually be ignored. The exception is that a
\htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the
attribute name relates to the primary Frame containing the specified
axis, rather than to the CmpFrame as a whole.

\item A new subclass of Mapping, the PolyMap, has been added which
performs a general N-dimensional polynomial mapping.

\item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which
models the spectral dispersion produced by a grating, prism or grism.

\item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds
constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap}
with unit scaling on all axes).

\item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice
and placement of numerical axis labels.

\item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the
longitude value to be returned when a Cartesian position corresponding to
either the north or south pole is transformed into spherical coordinates.

\item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output
celestial coordinates which have a latitude of plus or minus 90 degrees.

\item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been
changed so that they now return the fixed native coordinates of the
projection reference point, rather than the native coordinates of the
user-defined fiducial point.

\item Notation has been changed in both the WcsMap and FitsChan classes to
reflect the convention used in the FITS-WCS papers that index ``i'' refers
to a world coordinate axis, and index ``j'' refers to a pixel axis.

\item Changes have been made to several Mapping classes in order to allow
the
\htmlref{astSimplify}{astSimplify}
function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not
possible.

\item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions
between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates.

\item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the
refractive index of air as given in the current version of FITS-WCS paper
III. Also, the forward and inverse transformations between frequency and
air-wavelength have been made more compatible by using an iterative
procedure to calculate the inverse.

\end{enumerate}

\subsection{Changes Introduced in V3.1}

The following describes the most significant changes which have
occurred in the AST library between versions V3.0 and V3.1 (the
current version):

\begin{enumerate}
\item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which
reads and writes AST objects in the form of XML.
\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect
graphical attributes to be used for various parts of the plot if either
axis has no tick marks (i.e. if both major and minor tick marks have zero
length).
\end{enumerate}

Programs which are statically linked will need to be re-linked in
order to take advantage of these new facilities.


\subsection{Changes Introduced in V3.2}

The following describes the most significant changes which have
occurred in the AST library between versions V3.1 and V3.2:

\begin{enumerate}

\item A new
function \htmlref{astPutCards}{astPutCards}
has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header
cards to be stored in a FitsChan in a single call, providing an alternative to
the existing
astPutCards function.

\item Some signficant changes have been made to the simplification of Mappings
 which should resultin a greater degree of simplication taking place.Some
 bugs have also been fixed which could result in an infinite loop being
 entered when attempting to simplify certain Mappings.

\item The FitsChan class now translates the spectral algorithm codes
``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to
the corresponding ``-X2P'' form when reading a spectral axis description
from a set of FITS header cards.

\item A bug has been fixed in the FitsChan class which could cause
keywords associated with alternate axis descriptions to be mis-interpreted.

\item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance
of sub-strings within text strings such as axis labels, titles, \emph{etc},
by producing super-scripts, sub-scripts, changing the font colour, size,
\emph{etc}. See attribute \htmlref{Escape}{Escape}.

\item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been
changed from 0.001 to 0.01. This should not usually cause any significant
visible change to the plot, but should make the plotting faster. You may
need to set a lower value for Tol if you are producing a particularly
large plot.

\item The algorithm for finding the default value for the Gap attribute
has been changed. This attribute specifies the gap between major axis
values in an annotated grid drawn by the Plot class. The change in
algorithm may cause the default value to be different to previous versions
in cirtain circumstances.

\item Some bugs have been fixed in the Plot class which could cause the
system to hang for a long time while drawing certain all-sky grids
(notable some of the FITS Quad-cube projections).

\item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition
of the ``g'' option. this option is similar to the older ``l'' option in that
it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as
delimiters between the sexagesimal fields of the celestial position. The
difference is that the ``g'' option includes graphics escape sequences
in the returned formatted string which result in the field delimiter
characters being drawn as super-scripts when plotted as numerical axis values
by a Plot.

\item The Plot class has been extended to include facilities for producing
logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel.

\item New functions astGCap and astGScales have been added to the interface
defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so
that the \verb+-mygrf+ switch loads dummy versions of the new grf
functions. This means that applications should continue to build without
any change. However, the facilities for interpreting escape sequences
within strings drawn by the Plot class will not be available unless the
new grf functions are implemented. If you choose to implement them, you
should modify your linking procedure to use the \verb+-grf+ switch in
place of the older \verb+-mygrf+ switch. See the description of the ast\_link
command for details of the new switches. Also note that the astGQch
function, whilst included in verb+grf.h+ in pervious versions of AST, was
not actually called. As of this version of AST, calls are made to the
astGQch function, and so any bugs in the implementation of astGQch may
cause spurious behaviour when plotting text strings.

\item A new 'static' method called \htmlref{astEscapes}{astEscapes} has been added which is used
to control and enquire whether astGetC and \htmlref{astFormat}{astFormat} will strip any graphical
escape sequences which may be present out of the returned value.

\item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It
allows XML written by the XmlChan class to include an explicit namespace
prefix on each element.

\item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It
specifies the format in which AST objects should be written.

\item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap
takes its forward transformation from an existing Mapping, and its inverse
transformation from another existing Mapping.

\item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to
include erroneous axis numbers when referring to missing parameter values.

\end{enumerate}

\subsection{Changes Introduced in V3.3}

The following describes the most significant changes which have
occurred in the AST library between versions V3.2 and V3.3:

\begin{enumerate}

\item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the
origin
of celestial coordinates to be moved to any specified point. See the new
attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}.

\item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra
Frames representing cartesian projection plane coordinates (``intermediate
world coordinates'' in the parlance of FITS-WCS) to be created when
reading
WCS information from a foreign FITS header. This option is controlled by
a new attribute called \htmlref{Iwc}{Iwc}.

\item The FitsChan class which been modified to interpret FITS-WCS CAR
projection headers correctly if the longitude reference pixel (CRPIX) is
very large.

\item The  FITS-AIPS++ encoding in the FitsChan class now recognised
spectral axes if they conform to the AIPS convention in which the
spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB"
where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD,
HEL or OBS. Such spectral axes can be both read and written.

\item The FitsChan class now has a FITS-AIPS++ encoding which represents
WCS information using FITS header cards recognised by the AIPS++ project.
Support for spectral axes is identical to the FITS-AIPS encoding.

\item The organisation of the AST distribution and the commands for
building it have been changed. Whereas AST used to be built and installed
with \verb+./mk build; ./mk install+, it now builds using the more standard
idiom \verb+./configure; make; make install+. The installation location is
controlled by the \verb+--prefix+ argument to ./configure (as is usual
for other packages which use this scheme).  Note that the INSTALL environment
variable now has a \emph{different} meaning to that which it had
before, and it should generally be \emph{unset}. Also, there is no need to
set the SYSTEM variable.

\item Shared libraries are now installed in the same directory as the
static libraries. In addition, links to sharable libraries are installed
with names which include version information, and ``libtool libraries''
are also installed (see
\url{http://www.gnu.org/software/libtool/manual.html}).

\item The \verb+ast_dev+ script has been removed. Instead, the location of
the AST include files should be specified using the -I option when
compiling.


\end{enumerate}


\subsection{Changes Introduced in V3.4}

The following describes the most significant changes which have
occurred in the AST library between versions V3.3 and V3.4:

\begin{enumerate}

\item The \htmlref{Mapping}{Mapping} class has a new method
(\htmlref{astLinearApprox}{astLinearApprox})
which calculates the co-efficients of a linear approximation to a Mapping.

\item The Format attribute for simple Frames and SkyFrames has been extended.
It has always been possible, in both classes, to specify a precision by
including a dot in the Format value followed by an integer (\emph{e.g.}
``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}).
The precision can now also be specified using an asterisk in place of the
integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the
precision to be derived on the basis of the Digits attribute value.

\item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the
Digits attribute is chosen to be the smallest value which results in no
pair of adjacent labels being identical. For instance, if an annotated
grid is being drawn describing a SkyFrame, and the Format(1) value is set
to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as
superscripts), and the Digits(1) value is unset, then the seconds field
will have a number of decimal places which results in no pair of labels
being identical.

\item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a
sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes
associated with dual sideband spectral data.

\item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS''
projection code, converting them to the corresponding modern ``-SFL'' code,
provided that the celestial axes are not rotated.

\item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows
the reading and writing of FITS headers using the conventions of the CLASS
package - see
\url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}).

\end{enumerate}


\subsection{Changes Introduced in V3.5}

The following describes the most significant changes which have
occurred in the AST library between versions V3.4 and V3.5:

\begin{enumerate}

\item AST now provides facilities for representing regions of various
shapes within a coordinate system. The \htmlref{Region}{Region} class provides general
facilities which are independent of the specific shape of region being
used. Various sub-classes of Region are also now available which provide
means of creating Regions of specific shape. Facilities provided by the
Region class include testing points to see if they are inside the
Region, testing two Regions for overlap, transforming Regions from one
coordinate system to another \emph{etc}.

\item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which
can be used to describe various systems for describing ovserved value at a
single fixed spectral position.

\item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which
can be used to describe a 2-d frame spanned by a spectral position axis
and and an observed value axis.

\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates
a previously created Mapping. The inputs of the RateMap correspond to the
inputs of the encapsulated Mapping. All RateMaps have just a single
output which correspond to the rate of change of a specified output of
the encapsulated Mapping with respect to a specified input.

\item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}.
This system is an equatorial system based on the mean dynamical equator and
equinox at J2000, and differs slightly from an FK5(J2000) system.

\item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to
store a collection of vector or scalar values or Objects, indexed by a
character string rather than an integer.

\item The parameter list for the
\htmlref{astRate}{astRate}
method of the Mapping class has been modified. It no longer returns a second
derivative estimate. Existing code which uses this method will need to be
changed.

\item Methods
(astSetFits<X>)
have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named
keywords to be changed or added.

\end{enumerate}


\subsection{Changes Introduced in V3.6}

The following describes the most significant changes which
occurred in the AST library between versions V3.5 and V3.6:

\begin{enumerate}

\item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame}
starts with a percent character (``\verb+%+''), then axis values are
now formatted and unformatted as a decimal radians value, using the
Format syntax of a simple \htmlref{Frame}{Frame}.

\item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the
clipping performed by AST at the plot boundary.

\item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a
PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys
are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}.
The new PolyMap class always writes new styles keys but can read either
old or new style keys. Consequently, PolyMap dumps written by this
version of AST cannot be read by older versions of AST.

\item A mimimal cut down subset of the C version of SLALIB is now
included with the AST distribution and built as part of building AST.
This means that it is no longer necessary to have SLALIB installed
separately at your site. The SLALIB code included with AST is distrubuted
under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to
link with this internal slalib subset. However, the ``-csla'' option can
still be used to force linking with an external full C SLALIB library.
A new option ``-fsla'' has been introduced which forces linking with the
external full Fortran SLALIB library.

\end{enumerate}

\subsection{Changes Introduced in V3.7}

The following describes the most significant changes which
occurred in the AST library between versions V3.6 and V3.7:

\begin{enumerate}

\item Support for time coordinate systems has been introduced
throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}.
The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe
moments in time (either absolute or relative) in various systems (MJD,
Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC,
UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time
values between these various systems and time scales. Note,
FitsChans which have a foreign encoding (\emph{i.e.} any encoding other
than NATIVE) are not able to read or write these new classes.

\end{enumerate}


\subsection{Changes Introduced in V4.0}

The following describes the most significant changes which
occurred in the AST library between versions V3.7 and V4.0:

\begin{enumerate}

\item Experimental support for reading IVOA Space-Time-Coordinates (STC-X)
descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included
for a subset of V1.20 of the draft STC specification.

\item A new set of methods (AST\_REBIN<X>/astRebin<X>) has been added to
the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing
AST\_RESAMPLE<X>/astResample<X> methods.

\end{enumerate}


\subsection{Changes Introduced in V4.1}

The following describes the most significant changes which
occurred in the AST library between versions V4.0 and V4.1:

\begin{enumerate}

\item A new control flag has been added to the AST\_RESAMPLE<X>/astResample<X>
functions which produces approximate flux conservation.

\item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to
ast.h. These specify kernels for astResample and astRebin
based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the
first order Bessel function of the first kind).

\item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding
to horizon (azimuth/elevation) coordinates.

\item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and
``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values.

\item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify
the geodetic longitude and latitude of the observer.

\item The ClockLon and ClockLat attributes have been removed from the
\htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been
removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and
ObsLat attributes of the parent Frame class instead. However, the old
attribute names can be used as synonyms for ObsLat and ObsLon. Also,
dumps created using the old scheme can be read succesfully by AST V4.1
and converted to the new form.

\item A new
function \htmlref{astMapSplit}{astMapSplit}
has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component
Mappings which, when combined in parallel, are equivalent to the original
Mapping.

\item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from
``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame
to represent offsets from some origin position, you must now set the
SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in
addition to assigning the required origin position to the SkyRef attribute.

\end{enumerate}

\subsection{Changes Introduced in V4.2}

The following describes the most significant changes which
occurred in the AST library between versions V4.1 and V4.2:

\begin{enumerate}

\item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the
option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the
DSBSpecFrame to represent the offset from the local oscillator frequency,
rather than either of the two sidebands.

\item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS
keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric
apparent velocity of the standard of rest). FitsChan also strips out VELOSYS
keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding.

\item The FitsChan class has a new method called
\htmlref{astRetainFits}{astRetainFits}
that indicates that the current card in the FitsChan should not be
stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan.
Unless this method is used, all cards that were involved in the creation
of the AST Object will be stripped from the FitsChan afte a read operation.

\item A problem with unaligned memory access that could cause bus errors on
Solaris has been fixed.

\item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base
Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the
Object. Note, this is the size of the internal in-memory representation of
the Object, not the size of the textual representation produced by
writing the Object out through a \htmlref{Channel}{Channel}.

\item A new function
\htmlref{astTune}{astTune}
has been added which can be used to get and set global AST tuning
parameters. At the moment there are only two such parameter, both of
which are concerned with memory management within AST.

\item A new method called
\htmlref{astTranGrid}{astTranGrid}
has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular
grid of points covering a rectangular region within the input space of a
Mapping, and then transforms this set of points into the output space of the
Mapping, using a piecewise-continuous linear approximation to the Mapping
if appropriate in order to achive higher speed.

\item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A
SwitchMap represents several alternate Mappings, each of which is used to
transforms input positions within a different region of the input
coordinate space.

\item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A
SelectorMap tests each input position to see if it falls within one of
several Regions. If it does, the index of the \htmlref{Region}{Region} containing the
input position is returned as the Mapping output.

\item The behaviour of the
\htmlref{astConvert}{astConvert}
method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been
modified. If no conversion between positions in the Frame and CmpFrame
can be found, an attempt is now made to find a conversion between the
Frame and one of two component Frames contained within the CmpFrame. Thus
is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a
SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad
values for the extra axes (i.e. for the SpecFrame axis in the above example).

\item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the
\verb+-fsla+ and \verb+-csla+ options, and always link against the
minimal cut-down version of SLALIB distributed as part of AST.

\end{enumerate}

\subsection{Changes Introduced in V4.3}

The following describes the most significant changes which occurred in the
AST library between versions V4.2 and V4.3:

\begin{enumerate}

\item The
astGetFitsS
function now strips trailing white space from the returned string, if the
original string contains 8 or fewer characters

\item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified
whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the
source) should be accessed as an apparent radial velocity or a redshift.
Note, any existing software that assumes that SourceVel always represents
a velocity in km/s should be changed to allow for the possibility of
SourceVel representing a redshift value.

\end{enumerate}


\subsection{Changes Introduced in V4.4}

The following describes the most significant changes which occurred in
the AST library between versions V4.3 and V4.4:

\begin{enumerate}

\item The
\htmlref{astFindFrame}{astFindFrame}
function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more
specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame}
or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as
the ``template'' when calling
astFindFrame,
and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the
current Frame is a CmpFrame), then the component Frames within the CmpFrame
will be searched for an instance of the supplied template Frame, and, if
found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the
required axes from the CmpFrame) will be returned by
astFindFrame.
Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template
Frame must be set so that they cover a range that includes the number of axes
in the target CmpFrame.

\item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes
now allow the MaxAxes and MinAxes attributes to be set freely to any value.
In previous versions of AST, any attempt to change the value of MinAxes
or MaxAxes was ignored, resulting in them always taking the default values.

\item The DSBSpecFrame class has a new attribute called AlignSB that
specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when
aligning two DSBSpecFrames using
\htmlref{astConvert}{astConvert}.

\item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to
store a value for the difference between the UT1 and UTC timescales at
the epoch referred to by the Frame.

\item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and
\htmlref{ObsLon}{ObsLon} has been increased.

\item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This
attribute is used to control how two SkyFrames are aligned by
astConvert.
If the template and target SkyFrames both have a non-zero value for
AlignOffset, then alignment occurs between the offset coordinate systems
(that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames).

\item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be
used to force exterior (rather than interior) tick marks to be produced.
By default, exterior ticks are only produced if this would result in
more than 3 tick marks being drawn.

\item The TimeFrame class now supports conversion between angle based
timescales such as UT1 and atomic based timescales such as UTC.

\end{enumerate}

\subsection{Changes Introduced in V4.5}

The following describes the most significant changes that
occurred in the AST library between versions V4.4 and V4.5:

\begin{enumerate}



\item All FITS-CLASS headers are now created with a frequency axis. If the
\htmlref{FrameSet}{FrameSet} supplied to
\htmlref{astWrite}{astWrite}
contains a velocity axis (or any other form
of spectral axis) it will be converted to an equivalent frequency axis
before being used to create the FITS-CLASS header.

\item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed
from the velocity of the source to the velocity of the reference channel.

\item Addition of a new method call
\htmlref{astPurgeWCS}{astPurgeWCS}
to the \htmlref{FitsChan}{FitsChan}
class. This method removes all WCS-related header cards from a FitsChan.

\item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used
to comminicate context information between an application and any
graphics functions registered with the Plot class via the
\htmlref{astGrfSet}{astGrfSet} function.
\item Functions registered with the Plot class using
astGrfSet
now take a new additional integer parameter, ``grfcon''. The Plot class
sets this parameter to the value of the Plot's GrfContext attribute before
calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING
CODE THAT USES
astGrfSet
TO BE MODIFIED TO INCLUDE THE NEW PARAMETER.
\item The
astRebinSeq functions
now have an extra parameter that is used to record the total number of input
data values added into the output array. This is necessary to correct a
flaw in the calculation of output variances based on the spread of input
values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO
INCLUDE THE NEW PARAMETER (CALLED "NUSED").
\item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection.
\item A new flag ``AST\_\_VARWGT'' can be supplied to
astRebinSeq.
This causes the input data values to be weighted using the reciprocals of
the input variances (if supplied).

\item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that
returns the normalised value of the Unit attribute for an axis. Here,
``normalisation'' means cancelling redundant units, etc. So for instance, a
Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''.

\item A new
function \htmlref{astShowMesh}{astShowMesh}
has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering
the surface of a Region by writing out a table of axis values to standard
output.

\item The Plot class now honours the value of the LabelUp attribute even if
numerical labels are placed around the edge of the Plot. Previously
LabelUp was only used if the labels were drawn within the interior of
the plot. The LabelUp attribute controls whether numerical labels are
drawn horizontally or parallel to the axis they describe.

\item A bug has been fixed that could segmentation violations when setting
attribute values.

\end{enumerate}

\subsection{Changes Introduced in V4.6}

The following describes the most significant changes which have
occurred in the AST library between versions V4.5 and V4.6:

\begin{enumerate}

\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset
from UTC to Local Time is specified by a new TimeFrame attribute called
\htmlref{LTOffset}{LTOffset}.

\item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows
the creation of 3-dimensional annotated coordinate grids.

\item A correction for diurnal aberration is now included when
converting between AZEL and other celestial coordinate systems. The
correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the
geodetic latitude of the observer).

\item A bug has been fixed which caused the DUT1 attribute to be ignored
by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other
celestial coordinate systems.

\end{enumerate}

\subsection{Changes Introduced in V5.0}

The following describes the most significant changes which
occurred in the AST library between versions V4.6 and V5.0:

\begin{enumerate}


\item The AST library is now thread-safe (assuming that the POSIX pthreads
library is available when AST is built). Many of the macros defined in
the ast.h header file have changed. It is therefore necessary to
re-compile all source code that includes ast.h.

\item New methods \htmlref{astLock}{astLock} and \htmlref{astUnlock}{astUnlock} allow an AST \htmlref{Object}{Object} to be locked
for exclusive use by a thread.

\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset
from UTC to Local Time is specified by a new TimeFrame attribute called
\htmlref{LTOffset}{LTOffset}.

\item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls
whether or not to report an error if unexpected data items are found
within an AST Object description read from an external data source. Note,
the default behaviour is now not to report such errors. This differs from
previous versions of AST which always reported an error is unexpected
input items were encountered.

\end{enumerate}

\subsection{Changes Introduced in V5.1}

The following describes the most significant changes which occurred in the
AST library between versions V5.0 and V5.1:

\begin{enumerate}

\item The \htmlref{astUnlock}{astUnlock} function now has an extra parameter that controls whether
or not an error is reported if the \htmlref{Object}{Object} is currently locked by another
thread.

\item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can
be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval}
could be used for this purpose.

\item The values of the AST\_\_THREADSAFE macro (defined in ast.h) have
been changed from ``yes'' and ``no'' to ``1'' and ``0''.

\item Improvements have been made to the way that Prisms are simplified
when
\htmlref{astSimplify}{astSimplify}
is called.  The changes mean that more types of Prism will now simplify
into a simpler class of Region.

\item The \htmlref{PointList}{PointList} class has a new method,
astPoints,
that copies the axis values from the PointList into a supplied array.

\item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that
gives the number of points stored in the PointList.

\item The handling of warnings within different classes of \htmlref{Channel}{Channel} has
been rationalised. The XmlStrict attribute and
astXmlWarnings
function have been removed. The same functionality is now available via
the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new
attribute called \htmlref{ReportLevel}{ReportLevel}, and the new
\htmlref{astWarnings}{astWarnings}
function. This new function can be used on any class of Channel. Teh
\htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as
header cards within the FitsChan, but it also now stores warnings in the
parent Channel structure, from where they can be retrieved using the
astWarnings
function.

\item A new function called
astIntercept
has been added to the \htmlref{Frame}{Frame} class. This function finds the point of
intersection beteeen two geodesic curves.

\item A bug in the type-checking of Objects passed as arguments to constructor
functions has been fixed. This bug could lead to applications crashing or
showing strange behaviour if an inappropriate class of Object was
supplied as an argument to a constructor.

\item The
\htmlref{astPickAxes}{astPickAxes}
function will now return a Region, if possible, when applied to a Region. If
this is not possible, a Frame will be returned as before.

\item The choice of default tick-mark for time axes has been improved, to avoid
previous issues which could result in no suitable gap being found, or
inappropriate tick marks when using formatted dates.

\item A new function called
\htmlref{astTestFits}{astTestFits}
has been added to the FitsChan class. This function tests a FitsChan to
see if it contains a defined value for specified FITS keyword.

\item The AST\_\_UNDEF<X> parameters used to flag undefined FITS keyword values
have been removed. Use the new
astTestFits
function instead.

\item The astIsUndef<X> functions used to test FITS keyword values
have been removed. Use the new astTestFits function instead.

\end{enumerate}

\subsection{Changes Introduced in V5.2}

The following describes the most significant changes which
occurred in the AST library between versions V5.1 and V5.2:

\begin{enumerate}

\item A new method called
\htmlref{astSetFitsCM}{astSetFitsCM}
has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a
FitsChan (that is, a card with no keyword name or equals sign).

\item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It
records the geodetic altitude of the observer, in metres. It defaults to
zero. It is used when converting times to or from the TDB timescale, or
converting spectral positions to or from the topocentric rest frame, or
converting sky positions to or from horizon coordinates. The FitsChan
class will include its effect when creating a set of values for the
OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a
set of OBSGEO-X/Y/Z keyword values from a FITS header.

\item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap}
conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument -
the observer's geodetic altitude.

\item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the
IVOA STC definition of a Polygon. Specifically, the inside of a polygon
is now the area to the left of each edge as the vertices are traversed in
an anti-clockwise manner, as seen from the inside of the celestial sphere.
Previously, AST used the anti-clockwise convention, but viewed from the
outside of the celestial sphere instead of the inside. Any Polygon saved
using previous versions of AST will be identified and negated automatically
when read by AST V5.2.

\item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows
conversion of suitable AST Objects to and from IVOA STC-S format.

\item A new method called
\htmlref{astRemoveRegions}{astRemoveRegions}
has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound)
Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either
removes them, or replaces them with UnitMaps (or equivalent Frames). It
can be used to remove the masking effects of Regions from a compound
Mapping or Frame.

\item A new method called
\htmlref{astDownsize}{astDownsize}
has been added to the Polygon class. It produces a new Polygon that
contains a subset of the vertices in the supplied Polygon. The subset is
chosen to retain the main features of the supplied Polygion, in so far
as that is possible, within specified constraints.

\item A new constructor called
astOutline
has been added to the Polygon class. Given a 2D data array, it identifies
the boundary of a region within the array that holds pixels with
specified values. It then creates a new Polygon to describe this boundary
to a specified accuracy.

\item A new set of methods, called
astMapGetElem<X>
has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector
valued entry to be returned.

\item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It
controls whether the
astMapGet...
family of functions report an error if an entry with the requested key does
not exist in the KeyMap.

\end{enumerate}

\subsection{Changes Introduced in V5.3}

The following describes the most significant changes which
occurred in the AST library between versions V5.2 and V5.3:

\begin{enumerate}

\item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the
\htmlref{astFindFrame}{astFindFrame} and \htmlref{astConvert}{astConvert}
functions have been changed. The changes mean that a Frame can now be
aligned with an instance of a sub-class of Frame, so long as the number
of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic
2-dimensional Frame with Domain ``SKY'' will now align succesfully with
a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a
\htmlref{UnitMap}{UnitMap}.

\item The arrays that supply input values for astMapPut1<X> are now
declared ``const''.

\item Added method
\htmlref{astMatchAxes}{astMatchAxes}
to the Frame class. This method allows corresponding axes within two
Frames to be identified.

\item The
\htmlref{astAddFrame}{astAddFrame}
method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}.
\end{enumerate}

\subsection{Changes Introduced in V5.3-1}

The following describes the most significant changes which have
occurred in the AST library between versions V5.3 and V5.3-1:

\begin{enumerate}

\item The utility functions provided by the AST memory management layer
are now documented in an appendix.

\item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A
new method called
\htmlref{astMapPutU}{astMapPutU}
will store an entry with undefined value in a keymap. Methods that
retrieve values from a KeyMap
(astMapGet0<X>, etc.)
ignore entries with undefined values when searching for an entry with a given
key.

\item The KeyMap class has a new method called
\htmlref{astMapCopy}{astMapCopy}
that copies entries from one KeyMap to another KeyMap.

\item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If
non-zero,
an error is reported if an attempt is made to add any new entries
to a KeyMap (the value associated with any old entry may still be changed
without error). The default is
zero.

\item The \htmlref{Object}{Object} class has a new method called \htmlref{astHasAttribute}{astHasAttribute}/AST\_HASATTRIBUTE
that returns a boolean value indicating if a specified Object has a named
attribute.

\item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called
IsLatAxis and IsLonAxis that can be used to determine the nature of a
specified SkyFrame axis.

\item A bug has been fixed in the
astRebin(Seq)
methods that could cause flux to be lost from the edges of the supplied array.

\item A bug has been fixed in the
astRebin(Seq)
methods that caused the first user supplied parameter to be interpreted as the
full width of the spreading kernel, rather than the half-width.

\item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except
that units strings are still case sensitive).

\item A new \htmlref{Mapping}{Mapping} method,
\htmlref{astQuadApprox}{astQuadApprox},
produces a quadratic least-squares fit to a 2D Mapping.

\item A new Mapping method,
\htmlref{astSkyOffsetMap}{astSkyOffsetMap},
produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame
coordinates.

\item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation
in the text created by
\htmlref{astWrite}{astWrite}.
The StcsIndent and XmlIndent attributes have been removed.

\item All classes of Channel now use the string ``<bad>'' to represent the
floating point value AST\_\_BAD, rather than the literal formatted value
(typically ``-1.79769313486232e+308'' ).

\item The KeyMap class now uses the string ``<bad>'' to represent the
floating point value AST\_\_BAD, rather than the literal formatted value
(typically ``-1.79769313486232e+308'' ).

\item The KeyMap class has a new method called
astMapPutElem<X>
that allows a value to be put into a single element of a vector entry in
a KeyMap. The vector entry is extended automatically to hold the new
element if required.

\item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator
frequency is less than the absoliute value of the intermediate frequency.

\end{enumerate}


\subsection{Changes Introduced in V5.3-2}

The following describes the most significant changes which
occurred in the AST library between versions V5.3-1 and V5.3-2:

\begin{enumerate}

\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength
axes to be assigned the units ``m/s'' when reading WCS information from a
FITS header.

\item The
\htmlref{astSet}{astSet} function
now allows literal commas to be included in string attribute values. String
attribute values that include a literal comma should be enclosed in quotation
marks.

\item A bug in FitsChan has been fixed that caused ``-SIN'' projection
codes within FITS-WCS headers to be mis-interpreted, resulting in no
\htmlref{FrameSet}{FrameSet} being read by \htmlref{astRead}{astRead}.

\item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls
the order in which keys are returned by the
\htmlref{astMapKey}{astMapKey}
function. Keys can be sorted alphabetically or by age, or left unsorted.

\item Access to KeyMaps holding thousands of entries is now significantly
faster.

\item KeyMaps can now hold word (i.e.
short integer)
values.

\end{enumerate}


\subsection{Changes Introduced in V5.4-0}

The following describes the most significant changes which
occurred in the AST library between versions V5.3-2 and V5.4-0:

\begin{enumerate}

\item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing
of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper
III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}.
See the documentation for TabOK for more information.

\item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in
which each entry represents a cell in a two-dimensional table.

\item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a
Table that has an associated FitsChan holding headers appropriate to a
FITS binary table.

\item KeyMaps can now hold byte values. These are held in variables
of type
"unsigned char".

\item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to
make the handling of keys case insensitive.

\item a memory leak associated with the use of the
astMapPutElem<X>
functions has been fixed.

\item A new method called
\htmlref{astMapRename}{astMapRename}
has been added to rename existing entry in a KeyMap.
\end{enumerate}

\subsection{Changes Introduced in V5.5-0}

The following describes the most significant changes which
occurred in the AST library between versions V5.4-0 and V5.5-0:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather
than a boolean value. If TabOK is set to a non-zero positive integer
before invoking the
\htmlref{astWrite}{astWrite}
method, its value is used as the version number for any table that is
created as a consequence of the write operation. This is the value stored
in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the
binary table header. In previous versions of AST, the value used for these
headers could not be controlled and was fixed at 1. If TabOK is set to a
negative or zero value, the -TAB algorithm will not be supported by
either the
astWrite or \htmlref{astRead}{astRead}
methods.

\end{enumerate}



\subsection{Changes Introduced in V5.6-0}

The following describes the most significant changes which
occurred in the AST library between versions V5.5-0 and V5.6-0:

\begin{enumerate}

\item
New functions \htmlref{astBBuf}{astBBuf} and \htmlref{astEBuf}{astEBuf}
have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical
output produced by other Plot methods.

\item New functions astGBBuf and astGEBuf have been added to the interface
defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so
that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf
functions. This means that applications that use the  \verb+-grf_v3.2+
switch should continue to build without any change. However, the new public
functions astBBuf and astEBuf
will report an error unless the new grf functions are implemented. If you
choose to implement them, you should modify your linking procedure to
use the \verb+-grf+ (or  \verb+-grf_v5.6+ ) switch in place of the older
\verb+-grf_v3.2+ switch. See the description of the ast\_link command for
details of these switches.

\item New method
\htmlref{astGetRegionMesh}{astGetRegionMesh}
returns a set of positions covering the boundary, or volume, of a supplied
\htmlref{Region}{Region}.

\end{enumerate}


\subsection{ChangesIntroduced in V5.6-1}

The following describes the most significant changes which
occurred in the AST library between versions V5.6-0 and V5.6-1:

\begin{enumerate}

\item Tables can now have any number of parameters describing the global
properties of the \htmlref{Table}{Table}.

\item Frames now interpret the unit string ``A'' as meaning ``Ampere''
rather than ``Angstrom'', as specified by FITS-WCS paper I.

\item A bug has been fixed in the
\htmlref{astFindFrame}{astFindFrame}
method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match
a target frame of a less specialised class. For example, this bug would
allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer
happens.

\end{enumerate}

\subsection{Changes Introduced in V5.7-0}

The following describes the most significant changes which
occurred in the AST library between versions V5.6-1 and V5.7-0:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has
been extended to include reading TNX headers that use a Chebyshev
representation for the distortion polynomial.

\item The FitsChan class support for the IRAF-specific ``ZPX'' projection has
been extended to include reading ZPX headers that use simple or Chebyshev
representation for the distortion polynomial.

\item A bug has been fixed in the FitsChan class that caused headers
including the Spitzer ``-SIP'' distortion code to be read incorrectly if no
inverse polynomial was specified in the header.

\item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It
can be used to indicate that FITS headers that specify a TAN projection
should be interpreted according to the ``distorted TAN'' convention
included in an early draft of FITS-WCS paper II. Such headers are created
by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}).

\item The \htmlref{PolyMap}{PolyMap} class now provides a method called
\htmlref{astPolyTran}{astPolyTran}
that adds an inverse transformation to a PolyMap by sampling the forward
transformation on a regular grid, and then fitting a polynomial function
from the resulting output values to the grid of input values.

\end{enumerate}

\subsection{Changes Introduced in V5.7-1}

The following describes the most significant changes which
occurred in the AST library between versions V5.7-0 and V5.7-1:

\begin{enumerate}

\item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified
text files, without the need to provide source and sink functions when
the Channel is created. The files to use are specified by the new
attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}.

\item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS
keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header.

\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the
-SIP (Spitzer) distortion code within the CTYPE values, but which does
not provide an inverse polynomial correction, the FitsChan class will now
use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the
inverse polynomial correction.

\end{enumerate}


\subsection{Changes Introduced in V5.7-2}

The following describes the most significant changes which
occurred in the AST library between versions V5.7-1 and V5.7-2:

\begin{enumerate}

\item The \htmlref{Object}{Object} class has a new function \htmlref{astToString}{astToString} (C only), which creates
an in-memory textual serialisation of a given AST Object. A corresponding
new function called \htmlref{astFromString}{astFromString} re-creates the Object from its
serialisation.

\item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to
evaluate the inverse the inverse transformation if no inverse
transformation is defined when the PolyMap is created.

\item The \htmlref{FitsChan}{FitsChan} class has a new method
\htmlref{astWriteFits}{astWriteFits}
which writes out all cards currently in the FitsChan to the associated
external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the
sink function supplied when the FitsChan was created), and then empties
the FitsChan.

\item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which
holds the number of keywords for which values are held in a FitsChan.

\item The FitsChan
astGetFits<X>
methods can now be used to returned the value of the current card.

\item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which
holds the data type of the keyword value for the current card.

\item The FitsChan class has a new method
\htmlref{astReadFits}{astReadFits}
which forces the FitsChan to reads cards from the associated external
source and appends them to the end of the FitsChan.

\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the
-SIP (Spitzer) distortion code within the CTYPE values, but which does
not provide an inverse polynomial correction, and for which the PolyTran
method of the PolyMap class fails to create an accurate estimate of the
inverse polynomial correction, then an iterative method will be used to
evaluate the inverse correction for each point transformed.

\end{enumerate}

\subsection{Changes Introduced in V6.0}

The following describes the most significant changes which
occurred in the AST library between versions V5.7-2 and V6.0:

\begin{enumerate}

\item This version of AST is the first that can be used with the Python
AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}.

\item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the
non-standard ``TPV'' projection code within a CTYPE keyword value. This
code is used by SCAMP (see www.astromatic.net/software/scamp) to
represent a distorted TAN projection.

\item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as
incorrectly rotated numerical axis labels) if the graphics coordinates have
unequal scales on the X and Y axes.

- The graphics escape sequences used to produce graphical sky axis labels
can now be changed using the new
function \htmlref{astTuneC}{astTuneC}.

\end{enumerate}

\subsection{Changes Introduced in V6.0-1}

The following describes the most significant changes which
occurred in the AST library between versions V6.0 and V6.0-1:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion
code within FITS headers that describe non-celestial axes, as well as
celestial axes.

\item A bug has been fixed that could cause inappropriate equinox values to
be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set.

\item The versioning string for AST has changed from
``$<major>.<minor>-<release>$'' to ``$<major>.<minor>.<release>$''.

\end{enumerate}

\subsection{Changes Introduced in V7.0.0}

The following describes the most significant changes which
occurred in the AST library between versions V6.0-1 and V7.0.0:

\begin{enumerate}

\item Fundamental positional astronomy calculations are now performed
using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{}
otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB
library re-written in C). Copies of these libraries are bundled with AST
and so do not need to be obtained or built separately, although external
copies of SOFA and PAL can be used if necessary by including the
``\texttt{--with-external\_pal}'' option when configuring AST.

\end{enumerate}

\subsection{Changes Introduced in V7.0.1}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.0 and V7.0.1:

\begin{enumerate}

\item The levmar and wcslib code distributed within AST is now stored in the
main AST library (libast.so) rather than in separate libraries.

\end{enumerate}

\subsection{Changes Introduced in V7.0.2}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.1 and V7.0.2:

\begin{enumerate}

\item The libast\_pal library is no longer built if the
``--with-external\_pal'' option is used when AST is configured.

\end{enumerate}

\subsection{Changes Introduced in V7.0.3}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.2 and V7.0.3:

\begin{enumerate}

\item A bug has been fixed which could cause an incorrect axis to be used when
accessing axis attributes within CmpFrames. This could happen if axes
within the \htmlref{CmpFrame}{CmpFrame} have been permuted.

\item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two
values of the SkyRef and/or SkyRefP attributes to be reversed.

\item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border
around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately.
Previously, component Regions nested deeply inside a CmpRegion may have
been completely or partially ignored.

\item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation
violation if the MinTick attribute was set to zero.

\item The astResampleX set of methods now includes astResampleK and
astResampleUK that handles 64 bit integer data.

\end{enumerate}


\subsection{Changes Introduced in V7.0.4}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.3 and V7.0.4:


\begin{enumerate}

\item The previously private grf3d.h header file is now installed into
prefix/include.

\end{enumerate}


\subsection{Changes Introduced in V7.0.5}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.4 and V7.0.5:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO
convention for representing distorted TAN projections, based on the use
of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial.

\end{enumerate}


\subsection{Changes Introduced in V7.0.6}

The following describes the most significant changes which
occurred in the AST library between versions V7.0.5 and V7.0.6:

\begin{enumerate}

\item A bug has been fixed in astRebinSeq<X> which could result in
incorrect normalisation of the final binned data and variance values.

\item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1
and CNPIX2 now default to zero if absent. Previously an error was reported.

\end{enumerate}


\subsection{Changes Introduced in V7.1.0}

The following describes the most significant changes which occurred in the
AST library between versions V7.0.6 and V7.1.0:

\begin{enumerate}

\item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve
flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied
when calling
astRebinSeq<X>.
Without this flag, each output value is a weighted mean of the neighbouring
input values.

\item A new flag AST\_\_NONORM can be used with astRebinSeq<X> to indicate that
normalisation of the output arrays is not required. In this case no
weights array need be supplied.

\item A bug has been fixed in
\htmlref{astAddFrame}{astAddFrame} method
that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet}
when the AST\_\_ALLFRAMES flag is supplied for the
"iframe" parameter.

\item The
\htmlref{astRate}{astRate} method
has been re-written to make it faster and more reliable.

\end{enumerate}

\subsection{Changes Introduced in V7.1.1}

The following describes the most significant changes which
occurred in the AST library between versions V7.1.0 and V7.1.1:

\begin{enumerate}

\item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute
\htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions
are now created - one for the offset coordinates and one for the absolute
coordinates. If such a header is subsequently read back into AST, the
original offset SkyFrame is recreated.

\item A bug has been fixed in FitsChan that caused inappropriate CTYPE values
to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the
current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a
SkyFrame with \htmlref{System}{System}=Unknown).

\end{enumerate}

\subsection{Changes Introduced in V7.2.0}

The following describes the most significant changes which
occurred in the AST library between versions V7.1.1 and V7.2.0:

\begin{enumerate}

\item A new method call
\htmlref{astMapDefined}{astMapDefined}
has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has
a defined value in a given KeyMap.

\end{enumerate}

\subsection{Changes Introduced in V7.3.0}

The following describes the most significant changes which
occurred in the AST library between versions V7.2.0 and V7.3.0:

\begin{enumerate}

\item The interface for the astRebinSeq<X> family of functions has
been changed in order to allow a greater number of pixels to be pasted
into the output array. The "nused" parameter is now a pointer to a
"int64\_t" variable, instead of an "int". APPLICATION CODE SHOULD BE
CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC
BEHAVIOUR.

\item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be
associated with multiple Mappings, any one of which can be used to
connect the Frame to the other Frames in the FrameSet. The choice of
which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the
FrameSet class.

\item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident}
attribute are now left unchanged by the
c \htmlref{astSimplify}{astSimplify} function.
f AST\_SIMPLIFY routine.

\end{enumerate}

\subsection{Changes Introduced in V7.3.1}

The following describes the most significant changes which
occurred in the AST library between versions V7.3.0 and V7.3.1:

\begin{enumerate}

\item Fix a bug that could cauise a segmentation violation when reading
certain FITS headers that use a TNX projection.

\end{enumerate}

\subsection{Changes Introduced in V7.3.2}

The following describes the most significant changes which
occurred in the AST library between versions V7.3.1 and V7.3.2:

\begin{enumerate}

\item Fix support for reading FITS header that use a GLS projection.
Previously, an incorrect transformation was used for such projections if
any CRVAL or CROTA value was non-zero.

\item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and
``KeyAgeDown'' that retain the position of an existing entry if its value
is changed. See the \htmlref{SortBy}{SortBy} attribute.

\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords
for sky axes to be treated as radians rather than degrees when reading a
FITS header, if the corresponding CTYPE values included no projection code.

\end{enumerate}

\subsection{Changes Introduced in V7.3.3}

The following describes the most significant changes which
occurred in the AST library between versions V7.3.2 and V7.3.3:

\begin{enumerate}

\item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold
the keyword name and comment of the current card.

\item When using the FitsChan class to read FITS-WCS headers that include
polynomial distortion in the SIP format, any inverse transformation specified
in the header is now ignored and a new inverse is created to replace it based
on the supplied forward transformation. Previously, an inverse was created
only if the header did not include an inverse. The accuracy of the inverse
transformation has also been improved, although it may now be slower to
evaluate in some circumstances.

\end{enumerate}

\subsection{Changes Introduced in V7.3.4}

The following describes the most significant changes which
occurred in the AST library between versions V7.3.3 and V7.3.4:

\begin{enumerate}

\item By default, the simplification of Polygons no longer checks that the
edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices},
can be set to zero in order to re-instate this check.

\item The \htmlref{Polygon}{Polygon} class has a new mathod,
astConvex,
that returns a Polygon representing the shortest polygon (i.e. convex
hull) enclosing a specified set of pixel values within a supplied array.

\end{enumerate}

\subsection{Changes Introduced in V8.0.0}

The following describes the most significant changes which
occurred in the AST library between versions V7.3.4 and V8.0.0:

\begin{enumerate}

\item AST is now distributed under the Lesser GPL licence.

\item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack
package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform
least squares fitting of N-dimensional polynomials.

\item Use of the IAU SOFA library has been replaced by ERFA library, which is
a re-badged copy of SOFA distributed under a less restrictive license. A
copy of ERFA is included within AST.

\end{enumerate}

\subsection{Changes Introduced in V8.0.1}

The following describes the most significant changes which
occurred in the AST library between versions V8.0.0 and V8.0.1:

\begin{enumerate}

\item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the
  \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}.
\item The order of WCS axes within new FITS-WCS headers created by \htmlref{astWrite}{astWrite}
  can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}.
\item Supported added for FITS XPH (polar HEALPIX) projection.
\item The macro used to invoke the \htmlref{astAppendString}{astAppendString} utility function has
  changed to allow printf-style converstions to be included in the
  supplied text. Any code that uses this macro must be re-compiled.
\item The astRebin and astRebinSeq family of functions now include support
  for arrays with char (byte) and unsigned char (unsigned byte) data types.

\end{enumerate}

\subsection{Changes Introduced in V8.0.2}
The following describes the most significant changes which
occurred in the AST library between versions V8.0.1 and V8.0.2:

\begin{enumerate}
\item For security reasons, the change introduced to \htmlref{astAppendString}{astAppendString} in
  V8.0.1 has been moved to a new function called \htmlref{astAppendStringf}{astAppendStringf}, and
  astAppendString itself has been reverted to its V8.0.0 version.
  Any software that has been built against V8.0.1 will need to be
  re-compiled and re-linked against V8.0.2.
\end{enumerate}


\subsection{Changes Introduced in V8.0.3}
The following describes the most significant changes which
occurred in the AST library between versions V8.0.2 and V8.0.3:

\begin{enumerate}

\item Methods
astRebin, astRebinSeq, astResample and \htmlref{astTranGrid}{astTranGrid}
now report an error if an array is specified that has more pixels than
can be counted by a 32 bit integer.
\item The hypertext documentation is now generated using Tex4HT rather
than latex2html. The format of the hypertext docs has changed significantly.
\item Another bug fix associated with reading CAR projections from
FITS-WCS headers.
\item Constructor options strings of the form ``\texttt{..., "\%s", text );}''
can now be supplied. This avoids a security issue associated with the
alternative form ``\texttt{..., text );}''.
\end{enumerate}

\subsection{Changes Introduced in V8.0.4}
The following describes the most significant changes which
occurred in the AST library between versions V8.0.3 and V8.0.4:

\begin{enumerate}

\item The behaviour of the
\htmlref{astAddFrame}{astAddFrame} method has been changed slightly. Previously, astAddFrame
modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and
\htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes
to the current Frame of the modified FrameSet also affected the supplied
Frame object. Now, deep copies of the Mapping and Frame objects (rather
than references) are stored within the modified FrameSet. This means that
subsequent changes to the modified FrameSet will now have no effect on
the supplied Frame.

\item The choice of default tick-mark gaps for time axes has been
improved, to avoid a previous issue which could result in no suitable gap
being found.

- A new method called
\htmlref{astRegionOutline}{astRegionOutline}
has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST
\htmlref{Region}{Region}.

\item A bug has been fixed that could cause astSimplfy to enter an infinite loop.

\item Some improvements have been made to the Mapping simplification process
that allow more Mappings to be simplified.

\item The Frame class has a new read-only attribute called InternalUnit,
which gives the units used for the unformatted (i.e. floating-point) axis
values used internally by application code. For most Frames, the
InternalUnit value is just the same as the Unit value (i.e. formatted and
unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class
always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of
Unit, indicating that floating-point SkyFrame axis values are always in units
of radians.

\item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies
the relative error of the values in the table. It is used to decide if
the LutMap can be simplified to a straight line.

\end{enumerate}


\subsection{Changes Introduced in V8.0.5}
The following describes the most significant changes which
occurred in the AST library between versions V8.0.4 and V8.0.5:

\begin{enumerate}

\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies
the smallest significant distance within the SkyFrame. It is used to
decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit
transformation. The default value is 0.001 arc-seconds.

\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal
characters within FITS keyword names (i.e. characters not allowed by the
FITS standard) being detected. This bug could under some circumstances
cause a subsequent segmentation violation to occur.

\item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS
keyword name is encountered that contains any illegal characters. See
attribute ``\htmlref{Warnings}{Warnings}'' and
function ``\htmlref{astWarnings}{astWarnings}''.

\end{enumerate}

\subsection{Changes Introduced in V8.1.0}
The following describes the most significant changes which
occurred in the AST library between versions V8.0.5 and V8.1.0:

\begin{enumerate}

\item The configure script has a new option ``--without-fortran'' that allows
AST to be built in situations where no Fortran compiler is available. The
resulting library has no Fortran interface and so cannot be used within
Fortran applications. Also, the link scripts do not attempt to include the
fortran runtime libraries.

\end{enumerate}

\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
Introduced in V8.2}
The following describes the most significant changes which
occurred in the AST library between versions V8.1.0 and V8.2.0:

\begin{enumerate}

\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts
a vector to a unit vector relative to a specified centre, plus length. A
UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates
represent a unit vector parallel to the supplied input vector, and the
(N+1)'th output coordinate is the length of the input vector.

\item The restriction that Mappings are immutable has been extended to all
Mapping classes. This means that attributes representing parameters of
a Mapping's forward or inverse transformation cannot be changed after
the Mapping has been created. In order to minimise the risk to existing
software, this rule does not apply to Mappings that have not yet been
included in other objects such as CmpMaps or FrameSets, or which have not
yet been cloned. In other words, an error is reported if an attempt is
made to change the nature of a Mapping's transformation, but only if the
reference count of the Mapping is greater than one. The Mapping classes
affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}.

\end{enumerate}


\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
Introduced in V8.3}
The following describes the most significant changes which have
occurred in the AST library between versions V8.2.0 and V8.3.0 (the
current version):

\begin{enumerate}

\item A new method called \htmlref{astAxNorm}{astAxNorm}
has been added to the \htmlref{Frame}{Frame} class that normalises an array of axis
values. When used with SkyFrames, it allows longitude values to be
normalised into the shortest range.


\item A bug has been fixed in the \htmlref{astGetRegionBounds}{astGetRegionBounds} method that could
cause the wrong bounds to be returned for regions spanning a longitude =
zero singularity.

\end{enumerate}


% Programs which are statically linked will need to be re-linked in
% order to take advantage of these new facilities.

\end{document}