summaryrefslogtreecommitdiffstats
path: root/ast/sun210.tex
diff options
context:
space:
mode:
Diffstat (limited to 'ast/sun210.tex')
-rw-r--r--ast/sun210.tex53644
1 files changed, 53644 insertions, 0 deletions
diff --git a/ast/sun210.tex b/ast/sun210.tex
new file mode 100644
index 0000000..a4c48f7
--- /dev/null
+++ b/ast/sun210.tex
@@ -0,0 +1,53644 @@
+\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 {210.28}
+\stardocauthors {R.F. Warren-Smith \& D.S. Berry}
+\stardocdate {6th December 2018}
+\stardoctitle {AST\linebreak%
+ A Library for Handling\linebreak%
+ World Coordinate Systems\linebreak%
+ in Astronomy}
+\stardoccopyright {Copyright (C) 2017 East Asian Observatory}
+\stardocversion {V8.7}
+\stardocmanual {Programmer's Guide\\(Fortran Version)}
+\startitlepic{
+ \includegraphics[width=0.25\textwidth]{sun210_figures/fronta}~~~~~\hfill
+ \includegraphics[width=0.25\textwidth]{sun210_figures/frontb}~~~~~\hfill
+ \includegraphics[width=0.25\textwidth]{sun210_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 Fortran version of this document.\\
+ For the C version, please see \xref{SUN/211}{sun211}{}.}
+\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 Fortran and C interfaces are available (see
+\xref{SUN/211}{sun211}{} for the C 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
+Fortran and C.
+
+\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]{sun210_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} and
+\htmlref{ChebyMap}{ChebyMap}).
+
+\item Lookup tables (the \htmlref{LutMap}{LutMap}).
+
+\item General-purpose transformations expressed using arithmetic
+operations and functions similar to those available in Fortran (the
+\htmlref{MathMap}{MathMap}).
+
+\item Transformations for internal use within a program, based on
+private transformation routines which you write yourself in Fortran
+(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]{sun210_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]{sun210_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]{sun210_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]{sun210_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. Routines 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]{sun210_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]{sun210_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]{sun210_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 subroutine 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:
+
+\small
+\begin{terminalv}
+* Include the interface to the AST library.
+ INCLUDE 'AST_PAR'
+
+* Declare an integer status variable.
+ INTEGER STATUS
+ <maybe other declarations>
+
+* Initialise the status to zero.
+ STATUS = 0
+ <maybe some Fortran statements>
+
+* Enclose the parts which use AST between AST_BEGIN and AST_END calls.
+ CALL AST_BEGIN( STATUS )
+ <Fortran statements which use AST>
+ CALL AST_END( STATUS )
+
+ <maybe more Fortran statements>
+ END
+\end{terminalv}
+\normalsize
+
+The use of \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END} 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\_PAR include 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}
+f77 program.f -L/star/lib -I/star/include `ast_link` -o program
+\end{terminalv}
+\end{small}
+
+On Linux systems you should usually use \verb+g77 -fno-second-underscore+ in
+place of \verb+f77+ - see \xref{``Software development on Linux''}{sun212}
+{software_development_on_linux} in \xref{SUN/212}{sun212}{}.
+
+To build a program which uses PGPLOT for graphics, use:
+
+\begin{small}
+\begin{terminalv}
+f77 program.f -L/star/lib `ast_link -pgplot` -o program
+\end{terminalv}
+\end{small}
+
+again using \verb+g77 -fno-second-underscore+ in place of \verb+f77+
+on Linux systems.
+
+For more details about accessing AST include files, 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 an array of character strings
+containing a complete set of FITS header cards and NCARD is the number
+of cards. Then proceed as follows:
+
+\small
+\begin{terminalv}
+ INTEGER FITSCHAN, ICARD, NCARD, WCSINFO
+ CHARACTER * ( 80 ) CARDS( NCARD )
+
+ ...
+
+* Create a FitsChan and fill it with FITS header cards.
+ FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
+ DO 1 ICARD = 1, NCARD
+ CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS )
+ 1 CONTINUE
+
+* Rewind the FitsChan and read WCS information from it.
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+ WCSINFO = AST_READ( FITSCHAN, STATUS )
+\end{terminalv}
+\normalsize
+
+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 routine
+\xref{NDF\_GTWCS}{sun33}{NDF_GTWCS}---see \xref{SUN/33}{sun33}{}. The
+whole process can probably be encapsulated in a similar way for most
+other 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:
+
+\small
+\begin{terminalv}
+ IF ( STATUS .NE. 0 ) THEN
+ <an error occurred (a message will have been issued)>
+ ELSE IF ( WCSINFO .EQ. AST__NULL ) THEN
+ <there was no WCS information present>
+ ELSE IF ( AST_GETC( WCSINFO, 'Class', STATUS ) .NE. 'FrameSet' ) THEN
+ <something unexpected was read (i.e. not a FrameSet)>
+ ELSE
+ <WCS information was read OK>
+ END IF
+\end{terminalv}
+\normalsize
+
+For more information about detecting errors in AST routines, 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}
+ CALL AST_SHOW( WCSINFO, STATUS )
+\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{AST\_SHOW}{AST\_SHOW}, 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:
+
+\small
+\begin{terminalv}
+ INTEGER N
+ DOUBLE PRECISION XPIXEL( N ), YPIXEL( N )
+ DOUBLE PRECISION XWORLD( N ), YWORLD( N )
+
+ ...
+
+ CALL AST_TRAN2( WCSINFO, N, XPIXEL, YPIXEL, .TRUE.,
+ : XWORLD, YWORLD, STATUS )
+\end{terminalv}
+\normalsize
+
+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{AST\_TRAN2}{AST\_TRAN2} to .FALSE..
+
+To transform points in one dimension, use \htmlref{AST\_TRAN1}{AST\_TRAN1}. In any other
+number of dimensions (or if the number of dimensions is initially
+unknown), use \htmlref{AST\_TRANN}{AST\_TRANN}. These routines 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}
+ INTEGER FRAME
+ LOGICAL ISSKY
+
+ ...
+
+* Obtain a pointer to the current Frame and determine if it is a
+* SkyFrame.
+ FRAME = AST_GETFRAME( WCSINFO, AST__CURRENT, STATUS )
+ ISSKY = AST_ISASKYFRAME( FRAME, STATUS )
+ CALL AST_ANNUL( FRAME, STATUS )
+\end{terminalv}
+\end{small}
+
+This will set ISSKY to .TRUE.\ if the WCS is a celestial coordinate
+system, and to .FALSE.\ 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
+AST\_ISASPECFRAME routine
+in place of the
+AST\_ISASKYFRAME routine.
+
+\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}
+ CHARACTER * ( 20 ) XTEXT, YTEXT
+ DOUBLE PRECISION XW, YW
+
+ ...
+
+ XTEXT = AST_FORMAT( WCSINFO, 1, XW, STATUS )
+ YTEXT = AST_FORMAT( WCSINFO, 2, YW, STATUS )
+
+ WRITE ( *, 199 ) XTEXT, YTEXT
+ 199 FORMAT( 'Position = ', A, ', ', A )
+\end{terminalv}
+\end{small}
+
+Here, the second argument to \htmlref{AST\_FORMAT}{AST\_FORMAT} 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}
+ CALL AST_SET( WCSINFO, 'Report=1', STATUS )
+ CALL AST_TRAN2( WCSINFO, N, XPIXEL, YPIXEL, .TRUE.,
+ : XWORLD, YWORLD, STATUS )
+\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}
+ CHARACTER TEXT * ( 80 )
+ DOUBLE PRECISION COORD( 10 )
+ INTEGER IAXIS, N, NAXES, T
+
+ ...
+
+* Obtain the number of coordinate axes (if not already known).
+ NAXES = AST_GETI( WCSINFO, 'Naxes', STATUS )
+
+* Loop to read each line of input text, in this case from the
+* standard input channel (your programming environment will probably
+* provide a better way of reading text than this). Set the index T to
+* the start of each line read.
+ 2 CONTINUE
+ READ( *, '(A)', END=99 ) TEXT
+ T = 1
+
+* Attempt to read a coordinate for each axis.
+ DO 3 IAXIS = 1, NAXES
+ N = AST_UNFORMAT( WCSINFO, IAXIS, TEXT( T : ), COORD( IAXIS ),
+ : STATUS )
+
+* If nothing was read and this is not the first axis and the end of
+* the text has not been reached, try stepping over a separator and
+* reading again.
+ IF ( ( N .EQ. 0 ) .AND. ( IAXIS .GT. 1 ) .AND.
+ : ( T .LT. LEN( STRING ) ) ) THEN
+ T = T + 1
+ N = AST_UNFORMAT( WCSINFO, IAXIS, TEXT( T : ),
+ COORD( IAXIS ), STATUS )
+ END IF
+
+* Quit if nothing was read, otherwise move on to the next coordinate.
+ IF ( N .EQ. 0 ) GO TO 4
+ T = T + N
+ 3 CONTINUE
+ 4 CONTINUE
+
+* Test for the possible errors that may occur...
+
+* Error detected by AST (a message will have been issued).
+ IF ( STATUS .NE. 0 ) THEN
+ GO TO 99
+
+* Error in input data at character TEXT( T + N : T + N ).
+ ELSE IF ( ( T .LT. LEN( STRING ) ) .OR. ( N .EQ. 0 ) ) THEN
+ <handle the error, or report your own message here>
+ GO TO 99
+
+ ELSE
+ <coordinates were read OK>
+ END IF
+
+* Return to read the next input line.
+ GO TO 2
+ 99 CONTINUE
+\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{AST\_UNFORMAT}{AST\_UNFORMAT} function, see \secref{ss:unformattingaxisvalues}. For
+details of how sexagesimal formats are handled, and the forms of input
+that may be used for 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 PRECISION XNEW, XOLD, YNEW, YOLD
+ DOUBLE PRECISION M( 4 ), Z( 2 )
+
+ ...
+
+ XNEW = XOLD * M( 1 ) + YOLD * M( 2 ) + Z( 1 )
+ YNEW = XOLD * M( 3 ) + YOLD * M( 4 ) + Z( 2 )
+\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}
+ DOUBLE PRECISION INA( 2 ), INB( 2 ), OUTA( 2 ), OUTB( 2 )
+ INTEGER MATRIXMAP, WINMAP
+
+ ...
+
+* Set up the corners of a unit square.
+ DATA INA / 2 * 0.0D0 /
+ DATA INB / 2 * 1.0D0 /
+
+* The MatrixMap may be constructed directly from the matrix M.
+ MATRIXMAP = AST_MATRIXMAP( 2, 2, 0, M, ' ', STATUS )
+
+* For the WinMap, we take the coordinates of the corners of a unit
+* square (window) and then shift them by the required amounts.
+ OUTA( 1 ) = INA( 1 ) + Z( 1 )
+ OUTA( 2 ) = INA( 2 ) + Z( 2 )
+ OUTB( 1 ) = INB( 1 ) + Z( 1 )
+ OUTB( 2 ) = INB( 2 ) + Z( 2 )
+
+* The WinMap will then implement this shift.
+ WINMAP = AST_WINMAP( 2, INA, INB, OUTA, OUTB, ' ', STATUS )
+
+* Join the two Mappings together, so that they are applied one after
+* the other.
+ NEWMAP = AST_CMPMAP( MATRIXMAP, WINMAP, 1, ' ', STATUS )
+\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}
+ INTEGER WCSINFO1, WCSINFO2
+
+ ...
+
+* If necessary, make a copy of the WCS calibration, since we are
+* about to alter it.
+ WCSINFO2 = AST_COPY( WCSINFO1, STATUS )
+
+* Re-map the base Frame so that it refers to the new data grid
+* instead of the old one.
+ CALL AST_REMAPFRAME( WCSINFO2, AST__BASE, NEWMAP, STATUS )
+\end{terminalv}
+\end{small}
+
+This will produce a pointer, WCSINFO2, to a new FrameSet in which all
+the coordinate systems associated with the original image are modified
+so that they are correctly registered with your 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}
+ INTEGER FITSCHAN1, WCSINFO1
+ CHARACTER * ( 20 ) 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 AST_PUTCARDS in
+* place of AST_PUTFITS.
+ FITSCHAN1 = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
+ DO 1 ICARD = 1, NCARD
+ CALL AST_PUTFITS( FITSCHAN1, CARDS( ICARD ), .FALSE., STATUS )
+ 1 CONTINUE
+
+* Note which encoding has been used for the WCS information.
+ ENCODE = AST_GETC( FITSCHAN1, 'Encoding', STATUS );
+
+* Rewind the input FitsChan and read the WCS information from it.
+ CALL AST_CLEAR( FITSCHAN1, 'Card', STATUS )
+ WCSINFO1 = AST_READ( FITSCHAN1, STATUS )
+\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 the resulting string in
+the ENCODE variable. This must be done \textbf{before} actually reading
+the WCS calibration.
+
+
+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}
+ INTEGER FITSCHAN2, JUNK, 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 WCS calibration.
+ FITSCHAN2 = AST_COPY( FITSCHAN1, STATUS )
+
+* 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 = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
+
+* 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.
+ CALL AST_SET( FITSCHAN2, 'Card=1, Encoding=' // ENCODE, STATUS )
+ IF ( AST_WRITE( FITSCHAN2, WCSINFO2, STATUS ) .EQ. 0 ) THEN
+
+* If this didn't work (the WCS FrameSet has become too complex), then
+* use the native AST encoding instead.
+ CALL AST_SETC( FITSCHAN2, 'Encoding', 'NATIVE', STATUS );
+ JUNK = AST_WRITE( FITSCHAN2, WCSINFO2, STATUS );
+ END IF
+\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}
+ CHARACTER * ( 80 ) CARD
+
+ ...
+
+ CALL AST_CLEAR( FITSCHAN2, 'Card', STATUS )
+ 5 CONTINUE
+ IF ( AST_FINDFITS( FITSCHAN2, '%f', CARD, .TRUE., STATUS ) ) THEN
+ WRITE ( *, '(A)' ) CARD
+ GO TO 5
+ END IF
+\end{terminalv}
+\normalsize
+
+Here, we have simply written each card to the standard output unit,
+but you would obviously replace this with a subroutine call 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 routine
+\xref{NDF\_PTWCS}{sun33}{NDF_PTWCS}---see \xref{SUN/33}{sun33}{}. The
+whole process can probably be encapsulated in a similar way for most
+other 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 \htmlref{Encoding}{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]{sun210_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 routines 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 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}
+ DOUBLE PRECISION BBOX( 4 )
+ INTEGER NX, NY, PGBEG, PLOT
+ REAL DATA( NX, NY ), GBOX( 4 ), HI, LO, SCALE, TR( 6 )
+ REAL X1, X2, XLEFT, XRIGHT, Y1, Y2, YBOTTOM, YTOP
+
+ ...
+
+* Access the image data, which we assume will be stored in the real
+* 2-dimensional array DATA with dimension sizes NX and NY. 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 ( PGBEG( 0, ' ', 1, 1 ) .EQ. 1 ) THEN
+
+* Clear the screen and ensure equal scales on both axes.
+ CALL PGPAGE
+ CALL PGWNAD( 0.0, 1.0, 0.0, 1.0 )
+
+* 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.
+ CALL PGQWIN( X1, X2, Y1, Y2 )
+ SCALE = MIN( ( X2 - X1 ) / NX, ( Y2 - Y1 ) / NY )
+
+* 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.5 * ( X1 + X2 - NX * SCALE )
+ XRIGHT = 0.5 * ( X1 + X2 + NX * SCALE )
+ YBOTTOM = 0.5 * ( Y1 + Y2 - NY * SCALE )
+ YTOP = 0.5 * ( 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).
+ TR( 1 ) = XLEFT - 0.5 * SCALE
+ TR( 2 ) = SCALE
+ TR( 3 ) = 0.0
+ TR( 4 ) = YBOTTOM - 0.5 * SCALE
+ TR( 5 ) = 0.0
+ TR( 6 ) = SCALE
+ CALL PGGRAY( 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.
+ GBOX( 1 ) = XLEFT
+ GBOX( 2 ) = YBOTTOM
+ GBOX( 3 ) = XRIGHT
+ GBOX( 4 ) = 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).
+ BBOX( 1 ) = 0.5D0
+ BBOX( 2 ) = 0.5D0
+ BBOX( 3 ) = NX + 0.5D0
+ BBOX( 4 ) = NY + 0.5D0
+
+* 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 = AST_PLOT( WCSINFO, GBOX, BBOX, 'Grid=1', STATUS )
+
+* 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.
+ CALL AST_SET( PLOT, 'Colour(grid)=2, Font(textlab)=3', STATUS )
+
+* Use the Plot to draw the coordinate grid.
+ CALL AST_GRID( PLOT, STATUS )
+
+ <maybe some more AST graphics here>
+
+* Annul the Plot when finished (or use the AST_BEGIN/AST_END
+* technique shown earlier).
+ CALL AST_ANNUL( PLOT, STATUS )
+
+* END OF AST BIT
+* ==============
+
+* Close down the graphics system.
+ CALL PGEND
+ END IF
+\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{AST\_PLOT}{AST\_PLOT}, you could use:
+
+\small
+\begin{terminalv}
+ CALL AST_SET( PLOT, 'System=Galactic', STATUS )
+\end{terminalv}
+\normalsize
+or:
+\small
+\begin{terminalv}
+ CALL AST_SET( PLOT, 'System=FK5, Equinox=J2010', STATUS )
+\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}
+ CHARACTER LINE( 120 )
+ INTEGER BASE
+
+ ...
+
+* Create a Plot and define the default appearance of the graphical
+* output it will produce.
+ PLOT = AST_PLOT( WCSINFO, GBOX, PBOX,
+ : 'Grid=1, Colour(grid)=2, Font(textlab)=3',
+ : STATUS )
+
+* Obtain the value of any Plot attributes we want to preserve.
+ BASE = AST_GETI( PLOT, 'Base', STATUS )
+
+* Open the plot configuration file, if it exists.
+ OPEN ( 1, FILE = 'plot.config', STATUS = 'OLD', ERR = 8 )
+
+* Read each line of text and use it to set new Plot attribute
+* values. Close the file when done.
+ 6 CONTINUE
+ READ ( 1, '(A)', END = 7 ) LINE
+ CALL AST_SET( PLOT, LINE, STATUS )
+ GO TO 6
+ 7 CLOSE ( 1 )
+ 8 CONTINUE
+
+* Restore any attribute values we are preserving.
+ CALL AST_SETI( PLOT, 'Base', BASE, STATUS )
+
+* Produce the graphical output (e.g.).
+ CALL AST_GRID( PLOT, STATUS )
+\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 Fortran and C 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 Fortran 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_PAR'
+ INTEGER STATUS, ZOOMMAP
+
+ STATUS = 0
+
+ ...
+
+ ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+The first step is to include the file AST\_PAR which defines the
+interface to the AST library and, amongst other things, declares
+\htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} to be an integer function. We then declare an integer
+variable ZOOMMAP to receive the result and an integer STATUS variable
+to hold the error status, which we initialise to zero. Next, we invoke
+AST\_ZOOMMAP 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.
+
+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.0D0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a
+Fortran double precision value. We will return to the final two
+arguments, a blank string and the error status, shortly
+(\secref{ss:attributeinitialisation} and \secref{ss:errordetection}).
+
+The integer value returned by the constructor is termed an \emph{Object
+pointer} or, in this case, a \emph{ZoomMap pointer}. This pointer is not
+an Object itself, but is a value used to refer to the Object. You
+should be careful not to modify any Object pointer yourself, as this
+may render it invalid. Instead, you perform all subsequent operations
+on the Object by passing this pointer to other AST routines.
+
+\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 routine for doing this, called \htmlref{AST\_SHOW}{AST\_SHOW}, which is provided
+mainly for looking at Objects while you are debugging programs.
+
+If you consult the description of AST\_SHOW in
+\appref{ss:functiondescriptions}, you will find that it takes a
+pointer to an \htmlref{Object}{Object} as its argument (in addition to the usual STATUS
+argument). Although we have only a ZoomMap pointer available,
+fortunately 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 AST\_SHOW, as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_SHOW( ZOOMMAP, STATUS )
+\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}
+ INTEGER NIN
+
+ ...
+
+ NIN = AST_GETI( ZOOMMAP, 'Nin', STATUS )
+\end{terminalv}
+\normalsize
+
+Here, the integer function AST\_GETI 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\_PAR include file to save having to declare AST\_GETI
+as integer yourself.
+
+If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably
+have used AST\_GETD instead, this being a double precision version of
+the same function, for example:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION ZOOM
+
+ ...
+
+ ZOOM = AST_GETD( ZOOMMAP, 'Zoom', STATUS )
+\end{terminalv}
+\normalsize
+
+However, we could equally well have read the Nin value as double
+precision, 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 AST\_GETx function name with C~(character),
+D~(double precision), I~(integer), L~(logical) or R~(real). If
+possible, the value is converted to the type you want. If not, an
+error message will result. In converting from integer to logical, zero
+is regarded as .FALSE.\ and non-zero as .TRUE.. Note that all floating
+point values are stored internally as double precision. Boolean values
+are 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}
+ CALL AST_SETD( ZOOMMAP, 'Zoom', 99.6D0, STATUS )
+\end{terminalv}
+\normalsize
+
+which sets the value to 99.6 (double precision). 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}
+ CALL AST_SETI( ZOOMMAP, 'Zoom', 99, STATUS )
+\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
+AST\_SETx routine name with C~(character), D~(double precision),
+I~(integer), L~(logical) or R~(real). 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{AST\_SET}{AST\_SET} routine (\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}
+ CALL AST_SET( ZOOMMAP, 'Zoom=99.6, Report=1', STATUS )
+\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 (although you must use 0/1 instead of
+.TRUE./.FALSE., which are not supported). Note, when using AST\_SET, a
+literal comma may be included in an attribute value by enclosed the value in
+quotation marks:
+\small
+\begin{terminalv}
+ CALL AST_SET( SKYFRAME, 'SkyRef="12:13:32,-23:12:44"', STATUS )
+\end{terminalv}
+\normalsize
+
+\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 penultimate character argument which allows you to do
+this. Although you can simply leave this blank, 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 = AST_ZOOMMAP( 2, 5.0D0, 'Report=1', STATUS )
+\end{terminalv}
+\normalsize
+
+and it would then start life with its Report attribute set to 1.
+
+\subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes}
+
+You can use the AST\_GETx family of routines
+(\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 logical function \htmlref{AST\_TEST}{AST\_TEST},
+as in:
+
+\small
+\begin{terminalv}
+ IF ( AST_TEST( ZOOMMAP, 'Report', STATUS ) ) THEN
+ <the Report attribute is set>
+ END IF
+\end{terminalv}
+\normalsize
+
+(as usual, remember to include the AST\_PAR file to declare the
+function as LOGICAL, or make this declaration yourself).
+
+Once an attribute is set, you can return it to its un-set state using
+\htmlref{AST\_CLEAR}{AST\_CLEAR}. The effect is as if it had never been set in the first
+place. For example:
+
+\small
+\begin{terminalv}
+ CALL AST_CLEAR( ZOOMMAP, 'Report', STATUS )
+\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}
+ CALL AST_SET( ZOOMMAP, 'Report=1', STATUS )
+\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 arrays are
+double precision, as are all coordinate data processed by the AST
+library:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION XIN( 10 ), YIN( 10 ), XOUT( 10 ), YOUT( 10 )
+ DATA XIN / 0D0, 1D0, 2D0, 3D0, 4D0, 5D0, 6D0, 7D0, 8D0, 9D0 /
+ DATA YIN / 0D0, 2D0, 4D0, 6D0, 8D0, 10D0, 12D0, 14D0, 16D0, 18D0 /
+\end{terminalv}
+\normalsize
+
+We will now use the routine \htmlref{AST\_TRAN2}{AST\_TRAN2} to transform the input
+coordinates. This is the most commonly-used (2-dimensional) coordinate
+transformation routine. 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 routines 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 AST\_TRAN2 to transform our coordinates, as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_TRAN2( ZOOMMAP, 10, XIN, YIN, .TRUE., XOUT, YOUT, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, 10 is the number of points we want to transform and the fifth
+argument value of .TRUE.\ 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 AST\_TRAN2 from .TRUE. to .FALSE.. We can
+also feed the output coordinates from the above back into the routine:
+
+\small
+\begin{terminalv}
+ CALL AST_TRAN2( ZOOMMAP, 10, XOUT, YOUT, .FALSE., XIN, YIN, STATUS )
+\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{AST\_ANNUL}{AST\_ANNUL}. For example:
+
+\small
+\begin{terminalv}
+ CALL AST_ANNUL( ZOOMMAP, STATUS )
+\end{terminalv}
+\normalsize
+
+This indicates that you have finished with the pointer and sets it to
+the null value AST\_\_NULL (as defined in the AST\_PAR include file),
+so that any attempt to use it 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 AST\_ANNUL
+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{AST\_ANNUL}{AST\_ANNUL} (\secref{ss:annullingpointers}) is not completely
+foolproof, however. Consider the following:
+
+\small
+\begin{terminalv}
+ CALL AST_SHOW( AST_ZOOMMAP( 2, 5.ODO, ' ', STATUS ), STATUS )
+\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 routines in this way is very convenient because it
+avoids the need for intermediate pointer variables. However, the
+pointer generated by \htmlref{AST\_ZOOMMAP}{AST\_ZOOMMAP} is still active, and since we have
+not stored its value, we cannot use AST\_ANNUL 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
+routines between calls to \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END}, for example:
+
+\small
+\begin{terminalv}
+ CALL AST_BEGIN( STATUS )
+ CALL AST_SHOW( AST_ZOOMMAP( 2, 5.ODO, ' ', STATUS ), STATUS )
+ CALL AST_END( STATUS )
+\end{terminalv}
+\normalsize
+
+When the AST\_END call executes, every \htmlref{Object}{Object} pointer created since
+the previous AST\_BEGIN call 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 AST\_BEGIN
+and AST\_END 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, calls to AST\_BEGIN and AST\_END may be nested, like
+\htmlref{IF}{IF}\ldots ENDIF blocks in Fortran, to define a series of AST pointer
+contexts. Each call to AST\_END will then annul only those Object
+pointers created since the matching call to AST\_BEGIN.
+
+\subsection{Exporting, Importing and Exempting AST Pointers}
+The \htmlref{AST\_EXPORT}{AST\_EXPORT} routine allows you to export particular pointers from
+one AST context (\secref{ss:contexts}) to the next outer one, as
+follows:
+
+\small
+\begin{terminalv}
+ CALL AST_EXPORT( ZOOMMAP, STATUS )
+\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 call to \htmlref{AST\_END}{AST\_END} (but only one such
+call) 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{AST\_BEGIN}{AST\_BEGIN}\ldots AST\_END block is basically to generate an
+\htmlref{Object}{Object} pointer. Without this, there is no way of getting that pointer
+out.
+
+The \htmlref{AST\_IMPORT}{AST\_IMPORT} 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 AST\_END.
+
+
+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 routines 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 AST\_END. To avoid this, you should
+use \htmlref{AST\_EXEMPT}{AST\_EXEMPT} on each pointer that you store, for example:
+
+\small
+\begin{terminalv}
+ CALL AST_EXEMPT( ZOOMMAP, STATUS )
+\end{terminalv}
+\normalsize
+
+This will prevent the pointer being affected by any subsequent use of
+AST\_END. Of course, it then becomes your responsibility to annul this
+pointer (using \htmlref{AST\_ANNUL}{AST\_ANNUL}) when it is no longer required.
+
+
+
+
+\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{AST\_COPY}{AST\_COPY} to make a copy of one, \emph{e.g.}:
+
+\small
+\begin{terminalv}
+ INTEGER ZOOMMAP1, ZOOMMAP2
+
+ ...
+
+ ZOOMMAP2 = AST_COPY( ZOOMMAP1, STATUS )
+\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{\label{ss:errordetection}Error Detection}
+
+If an error occurs in an AST routine (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 that an error has occurred, each AST routine that can
+potentially fail has a final integer \emph{error status} argument
+called STATUS. This is both an input and an output argument.
+Normally, you should declare a single error status variable and pass
+it as the STATUS argument to every AST routine you invoke. This
+variable must initially be cleared (\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. To allow
+for this possibility, you might prefer to use a parameter constant to
+represent the value zero when testing for errors.} to indicate no
+error). If an error occurs, the STATUS argument is returned set to a
+different \emph{error value}, which allows you to detect the error, as
+follows:
+
+\small
+\begin{terminalv}
+ STATUS = 0
+
+ ...
+
+ ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, 'Title=My ZoomMap', STATUS )
+ IF ( STATUS .NE. 0 ) THEN
+ <an error has occurred>
+ END IF
+\end{terminalv}
+\normalsize
+
+In this example, an error would be detected 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.
+
+A consequence of the error status variable STATUS being set to an
+error value is that almost all AST routines will subsequently cease to
+function and will instead simply return without action. This means
+that you do not need to check for errors very frequently. Instead, you
+can usually simply invoke a succession of AST routines. 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}
+ STATUS = 0
+
+ ...
+
+ CALL AST_ROUTINEA( ... , STATUS )
+ CALL AST_ROUTINEB( ... , STATUS )
+ CALL AST_ROUTINEC( ... , STATUS )
+ IF ( STATUS .NE. 0 ) THEN
+ <an error has occurred>
+ END IF
+\end{terminalv}
+\normalsize
+
+There are, however, a few routines which do not adhere to this general
+rule and which will attempt to execute if their STATUS argument is
+initially set. These routines, such as \htmlref{AST\_ANNUL}{AST\_ANNUL}, are concerned with
+cleaning up and recovering resources. For example, in the following:
+
+\small
+\begin{terminalv}
+ STATUS = 0
+
+ ...
+
+ ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS )
+
+ CALL AST_ROUTINEX( ... , STATUS )
+ CALL AST_ROUTINEY( ... , STATUS )
+ CALL AST_ROUTINEZ( ... , STATUS )
+
+ CALL AST_ANNUL( ZOOMMAP, STATUS )
+ IF ( STATUS .NE. 0 ) THEN
+ <an error has occurred>
+ END IF
+\end{terminalv}
+\normalsize
+
+AST\_ANNUL 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 routines.
+Routines 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. This is
+simply done by resetting your error status variable to zero, whereupon
+the AST routines you pass it to will execute normally again.
+
+
+
+
+
+
+
+\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
+ ChebyMap
+ 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 AST\_MAPPING 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{AST\_ZOOMMAP}{AST\_ZOOMMAP} which created it. In this case, the Nout attribute was
+not needed and it implicitly took the same value as Nout, but we could
+have enquired about its value had we wanted, as follows:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER NOUT, STATUS, ZOOMMAP
+
+ STATUS = 0
+
+ ...
+
+ NOUT = AST_GETI( ZOOMMAP, 'Nout', STATUS )
+\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{AST\_INVERT}{AST\_INVERT}, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER MAPPING
+
+ ...
+
+ CALL AST_INVERT( MAPPING, STATUS )
+\end{terminalv}
+\normalsize
+
+If the Mapping you have happens to be the wrong way around,
+AST\_INVERT allows you to correct the problem.
+
+\subsection{Finding the Rate of Change of a Mapping Output}
+The
+\htmlref{AST\_RATE}{AST\_RATE}
+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{AST\_COPY}{AST\_COPY} (\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
+parameter constant AST\_\_BAD (as defined in the AST\_PAR include
+file). Before making use of coordinates generated by any of the AST
+transformation routines, 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 routines are also capable of recognising this value
+and handling it appropriately. The coordinate transformation routines
+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}
+ INTEGER UNITMAP
+
+ ...
+
+ UNITMAP = AST_UNITMAP( 2, ' ', STATUS )
+\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 routine, 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}
+ INTEGER OUTPERM( 4 ), INPERM( 4 )
+ DATA OUTPERM / 4, 1, 2, 3 /
+ DATA INPERM / 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}
+ INTEGER PERMMAP
+ DOUBLE PRECISION DUMMY( 1 )
+
+ ...
+
+ PERMMAP = AST_PERMMAP( 4, INPERM, 4, OUTPERM, DUMMY, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+(the fifth argument is not being used, so a dummy array has been supplied).
+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}
+ INTEGER OUTPERM( 3 ), INPERM( 4 )
+ DOUBLE PRECISION CONST( 1 )
+ DATA OUTPERM / 4, 3, 2 /
+ DATA INPERM / -1, 3, 2, 1 /
+ DATA CONST / 99.004D0 /
+\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 CONST array using an index of 1 (the
+absolute value). 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 = AST_PERMMAP( 4, INPERM, 3, OUTPERM, CONST, ' ', STATUS )
+\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 CONST 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 CONST 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\_PAR include
+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_PAR'
+ INTEGER CMPMAP, PERMMAP, STATUS, ZOOMMAP
+ INTEGER INPERM( 2 ), OUTPERM( 2 ), CONST( 1 )
+ DATA INPERM / 1, 2 /
+ DATA OUTPERM / 1, 2 /
+
+ STATUS = 0
+
+ ...
+
+* Create the individual Mappings.
+ PERMMAP = AST_PERMMAP( 2, INPERM, 2, OUTPERM, CONST, ' ', STATUS )
+ ZOOMMAP = AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS )
+
+* Combine them in series.
+ CMPMAP = AST_CMPMAP( PERMMAP, ZOOMMAP, .TRUE., ' ', STATUS )
+
+* Annul the individual Mapping pointers.
+ CALL AST_ANNUL( PERMMAP, STATUS )
+ CALL AST_ANNUL( ZOOMMAP, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, the third argument (.TRUE.) of the constructor function
+\htmlref{AST\_CMPMAP}{AST\_CMPMAP} 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 = AST_CMPMAP( PERMMAP, ZOOMMAP, .FALSE., ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+The only difference is that the third argument of \htmlref{AST\_CMPMAP}{AST\_CMPMAP} is now
+.FALSE., 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 th 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{AST\_ANNUL}{AST\_ANNUL}, but retained until the CmpMap itself is deleted and annuls
+the pointers it holds. Consistent use of AST\_ANNUL
+(\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{AST\_CMPMAP}{AST\_CMPMAP}. 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}
+ INTEGER MAP1, MAP2, MAP3
+
+ ...
+
+ CMPMAP = AST_CMPMAP( MAP1, AST_CMPMAP( MAP2, MAP3, .TRUE., ' ', STATUS ),
+ : .TRUE., ' ', STATUS )
+\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}
+ INTEGER ALIGNMAP, MAPA, MAPB
+
+ ...
+
+ CALL AST_INVERT( MAPB, STATUS )
+ ALIGNMAP = AST_CMPMAP( MAPA, MAPB, .TRUE., ' ', STATUS )
+ CALL AST_INVERT( MAPB, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, we have used \htmlref{AST\_INVERT}{AST\_INVERT} (\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{AST\_SIMPLIFY}{AST\_SIMPLIFY} 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,
+AST\_SIMPLIFY 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 AST\_SIMPLIFY works, consider the combination of
+ Mappings shown in Figure~\ref{fig:simplifyexample}.
+ \begin{figure}
+ \begin{center}
+ \includegraphics[width=0.7\textwidth]{sun210_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}
+ INTEGER SIMPLER
+
+ ...
+
+ SIMPLER = AST_SIMPLIFY( CMPMAP, STATUS );
+\end{terminalv}
+\normalsize
+
+In this case, the result would be a simple 3-dimensional UnitMap (the
+identity \htmlref{Mapping}{Mapping}). To reach this conclusion, AST\_SIMPLIFY 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 AST\_SIMPLIFY
+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,
+AST\_SIMPLIFY will just return a pointer to the original Mapping.
+
+Although AST\_SIMPLIFY 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_PAR'
+ INTEGER FRAME, STATUS
+
+ STATUS = 0
+
+ ...
+
+ FRAME = AST_FRAME( 2, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+The first argument of the \htmlref{AST\_FRAME}{AST\_FRAME} 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 routine, such as \htmlref{AST\_TRAN2}{AST\_TRAN2}.
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION XIN( 5 ), YIN( 5 ), XOUT( 5 ), YOUT( 5 )
+ DATA XIN / 0D0, 1D0, 2D0, 3D0, 4D0, 5D0 /
+ DATA YIN / 0D0, 2D0, 4D0, 6D0, 8D0, 10D0 /
+
+ CALL AST_SET( FRAME, 'Report=1', STATUS )
+ CALL AST_TRAN2( FRAME, 5, XIN, YIN, .TRUE., XOUT, YOUT, STATUS )
+\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}
+ CHARACTER * ( 70 ) LABEL
+
+ ...
+
+ LABEL = AST_GETC( FRAME, 'Label(2)', STATUS )
+\end{terminalv}
+\normalsize
+
+Other attribute access routines (AST\_SETx, \htmlref{AST\_TEST}{AST\_TEST} and \htmlref{AST\_CLEAR}{AST\_CLEAR})
+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}
+ CHARACTER * ( 10 ) AXIS
+ INTEGER IAXIS
+
+ ...
+
+ DO 1 IAXIS = 1, AST_GETI( FRAME, 'Naxes', STATUS )
+ WRITE ( AXIS, '( I10 )' ) IAXIS
+ LABEL = AST_GETC( FRAME, 'Label(' // AXIS // ')', STATUS )
+ WRITE ( *, 199 ) IAXIS, LABEL
+ 199 FORMAT ( 'Label ', I2, ': ', A )
+ 1 CONTINUE
+\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 = AST_FRAME( 2, 'Label(1)=Offset from centre of field,' //
+ 'Unit(1) =mm,' //
+ 'Label(2)=Transmission coefficient,' //
+ 'Unit(2) =%', STATUS )
+\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{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT}
+). 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 precision values. The
+Frame class therefore provides a function, \htmlref{AST\_FORMAT}{AST\_FORMAT}, to convert
+these values into formatted strings for display:
+
+\small
+\begin{terminalv}
+ CHARACTER * ( 50 ) STRING
+ DOUBLE PRECISION VALUE
+
+ ...
+
+ STRING = AST_FORMAT( FRAME, IAXIS, VALUE, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, the AST\_FORMAT character function is passed a Frame pointer,
+the number of an axis (IAXIS) and a double precision value to format
+(VALUE). It returns a 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 Fortran REAL 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
+\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.}. Unfortunately for Fortran programmers, this must
+be a C language format specifier,\footnote{This is a consequence of
+implementing the AST library in C.} so you might find the Digits
+approach preferable.
+
+The simplest type of format specifier takes the form ``\%m.nG'', where
+``m'' and ``n'' are integers giving the minimum field width in characters
+and the number of significant digits to display (\emph{e.g.}\
+``\%10.5G''). The ''n'' value may be replaced by an asterisk, in which
+case the value of the Digits attribute is used to determine the number of
+significant digits to display. Other formatting options are also possible
+and if you need to use them you may wish to consult a book on C (see the
+``printf'' function), remembering that you want to format a double
+precision (C double) value.
+
+It is recommended that you use AST\_FORMAT whenever you display
+formatted coordinate values, even although you could format them
+yourself using a WRITE statement. 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{AST\_NORM}{AST\_NORM} routine,
+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 routine \htmlref{AST\_NORM}{AST\_NORM} 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 AST\_NORM 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 AST\_NORM 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
+AST\_NORM, as follows:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION POINT( 2 )
+
+ ...
+
+ CALL AST_NORM( FRAME, POINT, STATUS )
+\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 AST\_NORM 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{AST\_FORMAT}{AST\_FORMAT} (\secref{ss:formattingaxisvalues}). Even if
+the Frame in question does not restrict the range of coordinates, so
+that AST\_NORM 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{AST\_FORMAT}{AST\_FORMAT}
+(\secref{ss:formattingaxisvalues}), back into a numerical (double
+precision) value ready for processing is performed by \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}.
+However, although this process is essentially the inverse of that
+performed by AST\_FORMAT, there are a number of additional difficulties
+that must be addressed in practice.
+
+The main use for AST\_UNFORMAT 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 AST\_FORMAT 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,
+AST\_UNFORMAT may have to read a value like ``1.25E-6'', whereas a
+more specialised Frame representing celestial coordinates 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 AST\_UNFORMAT works. It is
+invoked as follows:
+
+\small
+\begin{terminalv}
+ INTEGER N
+
+ ...
+
+ N = AST_UNFORMAT( FRAME, IAXIS, STRING, VALUE, STATUS )
+\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, AST\_UNFORMAT returns the resulting coordinate
+\emph{via} its penultimate 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 AST\_UNFORMAT 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 AST\_UNFORMAT 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, AST\_UNFORMAT 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, AST\_UNFORMAT
+may examine the Frame's attributes and, in particular, the appropriate
+\htmlref{Format(axis)}{Format(axis)} string which is used by AST\_FORMAT when formatting
+coordinate values (\secref{ss:formattingaxisvalues}). This is done in
+order that AST\_FORMAT and AST\_UNFORMAT 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 = AST_UNFORMAT( FRAME, IAXIS, ' 1.5E6 -99.0', VALUE, STATUS )
+\end{terminalv}
+\normalsize
+
+AST\_UNFORMAT 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. For example, if the
+string is expected to contain exactly one value, and nothing else,
+then the following would suffice:
+
+\small
+\begin{terminalv}
+ N = AST_UNFORMAT( FRAME, IAXIS, STRING, VALUE, STATUS )
+ IF ( STATUS .EQ. 0 ) THEN
+ IF ( N .LT. LEN( STRING ) ) THEN
+ <error in input data>
+ ELSE
+ <value read correctly>
+ END IF
+ END IF
+\end{terminalv}
+\normalsize
+
+If AST\_UNFORMAT does not detect an error itself, we check that it has
+read to the end of the 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}
+ INTEGER I
+ DOUBLE PRECISION VALUES( 10 )
+
+ ...
+
+* Initialise the string index.
+ I = 1
+
+* Obtain the number of Frame axes and loop through them.
+ DO 1 IAXIS = 1, AST_GETI( FRAME, 'Naxes', STATUS )
+
+* Attempt to read a value for this axis.
+ N = AST_UNFORMAT( FRAME, IAXIS, STRING( I : ),
+ : VALUES( IAXIS ), STATUS )
+
+* If nothing was read and this is not the first axis and the end of
+* the string has not been reached, try stepping over a separator and
+* reading again.
+ IF ( ( N .EQ. 0 ) .AND. ( IAXIS .GT. 1 ) .AND.
+ : ( I .LT. LEN( STRING ) ) ) THEN
+ I = I + 1
+ N = AST_UNFORMAT( FRAME, IAXIS, STRING( I : ),
+ : VALUES( IAXIS ), STATUS )
+ END IF
+
+* Quit if nothing was read, otherwise move on to the next value.
+ IF ( N .EQ. 0 ) GO TO 2
+ I = I + N
+ 1 CONTINUE
+ 2 CONTINUE
+
+* Check for possible errors.
+ IF ( STATUS .EQ. 0 ) THEN
+ IF ( ( I .LT. LEN( STRING ) ) .OR. ( N .EQ. 0 ) ) THEN
+ <error in input data>
+ ELSE
+ <values read correctly>
+ END IF
+ END IF
+\end{terminalv}
+\normalsize
+
+In this case, the value of I will indicate 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}
+ INTEGER PERM( 2 )
+ DATA PERM / 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{AST\_PERMAXES}{AST\_PERMAXES} 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}
+ CALL AST_PERMAXES( FRAME, PERM, STATUS )
+\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{AST\_PERMAXES}{AST\_PERMAXES}
+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}
+ INTEGER FRAME1, FRAME2, MAPPING, PICK( 2 )
+ DATA PICK / 3, 2 /
+
+ ...
+
+ FRAME2 = AST_PICKAXES( FRAME1, 2, PICK, MAPPING, STATUS )
+\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{AST\_COPY}{AST\_COPY}
+(\secref{ss:copyingobjects}) to make an independent copy.
+
+In addition to the new Frame pointer, \htmlref{AST\_PICKAXES}{AST\_PICKAXES} will also return a
+pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument. 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 AST\_PICKAXES, 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
+AST\_PICKAXES 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
+routines
+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}.
+
+Routines
+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 routines, \htmlref{AST\_DISTANCE}{AST\_DISTANCE}, returns a double precision
+distance value when supplied with the Frame coordinates of two
+points. For example:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION DIST, POINT1( 2 ), POINT2( 2 )
+ DATA POINT1 / 0D0, 0D0 /
+ DATA POINT2 / 1D0, 1D0 /
+
+ ...
+
+ DIST = AST_DISTANCE( FRAME, POINT1, POINT2, STATUS )
+\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, AST\_DISTANCE 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{AST\_OFFSET}{AST\_OFFSET} routine is really the inverse of AST\_DISTANCE. 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 PRECISION POINT1( 2 ), POINT2( 2 ), POINT3( 2 )
+ DATA POINT1 / 0D0, 0D0 /
+ DATA POINT2 / 1D0, 1D0 /
+
+ ...
+
+ CALL AST_OFFSET( FRAME, POINT1, POINT2, 0.5D0, POINT3, STATUS )
+\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 routines \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE} and \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET} are similar to AST\_DISTANCE
+and AST\_OFFSET, 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 routines is to deal with the cyclic ambiguity of
+longitude and latitude axes.
+
+The \htmlref{AST\_OFFSET2}{AST\_OFFSET2} routine is similar to AST\_OFFSET, 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
+AST\_OFFSET2 routine
+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 AST\_OFFSET2 to calculate the
+position of each corner, and then add (or subtract) 90 degrees from the
+position angle returned by AST\_OFFSET2.
+
+The \htmlref{AST\_ANGLE}{AST\_ANGLE} routine
+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{AST\_AXANGLE}{AST\_AXANGLE} routine is similar to AST\_AXANGLE,
+but the ``reference direction'', from which angles are measured, is
+a specified axis.
+
+The \htmlref{AST\_RESOLVE}{AST\_RESOLVE} routine
+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 a
+blank 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 = AST_FRAME( 2, 'Domain=CCD_CHIP,' //
+ 'Unit(1)=micron,' //
+ 'Unit(2)=micron', STATUS )
+ FRAME2 = AST_FRAME( 2, 'Domain=FOCAL_PLANE,' //
+ 'Unit(1)=mm,' //
+ 'Unit(2)=mm', STATUS )
+\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{AST\_CONVERT}{AST\_CONVERT}
+) 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
+routines \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} and \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT}
+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}
+ INTEGER FRAME1, FRAME2
+
+ FRAME1 = AST_FRAME( 1, 'Domain=VELOCITY,Unit=km/h' )
+ FRAME2 = AST_FRAME( 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}
+ CALL AST_SETACTIVEUNIT( FRAME1, .TRUE., STATUS )
+ CALL AST_SETACTIVEUNIT( FRAME2, .TRUE., STATUS )
+\end{terminalv}
+\normalsize
+
+If we then find the Mapping between them as follows:
+
+\small
+\begin{terminalv}
+ INTEGER CVT
+ ...
+ CVT = AST_CONVERT( FRAME1, FRAME2, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by
+AST\_CONVERT
+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 AST\_CONVERT is determined by its TO Frame
+(the second Frame argument).
+
+\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{AST\_PERMAXES}{AST\_PERMAXES} routine (\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_PAR'
+ INTEGER SKYFRAME, STATUS
+
+ STATUS = 0
+
+ ...
+
+ SKYFRAME = AST_SKYFRAME( ' ', STATUS )
+\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 = AST_SKYFRAME( 'System=FK4', STATUS )
+\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 = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2005.5', STATUS )
+\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{AST\_SHOW}{AST\_SHOW} to examine a SkyFrame, as
+follows:
+
+\small
+\begin{terminalv}
+ CALL AST_SHOW( AST_SKYFRAME( 'System=FK4-NO-E, Epoch=1958', STATUS ), STATUS )
+\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{AST\_FORMAT}{AST\_FORMAT}
+(\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{AST\_FORMAT}{AST\_FORMAT} 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{AST\_FORMAT}{AST\_FORMAT} function
+(\secref{ss:formattingskyaxisvalues}), into numerical (double
+precision) coordinate values is performed by using \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}
+(\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
+AST\_FORMAT (\secref{ss:formattingskyaxisvalues}) are correctly
+interpreted by AST\_UNFORMAT.
+
+\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 AST\_FORMAT
+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
+AST\_FORMAT would produce.
+
+\end{itemize}
+
+This final convention is intended to ensure that values formatted by
+AST\_FORMAT which contain less than three fields will be correctly
+interpreted if read back using AST\_UNFORMAT, 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 AST\_UNFORMAT 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 AST\_UNFORMAT 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_PAR'
+ INTEGER SPECFRAME, STATUS
+
+ STATUS = 0
+
+ ...
+
+ SPECFRAME = AST_SPECFRAME( ' ', STATUS )
+\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 = AST_SPECFRAME( 'System=Energy', STATUS )
+\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{AST\_SHOW}{AST\_SHOW} to examine a SpecFrame, as
+follows:
+
+\small
+\begin{terminalv}
+ CALL AST_SHOW( AST_SPECFRAME( 'System=Vopt, RestFreq=250 GHz', STATUS ),
+ : STATUS )
+\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}
+ CALL AST_SETC( SPECFRAME, 'Unit', 'kHz', STATUS )
+\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{AST\_CONVERT}{AST\_CONVERT}
+) 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}
+ INTEGER SKYFRAME
+ INTEGER SPECFRAME
+ INTEGER CMPFRAME
+ ...
+ SKYFRAME = AST_SKYFRAME( 'Epoch=J2002', STATUS )
+ SPECFRAME = AST_SPECFRAME( 'System=Freq,StdOfRest=LSRK',
+ : STATUS )
+ CMPFRAME = AST_CMPFRAME( SKYFRAME, SPECFRAME, ' ', STATUS )
+\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{AST\_PERMAXES}{AST\_PERMAXES}.
+
+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{AST\_CONVERT}{AST\_CONVERT}
+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
+AST\_CONVERT
+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_PAR'
+ INTEGER TIMEFRAME, STATUS
+
+ STATUS = 0
+
+ ...
+
+ TIMEFRAME = AST_TIMEFRAME( ' ', STATUS )
+\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 = AST_TIMEFRAME( 'System=JEPOCH', STATUS )
+\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}
+ INTEGER SKYFRAME
+ INTEGER SPECFRAME
+ INTEGER CMPFRAME
+ ...
+ SKYFRAME = AST_SKYFRAME( ' ', STATUS )
+ SPECFRAME = AST_SPECFRAME( ' ', STATUS )
+ CMPFRAME = AST_CMPFRAME( SKYFRAME, SPECFRAME, ' ', STATUS )
+\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}
+ INTEGER PERM(3)
+ ...
+
+ PERM( 1 ) = 1
+ PERM( 2 ) = 3
+ PERM( 3 ) = 2
+ CALL AST_PERMAXES( CMPFRAME, PERM, STATUS )
+\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_PAR'
+ INTEGER SKYFRAME1, SKYFRAME2, STATUS
+
+ STATUS = 0
+
+ ...
+
+ SKYFRAME1 = AST_SKYFRAME( 'System=FK4-NO-E, Epoch=B1958, Equinox=B1960', STATUS )
+ SKYFRAME2 = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2010.5', STATUS )
+\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{AST\_CONVERT}{AST\_CONVERT}, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER CVT
+
+ ...
+
+ CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS )
+ IF ( CVT .EQ. AST__NULL ) THEN
+ <conversion is not possible>
+ ELSE
+ <conversion is possible>
+ END IF
+\end{terminalv}
+\normalsize
+
+The third argument of AST\_CONVERT is not used here and should be a
+blank string.
+
+AST\_CONVERT will return a null result, AST\_\_NULL (as defined in the
+AST\_PAR include 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}
+ INTEGER N
+ DOUBLE PRECISION ALPHA1( N ), DELTA1( N )
+ DOUBLE PRECISION ALPHA2( N ), DELTA2( N )
+
+ ...
+
+ CALL AST_TRAN2( CVT, N, ALPHA1, DELTA1, .TRUE., ALPHA2, DELTA2, STATUS )
+\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 (logical) argument to \htmlref{AST\_TRAN2}{AST\_TRAN2}, as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_TRAN2( CVT, N, ALPHA2, DELTA2, .FALSE., ALPHA1, DELTA1, STATUS )
+\end{terminalv}
+\normalsize
+
+The FrameSet returned by AST\_CONVERT 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{AST\_DISTANCE}{AST\_DISTANCE}:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION DISTANCE, POINT1( 2 ), POINT2( 2 )
+
+ ...
+
+ DISTANCE = AST_DISTANCE( CVT, POINT1, POINT2, STATUS )
+\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}
+ CALL AST_SET( CVT, 'Report=1', STATUS )
+ CALL AST_TRAN2( CVT, N, ALPHA1, DELTA1, .TRUE., ALPHA2, DELTA2, STATUS )
+\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 AST\_CONVERT. 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_PAR'
+ INTEGER SPECFRAME1, SPECFRAME2, STATUS
+
+ STATUS = 0
+
+ ...
+
+ SPECFRAME1 = AST_SPECFRAME( ' ', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'System=vradio', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'Unit=km/s', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'Epoch=1996-Oct-2 12:13:56.985',
+ : STATUS )
+ CALL AST_SETC( SPECFRAME1, 'ObsLon=W155:28:18', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'ObsLat=N19:49:34', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'RefRA=18:14:50.6', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'RefDec=-4:40:49', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'RestFreq=230.538 GHz', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'StdOfRest=LSRK', STATUS )
+
+ SPECFRAME2 = AST_COPY( SPECFRAME1, STATUS )
+ CALL AST_SETC( SPECFRAME1, 'System=freq', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'Unit=GHz', STATUS )
+ CALL AST_SETC( SPECFRAME1, 'StdOfRest=Topocentric', STATUS )
+
+\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}
+ INTEGER CVT
+
+ ...
+
+ CVT = AST_CONVERT( SPECFRAME1, SPECFRAME2, ' ', STATUS )
+ IF ( CVT .EQ. AST__NULL ) THEN
+ <conversion is not possible>
+ ELSE
+ <conversion is possible>
+ END IF
+\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{AST\_TRAN1}{AST\_TRAN1} in place of \htmlref{AST\_TRAN2}{AST\_TRAN2}
+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}
+ INTEGER N
+ DOUBLE PRECISION FRQ( N )
+ DOUBLE PRECISION VEL( N )
+
+ ...
+
+ CALL AST_TRAN1( CVT, N, FRQ, .TRUE., VEL, STATUS )
+\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{AST\_PERMAXES}{AST\_PERMAXES}
+(\secref{ss:permutingaxes}) to do this to the second SkyFrame, before
+applying \htmlref{AST\_CONVERT}{AST\_CONVERT}, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER PERM( 2 )
+ DATA PERM / 2, 1 /
+
+ ...
+
+ CALL AST_PERMAXES( SKYFRAME2, PERM, STATUS )
+ CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS )
+\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 AST\_CONVERT 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 AST\_CONVERT 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{AST\_CONVERT}{AST\_CONVERT} to derive a conversion
+between them, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER FRAME1, FRAME2
+
+ ...
+
+ FRAME1 = AST_FRAME( 2, ' ', STATUS )
+ FRAME2 = AST_FRAME( 2, ' ', STATUS )
+ CVT = AST_CONVERT( FRAME1, FRAME2, ' ', STATUS )
+\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 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{AST\_CONVERT}{AST\_CONVERT} 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_PAR'
+ INTEGER FRAME1, STATUS
+
+ STATUS = 0
+
+ ...
+
+ FRAME1 = AST_FRAME( 2, 'Domain=A', STATUS )
+\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}
+ INTEGER FRAMESET
+
+ ...
+
+ FRAMESET = AST_FRAMESET( FRAME1, ' ', STATUS )
+\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}
+ INTEGER FRAME2, MAPPING12
+
+ ...
+
+ FRAME2 = AST_FRAME( 2, 'Domain=B', STATUS )
+ MAPPING12 = AST_ZOOMMAP( 2, 10.0D0, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+To add the new Frame into our FrameSet, we use the \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}
+routine:
+
+\small
+\begin{terminalv}
+ CALL AST_ADDFRAME( FRAMESET, 1, MAPPING12, FRAME2, STATUS )
+\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{AST\_COPY}{AST\_COPY}
+(\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}
+ CALL AST_ADDFRAME( FRAMESET, 1,
+ : AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ),
+ : AST_FRAME( 2, 'Domain=C', STATUS ),
+ : STATUS )
+\end{terminalv}
+\normalsize
+
+Here, we have avoided storing unnecessary pointer values by using
+function invocations directly as arguments for AST\_ADDFRAME. This
+assumes that we are using \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END}
+(\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]{sun210_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}
+ CALL AST_SETI( FRAMESET, 'Current', 3, STATUS )
+\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 parameter
+constants, AST\_\_BASE and AST\_\_CURRENT, are defined in the AST\_PAR
+include 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}
+ INTEGER FRAME, MAPPING
+
+ ...
+
+ CALL AST_ADDFRAME( FRAMESET, AST__CURRENT, MAPPING, FRAME, STATUS )
+\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 routine such as \htmlref{AST\_TRAN2}{AST\_TRAN2}:
+
+\small
+\begin{terminalv}
+ INTEGER N
+ DOUBLE PRECISION XIN( N ), YIN( N )
+ DOUBLE PRECISION XOUT( N ), YOUT( N )
+
+ ...
+
+ CALL AST_TRAN2( FRAMESET, N, XIN, YIN, .TRUE., XOUT, YOUT, STATUS )
+\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{AST\_INVERT}{AST\_INVERT}
+(\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{AST\_GETMAPPING}{AST\_GETMAPPING} 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 = AST_GETMAPPING( FRAMESET, 2, 3, STATUS )
+\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{AST\_COPY}{AST\_COPY} should be used to make a copy if you need to guarantee
+independence (\secref{ss:copyingobjects}).
+
+Very often, the Mapping returned by AST\_GETMAPPING 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{AST\_SIMPLIFY}{AST\_SIMPLIFY} 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}
+ CHARACTER * ( 80 ) TITLE
+
+ ...
+
+ TITLE = AST_GETC( FRAMESET, 'Title', STATUS )
+\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{AST\_GETFRAME}{AST\_GETFRAME} function, as follows:
+
+\small
+\begin{terminalv}
+ FRAME = AST_GETFRAME( FRAMESET, AST__BASE, STATUS )
+\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{AST\_REMOVEFRAME}{AST\_REMOVEFRAME} routine. 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}
+ CALL AST_REMOVEFRAME( FRAMESET, 1, STATUS );
+\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, AST\_REMOVEFRAME 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 AST\_CONVERT}
+
+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{AST\_CONVERT}{AST\_CONVERT}. 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_PAR'
+ INTEGER SKYFRAME1, SKYFRAME2, STATUS
+
+ STATUS = 0
+
+ ...
+
+ SKYFRAME1 = AST_SKYFRAME( 'System=FK4-NO-E, Epoch=B1958, Equinox=B1960', STATUS )
+ SKYFRAME2 = AST_SKYFRAME( 'System=Ecliptic, Equinox=J2010.5', STATUS )
+
+ CVT = AST_CONVERT( SKYFRAME1, SKYFRAME2, ' ', STATUS )
+\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]{sun210_figures/fsconvert}
+ \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when AST\_CONVERT 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 AST\_CONVERT 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 AST\_CONVERT 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{AST\_GETMAPPING}{AST\_GETMAPPING} (\secref{ss:extractingamapping}), for example:
+
+\small
+\begin{terminalv}
+ INTEGER MAPPING
+
+ ...
+
+ MAPPING = AST_GETMAPPING( CVT, AST__BASE, AST__CURRENT, STATUS )
+\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]{sun210_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{AST\_CONVERT}{AST\_CONVERT}
+(\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}
+ INTEGER FRAMESETA, FRAMESETB
+
+ ...
+
+ CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY', STATUS )
+\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 AST\_CONVERT 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 AST\_CONVERT 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 AST\_CONVERT. 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 AST\_CONVERT, such as
+the following:
+
+\small
+\begin{terminalv}
+ CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY,PIXEL,GRID,', STATUS )
+\end{terminalv}
+\normalsize
+
+Now, if the two FrameSets cannot be inter-related using the SKY domain,
+AST\_CONVERT 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, AST\_CONVERT 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 AST\_CONVERT 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{AST\_COPY}{AST\_COPY}---\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. astInvert will perform this task:
+
+\small
+\begin{terminalv}
+ CALL AST_INVERT( FRAMESETA, STATUS )
+ CALL AST_INVERT( FRAMESETB, STATUS )
+\end{terminalv}
+\normalsize
+
+To identify the required conversion, we now use \htmlref{AST\_CONVERT}{AST\_CONVERT},
+supplying a suitable domain search path with which we would like our
+two images to be registered:
+
+\small
+\begin{terminalv}
+ CVT = AST_CONVERT( FRAMESETA, FRAMESETB, 'SKY,PIXEL,GRID', STATUS )
+ IF ( CVT .EQ. AST__NULL ) THEN
+ <no conversion was possible>
+ ELSE
+ <conversion was possible>
+ END IF
+\end{terminalv}
+\normalsize
+
+The effects of this are:
+
+\begin{enumerate}
+\item AST\_CONVERT 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, AST\_CONVERT 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, AST\_CONVERT 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
+AST\_CONVERT 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}
+ CHARACTER * ( 20 ) DOMAIN
+
+ ...
+
+
+ CALL AST_INVERT( FRAMESETA, STATUS )
+ DOMAIN = AST_GETC( FRAMESETA, 'Domain', STATUS )
+\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{AST\_GETFRAME}{AST\_GETFRAME} 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]{sun210_figures/fsremap}
+\caption[Interposing a Mapping into a FrameSet]{The effect
+ of \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME} 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
+AST\_REMAPFRAME 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{AST\_REMAPFRAME}{AST\_REMAPFRAME}, 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}
+ INTEGER WINMAP
+ DOUBLE PRECISION INA( 2 ), INB( 2 ), OUTA( 2 ), OUTB( 2 )
+ DATA INA / 0.5D0, 0.5D0 /
+ DATA INB / 2.5D0, 2.5D0 /
+ DATA OUTA / 0.5D0, 0.5D0 /
+ DATA OUTB / 1.5DO, 1.5DO /
+
+ ...
+
+ WINMAP = AST_WINMAP( 2, INA, INB, OUTA, OUTB, ' ', STATUS )
+\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{AST\_WINMAP}{AST\_WINMAP} 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 AST\_REMAPFRAME. 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}
+ INTEGER FRAMESET
+
+ ...
+
+ CALL AST_REMAPFRAME( FRAMESET, AST__BASE, WINMAP, STATUS )
+\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{AST\_SET}{AST\_SET} on the FrameSet, as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_SET( FRAMESET, 'Equinox=J2010', STATUS )
+\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{AST\_REMAPFRAME}{AST\_REMAPFRAME} had been used---\secref{ss:remapframe}) in response to
+the use of AST\_SET. One way of illustrating this process is as
+follows:
+
+\small
+\begin{terminalv}
+ INTEGER SKYFRAME
+
+ ...
+
+ SKYFRAME = AST_SKYFRAME( ' ', STATUS )
+ FRAMESET = AST_FRAMESET( SKYFRAME, STATUS )
+ CALL AST_ADDFRAME( FRAMESET, 1, AST_UNITMAP( 2, ' ', STATUS )
+ : SKYFRAME, STATUS )
+\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}
+ CALL AST_SET( FRAMESET, 'System=Ecliptic, Equinox=J2010', STATUS )
+\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}
+ CALL AST_INVERT( FRAMESET )
+ CALL AST_SET( FRAMESET, 'System=Galactic', STATUS )
+ CALL AST_INVERT( FRAMESET )
+\end{terminalv}
+\normalsize
+
+The FrameSet would then convert between galactic and ecliptic
+coordinates.
+
+Note that AST\_SET is not the only function which has this effect:
+\htmlref{AST\_CLEAR}{AST\_CLEAR} behaves similarly, as also does \htmlref{AST\_PERMAXES}{AST\_PERMAXES}
+(\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 = AST_GETFRAME( FRAMESET, AST__CURRENT, STATUS )
+ CALL AST_SET( SKYFRAME, 'Equinox=J2010', STATUS )
+ CALL AST_ANNUL( SKYFRAME, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, AST\_SET 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
+AST\_REMAPFRAME.
+
+\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]{sun210_figures/fsmerge}
+ \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using
+ \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}. 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
+AST\_ADDFRAME, 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}
+ INTEGER MAPPING
+
+ ...
+
+ CALL AST_ADDFRAME( FRAMESETA, 1, MAPPING, FRAMESETB, STATUS )
+\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 Fortran I/O
+unit (also represented by an integer, as it happens) and to think of
+the process of creating a Channel as the combined process of
+allocating a unit number and attaching it to a file by opening the
+file on that unit. 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 Fortran I/O unit
+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{AST\_CHANNEL}{AST\_CHANNEL}:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER CHANNEL, STATUS
+
+ STATUS = 0
+
+ ...
+
+ CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+The first two arguments to AST\_CHANNEL specify the external source
+and sink that the Channel is to use. There arguments are the names of
+Fortran subroutines 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 the name of the null
+routine AST\_NULL\footnote{Note that AST\_NULL (one underscore) is a
+routine name and is distinct from AST\_\_NULL (two underscores) which
+is a null \htmlref{Object}{Object} pointer. Since we are passing the name of one
+routine to another routine, AST\_NULL would normally have to appear in
+a Fortran EXTERNAL statement. In this example, however, a suitable
+statement is already present in the AST\_PAR include file.} for both
+the source and sink routines. 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.
+
+\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{AST\_WRITE}{AST\_WRITE}
+function, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER NOBJ, OBJECT
+
+ ...
+
+ NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS )
+\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.
+
+AST\_WRITE 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, AST\_WRITE 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{AST\_READ}{AST\_READ} function, having first created a suitable
+\htmlref{Channel}{Channel}:
+
+\small
+\begin{terminalv}
+ OBJECT = AST_READ( CHANNEL, STATUS )
+\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
+AST\_READ.
+
+\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{AST\_READ}{AST\_READ} will return the value AST\_\_NULL to indicate an
+\emph{end-of-file}.
+
+\subsection{\label{ss:validatinginput}Validating Input}
+
+The pointer returned by \htmlref{AST\_READ}{AST\_READ} (\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{AST\_ISA$<$CLASS$>$}{AST\_ISA$<$CLASS$>$} family of functions:
+
+\small
+\begin{terminalv}
+ LOGICAL OK
+
+ ...
+
+ OK = AST_ISAFRAME( OBJECT, STATUS )
+\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}
+ OK = AST_GETC( OBJECT, 'Class', STATUS ) .EQ. '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}
+ CALL AST_SET( OBJECT, 'ID=Calibration', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS )
+\end{terminalv}
+\normalsize
+
+You can then test its value after you read the Object back:
+
+\small
+\begin{terminalv}
+ OBJECT = AST_READ( CHANNEL, STATUS )
+ IF ( AST_GETC( OBJECT, 'ID', STATUS ) .EQ. 'Calibration' ) THEN
+ <the Calibration Object has been read>
+ ELSE
+ <some other Object has been read>
+ END IF
+\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}
+ INTEGER SKYFRAME
+
+ ...
+
+ NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS )
+\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{AST\_SHOW}{AST\_SHOW} works (\secref{ss:displayingobjects}), this routine
+being roughly equivalent to the following use of a Channel:
+
+\small
+\begin{terminalv}
+ CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, ' ', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS )
+ CALL AST_ANNUL( CHANNEL, STATUS )
+\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{AST\_READ}{AST\_READ}. 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{AST\_WRITE}{AST\_WRITE}
+(\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 = AST_CHANNEL( AST_NULL, AST_NULL, 'Full=-1', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS )
+ CALL AST_ANNUL( CHANNEL, STATUS )
+\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}
+ CALL AST_SET( CHANNEL, 'Full=-1, Comment=0', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, SKYFRAME, STATUS )
+\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{AST\_WRITE}{AST\_WRITE} (or
+\htmlref{AST\_SHOW}{AST\_SHOW}) 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{AST\_READ}{AST\_READ} is intended for retrieving data written by AST\_WRITE
+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{AST\_READ}{AST\_READ} 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 Fortran
+program will read all the AST Objects whose descriptions appear in the
+source of this document, ignoring the other text. \htmlref{AST\_SHOW}{AST\_SHOW} is used to
+display those found:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER CHANNEL, OBJECT, STATUS
+
+ STATUS = 0
+ CHANNEL = AST_CHANNEL( AST_NULL, AST_NULL, 'Skip=1', STATUS )
+ 1 OBJECT = AST_READ( CHANNEL, STATUS )
+ IF ( OBJECT .NE. AST__NULL ) THEN
+ CALL AST_SHOW( OBJECT, STATUS )
+ CALL AST_ANNUL( OBJECT, STATUS )
+ GO TO 1
+ END IF
+ CALL AST_ANNUL( CHANNEL, STATUS )
+ END
+\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}
+ CALL AST_SET( CHANNEL, 'SourceFile=fred.txt', STATUS )
+ OBJ1 = AST_READ( CHANNEL, STATUS )
+ OBJ2 = AST_READ( CHANNEL, STATUS )
+ CALL AST_CLEAR( CHANNEL, 'SourceFile', STATUS )
+\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
+Fortran routines that perform the actual transfer of data to and from
+files and similar external data stores. The routines you provide are
+supplied as the source and/or sink routine arguments to \htmlref{AST\_CHANNEL}{AST\_CHANNEL}
+when you create a Channel (\secref{ss:creatingachannel}). An example is
+the best way to illustrate this.
+
+Consider the following simple subroutine called SOURCE. It reads a
+single line of text from a Fortran I/O unit and then calls
+\htmlref{AST\_PUTLINE}{AST\_PUTLINE} to pass it to the AST library, together with its
+length. It sets this length to be negative if there is no more input:
+
+\small
+\begin{terminalv}
+ SUBROUTINE SOURCE( STATUS )
+ INTEGER STATUS
+ CHARACTER * ( 200 ) BUFFER
+
+ READ( 1, '(A)', END = 99 ) BUFFER
+ CALL AST_PUTLINE( BUFFER, LEN( BUFFER ), STATUS )
+ RETURN
+
+ 99 CALL AST_PUTLINE( BUFFER, -1, STATUS )
+ END
+\end{terminalv}
+\normalsize
+
+Our main program might then look something like this (omitting error
+checking for brevity):
+
+\small
+\begin{terminalv}
+ EXTERNAL SOURCE
+
+ ...
+
+* Open the input file.
+ OPEN( UNIT = 1, FILE = 'infile.ast', STATUS = 'OLD' )
+
+* Create the Channel and read an Object from it.
+ CHANNEL = AST_CHANNEL( SOURCE, AST_NULL, ' ', STATUS )
+ OBJECT = AST_READ( CHANNEL, STATUS )
+
+ ...
+
+* Annul the Channel and close the file when done.
+ CALL AST_ANNUL( CHANNEL, STATUS )
+ CLOSE( 1 )
+\end{terminalv}
+\normalsize
+
+Here, we first open the required input file. We then pass the name of
+our SOURCE routine as the first argument to AST\_CHANNEL when creating
+a new Channel (ensuring that SOURCE also appears in an EXTERNAL
+statement). When we read an \htmlref{Object}{Object} from this Channel using
+\htmlref{AST\_READ}{AST\_READ}, the SOURCE routine will be called to obtain the textual
+data from the file, the end-of-file being detected when it yields a
+negative line length.
+
+Note, if a value is set for the SourceFile attribute,
+the AST\_READ function will ignore any source routine
+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}
+ CALL AST_SET( CHANNEL, 'SinkFile=fred.txt', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, OBJECT1, STATUS )
+ NOBJ = AST_WRITE( CHANNEL, OBJECT2, STATUS )
+ CALL AST_CLEAR( CHANNEL, 'SinkFile', STATUS )
+\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 routine,
+that obtains a line of output text from the AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}
+and then writes it to a file. We can use this in basically the same way as
+the SOURCE routine in the previous section (\secref{ss:channelsource}):
+
+\small
+\begin{terminalv}
+ SUBROUTINE SINK( STATUS )
+ INTEGER L, STATUS
+ CHARACTER * ( 200 ) BUFFER
+
+ CALL AST_GETLINE( BUFFER, L, STATUS )
+ IF ( L .GT. 0 ) WRITE( 2, '(A)' ) BUFFER( : L )
+
+ END
+\end{terminalv}
+\normalsize
+
+In this case, our main program would supply the name of this SINK
+routine as the second argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL} (ensuring that it also
+appears in an EXTERNAL statement), as follows:
+
+\small
+\begin{terminalv}
+ EXTERNAL SINK
+
+ ...
+
+* Open the output file.
+ OPEN( UNIT = 2, FILE = 'outfile.ast', STATUS = 'NEW' )
+
+* Create a Channel and write an Object to it.
+ CHANNEL = AST_CHANNEL( SOURCE, SINK, ' ', STATUS )
+ NOBJ = AST_WRITE( CHANNEL, OBJECT, STATUS )
+
+ ...
+
+* Annul the Channel and close the file when done.
+ CALL AST_ANNUL( CHANNEL, STATUS )
+ CLOSE( 2 )
+\end{terminalv}
+\normalsize
+
+Note that we can specify a source and/or a sink routine 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 Fortran statements.
+
+If an error occurs in your source or sink routine, you can communicate
+this to the AST library by setting the STATUS argument to any error
+value. This will immediately terminate the read or write operation.
+
+Note, if a value is set for the SinkFile attribute,
+the \htmlref{AST\_WRITE}{AST\_WRITE} function will ignore any sink routine
+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 routines
+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 routines, 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{AST\_PUTFITS}{AST\_PUTFITS}
+(\secref{ss:addingfitscards}).
+
+\item You may add cards yourself, supplying all cards concatenated into a
+single string, using \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}.
+(\secref{ss:addingmulticards}).
+
+\item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{AST\_WRITE}{AST\_WRITE}),
+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
+AST\_SETC or \htmlref{AST\_SET}{AST\_SET}).
+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 routine 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
+routine, 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{AST\_DELFITS}{AST\_DELFITS}
+(\secref{ss:findingandchangingfits}).
+
+\item You may read an AST Object from the FitsChan (using \htmlref{AST\_READ}{AST\_READ}),
+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 routine 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 routine,
+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 routine 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{AST\_FINDFITS}{AST\_FINDFITS} (which is not
+destructive). This is the main means of writing out FITS cards if you
+have not supplied a sink routine. AST\_FINDFITS 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{AST\_FITSCHAN}{AST\_FITSCHAN}, is straightforward
+to use:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER FITSCHAN, STATUS
+
+ STATUS = 0
+
+ ...
+
+ FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, 'Encoding=NATIVE', STATUS )
+\end{terminalv}
+\normalsize
+
+Here, we have omitted any source or sink functions by supplying the
+AST\_NULL routine for the first two arguments (remember to include the
+AST\_PAR include file which contains the required EXTERNAL statement
+for this routine).
+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}
+ INTEGER ICARD
+
+ ...
+
+ CALL AST_SETI( FITSCHAN, 'Card', ICARD, STATUS )
+\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}
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+\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}
+ DO 1 ICARD = 1, AST_GETI( FITSCHAN, 'Ncard', STATUS )
+ CALL AST_SETI( FITSCHAN, 'Card', ICARD, STATUS )
+ <access the current card>
+ 1 CONTINUE
+\end{terminalv}
+\normalsize
+
+However, it is usually possible to write slightly tidier loops based
+on the \htmlref{AST\_FINDFITS}{AST\_FINDFITS} 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{AST\_WRITE}{AST\_WRITE} 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}
+ INTEGER NOBJ, SKYFRAME
+
+ ...
+
+ NOBJ = AST_WRITE( FITSCHAN, SKYFRAME, STATUS )
+\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 AST\_WRITE 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 AST\_WRITE routine and the
+\emph{native} encoding. If a long string is stored in a FitsChan using
+(for instance) the \htmlref{AST\_PUTFITS}{AST\_PUTFITS} or \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS} routine, 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{AST\_CLEAR}{AST\_CLEAR}. The
+following loop would do:
+
+\small
+\begin{terminalv}
+ CHARACTER * ( 80 ) CARD
+
+ ...
+
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+
+ 2 CONTINUE
+ IF ( AST_FINDFITS( FITSCHAN, '%f', CARD, .TRUE., STATUS ) ) THEN
+ WRITE ( *, '(A)' ) CARD
+ GO TO 2
+ END IF
+\end{terminalv}
+\normalsize
+
+Here, we have used the \htmlref{AST\_FINDFITS}{AST\_FINDFITS} 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 .TRUE., 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. AST\_FINDFITS
+returns .FALSE.\ 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 the WRITE
+statement with a call to a suitable data access routine to store the
+header card. This would only be necessary if we had not provided a
+sink routine 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{AST\_WRITE}{AST\_WRITE} 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 AST\_WRITE 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{AST\_PUTFITS}{AST\_PUTFITS} routine. You
+can insert a card in front of the current one as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_PUTFITS( FITSCHAN, CARD, .FALSE., STATUS )
+\end{terminalv}
+\normalsize
+
+where the third argument of .FALSE.\ 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 character 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}
+ INTEGER NCARD
+ CHARACTER * ( 80 ) CARDS( NCARD )
+
+ ...
+
+ DO 3 ICARD = 1, NCARD
+ CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS )
+ 3 CONTINUE
+\end{terminalv}
+\normalsize
+
+
+Note that AST\_PUTFITS 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{AST\_PUTCARDS}{AST\_PUTCARDS}.
+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{AST\_READ}{AST\_READ}
+will start reading from the first supplied card. The
+AST\_PUTCARDS routine uses \htmlref{AST\_PUTFITS}{AST\_PUTFITS}
+internally to interpret and store each individual card, and so the
+caveats in \secref{ss:addingfitscards} should be read.
+
+
+\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{AST\_READ}{AST\_READ} 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}
+ INTEGER OBJECT
+
+ ...
+
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+ OBJECT = AST_READ( FITSCHAN, STATUS )
+\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 AST\_READ 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{AST\_COPY}{AST\_COPY}
+(\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 routine
+\htmlref{AST\_WRITE}{AST\_WRITE}. The AST\_READ routine 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{AST\_FINDFITS}{AST\_FINDFITS}. 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, AST\_FINDFITS 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 fourth (logical) argument to
+AST\_FINDFITS. A value of .TRUE.\ is returned to indicate success. If
+a suitable card cannot be found, AST\_FINDFITS returns a value of
+.FALSE.\ 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
+AST\_FINDFITS finds is useful if you want to replace that card with a
+new one, as in this example:
+
+\small
+\begin{terminalv}
+ CHARACTER * ( 80 ) NEWCARD
+ LOGICAL JUNK
+
+ ...
+
+ JUNK = AST_FINDFITS( FITSCHAN, 'AIRMASS', CARD, .FALSE., STATUS )
+ CALL AST_PUTFITS( FITSCHAN, NEWCARD, .TRUE., STATUS )
+\end{terminalv}
+\normalsize
+
+Here, AST\_FINDFITS is used to search for a card with the keyword
+AIRMASS. If the card is found, \htmlref{AST\_PUTFITS}{AST\_PUTFITS} 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{AST\_DELFITS}{AST\_DELFITS}, which deletes the current card:
+
+\small
+\begin{terminalv}
+ IF ( AST_FINDFITS( FITSCHAN, 'BSCALE', CARD, .FALSE., STATUS ) ) THEN
+ CALL AST_DELFITS( FITSCHAN, STATUS )
+ END IF
+\end{terminalv}
+\normalsize
+
+This deletes the first card, if any, with the BSCALE keyword.
+
+Requesting that AST\_FINDFITS 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}
+ 4 CONTINUE
+ IF ( AST_FINDFITS( FITSCHAN, 'CD%6d', CARD, .TRUE., STATUS ) ) THEN
+ <process the card's contents>
+ GO TO 4
+ END IF
+\end{terminalv}
+\normalsize
+
+For further details of keyword templates, see the description of
+AST\_FINDFITS in \appref{ss:functiondescriptions}.
+
+\subsection{\label{ss:fitssourceandsink}Source and Sink Routines for FitsChans}
+
+The use of source and sink routines 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 routines, 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 these routines, as arguments
+to the constructor function \htmlref{AST\_FITSCHAN}{AST\_FITSCHAN} when you create the FitsChan
+(\secref{ss:creatingafitschan}). The source routine 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 routine 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 routines 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. This
+affects the way the card contents are passed, so the routines
+themselves are slightly different. The following is therefore the
+FitsChan equivalent of the Channel SOURCE routine given in
+\secref{ss:channelsource}:
+
+\small
+\begin{terminalv}
+ INTEGER FUNCTION FITSSOURCE( CARD, STATUS )
+ CHARACTER * ( 80 ) CARD
+ INTEGER STATUS
+
+ READ( 1, '(A)', END = 99 ) CARD
+ FITSSOURCE = 1
+ RETURN
+
+ 99 FITSSOURCE = 0
+ END
+\end{terminalv}
+\normalsize
+
+Here, the FITS card contents are returned \emph{via} the CARD argument
+(the \htmlref{AST\_PUTLINE}{AST\_PUTLINE} routine should not be used) and the function returns
+1 to indicate that a card has been read. A value of zero is returned
+if there are no more cards to read.
+
+The sink routine for a FitsChan is also a little different
+(\emph{c.f.}\ the SINK routine in~\secref{ss:channelsink}), as
+follows:
+
+\small
+\begin{terminalv}
+ SUBROUTINE FITSSINK( CARD, STATUS )
+ CHARACTER * ( 80 ) CARD
+ INTEGER STATUS
+
+ WRITE( 2, '(A)' ) CARD
+
+ END
+\end{terminalv}
+\normalsize
+
+The contents of the FITS card being written are passed \emph{via}\ the
+CARD argument (the \htmlref{AST\_GETLINE}{AST\_GETLINE} routine should not be used).
+
+Of course, both of these examples assume that you are accessing text
+files. If this is not the case, then appropriate changes to the I/O
+statements would be needed. 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 character strings holding the header cards
+and NCARDS is the number of cards, this could be done as follows:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER FITSCHAN, ICARD, NCARD, STATUS
+ CHARACTER * ( 80 ) CARDS( NCARD )
+
+ STATUS = 0
+
+ ...
+
+ FITSCHAN = AST_FITSCHAN( AST_NULL, AST_NULL, ' ', STATUS )
+ DO 1 ICARD = 1, NCARD
+ CALL AST_PUTFITS( FITSCHAN, CARDS( ICARD ), .FALSE., STATUS )
+ 1 CONTINUE
+\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}
+ CHARACTER * ( 20 ) ENCODE
+
+ ...
+
+ ENCODE = AST_GETC( FITSCHAN, 'Encoding', STATUS )
+\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 = AST_FITSCHAN( AST_NULL, AST_NULL, 'Encoding=FITS-AIPS', STATUS )
+\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{AST\_READ}{AST\_READ}. 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}
+ INTEGER WCSINFO
+
+ ...
+
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+ WCSINFO = AST_READ( FITSCHAN, STATUS )
+\end{terminalv}
+\normalsize
+
+If the pointer returned by AST\_READ 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 ( AST_GETC( WCSINFO, 'Class', STATUS ) .EQ. 'FrameSet' ) THEN
+ <the Object is a FrameSet, so use it>
+ ELSE
+ <something unexpected was read>
+ END IF
+\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{AST\_SHOW}{AST\_SHOW} (\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}
+ CHARACTER CARD * ( 80 )
+
+ ...
+
+ CALL AST_CLEAR( FITSCHAN, 'Card', STATUS )
+ 2 CONTINUE
+ IF ( AST_FINDFITS( FITSCHAN, '%f', CARD, .TRUE., STATUS ) ) THEN
+ WRITE ( *, '(A)' ) CARD
+ GO TO 2
+ END IF
+\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{AST\_READ}{AST\_READ} 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 AST\_READ 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 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{AST\_WRITE}{AST\_WRITE} can then be used to write the output WCS
+information into the FitsChan:
+
+\small
+\begin{terminalv}
+ INTEGER NOBJ
+
+ ...
+
+
+ CALL AST_SET( FITSCHAN, 'Card=1, Encoding=' // ENCODE, STATUS )
+ NOBJ = AST_WRITE( FITSCHAN, WCSINFO, STATUS )
+\end{terminalv}
+\normalsize
+
+The value returned by AST\_WRITE (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
+AST\_WRITE
+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.
+ CALL AST_SET( FITSCHAN, 'Card=1, Encoding=FITS-WCS', STATUS )
+ IF ( AST_WRITE( FITSCHAN, WCSINFO, STATUS ) .EQ. 0 ) THEN
+
+* 2.
+ CALL AST_SETC( FITSCHAN, 'Encoding', ENCODE, STATUS )
+ IF ( AST_WRITE( FITSCHAN, WCSINFO, STATUS ) .EQ. 0 ) THEN
+
+* 3.
+ CALL AST_SET( FITSCHAN, 'Encoding=NATIVE', STATUS )
+ NOBJ = AST_WRITE( FITSCHAN, WCSINFO, STATUS )
+ END IF
+ END IF
+\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 AST\_WRITE, 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 routine written in Fortran. You write
+this routine 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 routine 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 routines in Fortran, 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 routine 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 routines), 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 routine 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 Routine}
+
+The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate
+transformation routine. This should have a calling interface like the
+\htmlref{AST\_TRANN}{AST\_TRANN} function provided by AST (\emph{q.v.}). Here is a simple
+example of a suitable transformation routine which transforms
+coordinates by squaring them:
+\xlabel{SqrTran}
+
+\small
+\begin{terminalv}
+ SUBROUTINE SQRTRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD,
+ : NCOORD_OUT, OUTDIM, OUT, STATUS )
+ INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS
+ DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT )
+ LOGICAL FORWARD
+
+ INCLUDE 'AST_PAR'
+ DOUBLE PRECISION X
+ INTEGER COORD, POINT
+
+* Forward transformation.
+ IF ( FORWARD ) THEN
+ DO 2 POINT = 1, NPOINT
+ DO 1 COORD = 1, NCOORD_IN
+ X = IN( POINT, COORD )
+ IF ( X .EQ. AST__BAD ) THEN
+ OUT( POINT, COORD ) = AST__BAD
+ ELSE
+ OUT( POINT, COORD ) = X * X
+ ENDIF
+ 1 CONTINUE
+ 2 CONTINUE
+
+* Inverse transformation.
+ ELSE
+ DO 4 POINT = 1, NPOINT
+ DO 3 COORD = 1, NCOORD_IN
+ X = IN( POINT, COORD )
+ IF ( X .LT. 0.0D0 .OR. X .EQ. AST__BAD ) THEN
+ OUT( POINT, COORD ) = AST__BAD
+ ELSE
+ OUT( POINT, COORD ) = SQRT( X )
+ ENDIF
+ 3 CONTINUE
+ 4 CONTINUE
+ ENDIF
+ END
+\end{terminalv}
+\normalsize
+
+As you can see, the routine 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 routine. 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 routine so
+that it can handle arbitrary dimensionality, as here.
+
+Before using an incoming coordinate, the routine 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
+routine 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 held in common
+blocks. Remember, however, that whatever facilities the
+transformation routine requires must be available in every program
+which uses it.
+
+Generally, it is not a good idea to retain context information within
+a transformation routine. 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 routine, it should set its
+STATUS argument 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). The AST\_\_ITFER error value is defined in the AST\_ERR
+include file.
+
+\subsection{\label{ss:registeringintramaps}Registering a Transformation Routine}
+
+Having written your coordinate transformation routine, the next step
+is to register it with AST. Registration is performed using
+\htmlref{AST\_INTRAREG}{AST\_INTRAREG}, as follows:
+
+\small
+\begin{terminalv}
+ EXTERNAL SQRTRAN
+
+ CHARACTER * ( 80 ) 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/' //
+ 'sun210.htx/?xref_SqrTran'
+
+ CALL AST_INTRAREG( 'SqrTran', 2, 2, SQRTRAN, 0,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+\end{terminalv}
+\normalsize
+
+Note that the transformation routine must also appear in a Fortran
+EXTERNAL statement.
+
+The first argument to AST\_INTRAREG is a name by which the
+transformation routine will be known. This will be used when we come
+to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you
+base this on the actual routine name and make this sufficiently
+unusual that it is unlikely to clash with any other routines in most
+people's software.
+
+The next two arguments specify the number of input and output
+coordinates which the transformation routine 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 routine 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 routine 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 routine, 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 routine 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 routine, 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 routine been registered, creating an \htmlref{IntraMap}{IntraMap}
+from it is simple:
+
+\small
+\begin{terminalv}
+ INTEGER INTRAMAP
+
+ ...
+
+ INTRAMAP = AST_INTRAMAP( 'SqrTran', 2, 2, ' ', STATUS );
+\end{terminalv}
+\normalsize
+
+We simply use the \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} constructor function and pass it the
+name of the transformation routine to use. This name is the same (case
+sensitive) one that we associated with the routine when we registered
+it using \htmlref{AST\_INTRAREG}{AST\_INTRAREG} (\secref{ss:registeringintramaps}).
+
+You can, of course, register any number of transformation routines and
+select which one to use whenever you create an IntraMap. You can also
+create any number of independent IntraMaps using each transformation
+routine. In this sense, each transformation routine 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 routine that has not yet
+been registered.
+
+The second and third arguments to AST\_INTRAMAP 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 routine was registered.
+
+The penultimate 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 Routines}
+
+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 routine. Consider
+the following, for example:
+
+\small
+\begin{terminalv}
+ SUBROUTINE POLY3TRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD,
+ : NCOORD_OUT, OUTDIM, OUT, STATUS )
+ INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS
+ DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT )
+ LOGICAL FORWARD
+
+ INCLUDE 'AST_PAR'
+ DOUBLE PRECISION X
+ INTEGER POINT
+
+* Forward transformation.
+ DO 1 POINT = 1, NPOINT
+ X = IN( POINT, 1 )
+ IF ( X .EQ. AST__BAD ) THEN
+ OUT( POINT, 1 ) = AST__BAD
+ ELSE
+ OUT( POINT, 1 ) =
+ : 6.18D0 + X * ( 0.12D0 + X * ( -0.003D0 + X * 0.0000101D0 ) )
+ END IF
+ 1 CONTINUE
+ END
+\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 routine, this is
+indicated via the FLAGS argument to \htmlref{AST\_INTRAREG}{AST\_INTRAREG}, as follows:
+
+\small
+\begin{terminalv}
+ EXTERNAL POLY3TRAN
+
+ ...
+
+ CALL AST_INTRAREG( 'Poly3Tran', 1, 1, POLY3TRAN, AST__NOINV,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+\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 by summing them 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
+routine. It is not necessary to impose this restriction, however, if
+the transformation routine 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 routine by
+supplying the value AST\_\_ANY for the number of input and/or output
+coordinates, as follows:
+
+\small
+\begin{terminalv}
+ CALL AST_INTRAREG( 'SqrTran', AST__ANY, AST__ANY, SQRTRAN, 0,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+\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}
+ INTEGER INTRAMAP1, INTRAMAP2
+
+ ...
+
+ INTRAMAP1 = AST_INTRAMAP( 'SqrTran', 1, 1, ' ', STATUS )
+ INTRAMAP2 = AST_INTRAMAP( 'SqrTran', 3, 3, 'Invert=1', STATUS )
+\end{terminalv}
+\normalsize
+
+It is possible to fix either the number of input or output coordinates
+(by supplying an explicit number to \htmlref{AST\_INTRAREG}{AST\_INTRAREG}), 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 = AST_INTRAMAP( 'SqrTran', 1, 2, ' ', STATUS )
+\end{terminalv}
+\normalsize
+
+will be accepted without error, although the transformation routine
+cannot actually handle such a combination sensibly. If this is
+important, it would be worth adding a check within the transformation
+routine itself, so that the error would be detected when it came to be
+used.
+
+\subsection{\label{ss:intraflag}Adapting a Transformation Routine to Individual IntraMaps}
+
+In the examples given so far, our coordinate transformation routines
+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 routine to invoke any other AST routine on
+the IntraMap, and this permits enquiries about its attributes. The
+transformation routine'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 routine 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 routine, 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 = AST_INTRAMAP( 'MyTran', 2, 2, 'IntraFlag=A', STATUS )
+ INTRAMAP2 = AST_INTRAMAP( 'MyTran', 2, 2, 'IntraFlag=B', STATUS )
+\end{terminalv}
+\normalsize
+
+The transformation routine may then enquire the value of the IntraFlag
+attribute (\emph{e.g.}\ using AST\_GETC 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{AST\_SIMPLIFY}{AST\_SIMPLIFY} (\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 routine, for example:
+
+\small
+\begin{terminalv}
+ SUBROUTINE MAXTRAN( THIS, NPOINT, NCOORD_IN, INDIM, IN, FORWARD,
+ : NCOORD_OUT, OUTDIM, OUT, STATUS )
+ INTEGER THIS, NPOINT, NCOORD_IN, INDIM, NCOORD_OUT, OUTDIM, STATUS
+ DOUBLE PRECISION IN( INDIM, NCOORD_IN ), OUT( OUTDIM, NCOORD_OUT )
+ LOGICAL FORWARD
+
+ INCLUDE 'AST_PAR'
+ DOUBLE PRECISION HI, X
+ INTEGER COORD, POINT
+
+* Forward transformation.
+ IF ( FORWARD ) THEN
+ DO 2 POINT = 1, NPOINT
+ HI = AST__BAD
+ DO 1 COORD = 1, NCOORD_IN
+ X = IN( POINT, COORD )
+ IF ( X .NE. AST__BAD ) THEN
+ IF ( X .GT. HI .OR. HI .EQ. AST__BAD ) HI = X
+ END IF
+ 1 CONTINUE
+ 2 CONTINUE
+
+* Inverse transformation.
+ ELSE
+ DO 4 COORD = 1, NCOORD_OUT
+ DO 3 POINT = 1, NPOINT
+ OUT( POINT, COORD ) = IN( POINT, 1 )
+ 3 CONTINUE
+ 4 CONTINUE
+ END IF
+ END
+\end{terminalv}
+\normalsize
+
+This routine 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 IN holds the original ``output''
+coordinates when applying the inverse transformation and OUT holds the
+original ``input'' coordinates.}
+
+If this routine 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{AST\_INTRAREG}{AST\_INTRAREG} to indicate what simplification (if any) is
+possible. For example, to register the above transformation routine,
+we might use:
+
+\small
+\begin{terminalv}
+ EXTERNAL MAXTRAN
+
+ ...
+
+ CALL AST_INTRAREG( 'MaxTran', AST__ANY, 1, MAXTRAN, AST__SIMPIF,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+\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 sum of both values.
+
+In practice, some judgement is usually necessary when deciding whether
+to allow simplification. For example, seen in one light our SQRTRAN
+routine (\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 routine 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 routine
+which it uses is not stored with it. To do so is impossible, because
+the routine 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 routine 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 routine. If it
+does not have access to this routine, 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 routine for more
+information.
+
+However, if the necessary transformation routine 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 routine 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 routines 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 Routines 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
+routines 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 routine any number of times, so long
+as it is performed using an identical invocation of \htmlref{AST\_INTRAREG}{AST\_INTRAREG} 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 routine 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 routine, perhaps as follows:
+
+\small
+\begin{terminalv}
+ SUBROUTINE MYTRANS( STATUS )
+ INTEGER STATUS
+
+ INCLUDE 'AST_PAR'
+ EXTERNAL MAXTRAN, POLY3TRAN, SQRTRAN
+
+ ...
+
+ CALL AST_INTRAREG( 'MaxTran', AST__ANY, 1, MAXTRAN, AST__SIMPIF,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+
+ ...
+
+ CALL AST_INTRAREG( 'Poly3Tran', 1, 1, POLY3TRAN, AST__NOINV,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+
+ ...
+
+ CALL AST_INTRAREG( 'SqrTran, 2, 2, SQRTRAN, 0,
+ : PURPOSE, AUTHOR, CONTACT, STATUS )
+ END
+\end{terminalv}
+\normalsize
+
+You can then simply invoke this routine wherever necessary. It is, in
+fact, particularly important to register all relevant transformation
+routines 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 routines 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{AST\_MARK}{AST\_MARK},
+which is supplied with a set of physical coordinates at which to place
+the markers:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+ INTEGER NCOORD, NMARK, TYPE, STATUS
+ DOUBLE PRECISION IN( NMARK, NCOORD )
+
+ STATUS = 0
+
+ ...
+
+ CALL AST_MARK( PLOT, NMARK, NCOORD, NMARK, IN, TYPE, STATUS )
+\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{AST\_DISTANCE}{AST\_DISTANCE} 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{AST\_CURVE}{AST\_CURVE} as follows:
+
+\small
+\begin{terminalv}
+ DOUBLE PRECISION START( NCOORD ), FINISH( NCOORD )
+
+ ...
+
+ CALL AST_CURVE( PLOT, START, FINISH, STATUS )
+\end{terminalv}
+\normalsize
+
+Here, START and FINISH are arrays containing the starting and
+finishing coordinates of the curve. The \htmlref{AST\_OFFSET}{AST\_OFFSET} and AST\_DISTANCE
+routines 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{AST\_POLYCURVE}{AST\_POLYCURVE}. This has the same effect as a sequence of calls to
+AST\_CURVE, but allows you to supply a whole set of points at the same
+time. AST\_POLYLINE then joins them, in sequence, using geodesic
+curves:
+
+\small
+\begin{terminalv}
+ INTEGER NPOINT
+ DOUBLE PRECISION COORDS( NPOINT, NCOORD )
+
+ ...
+
+ CALL AST_POLYCURVE( PLOT, NPOINT, NCOORD, NPOINT, COORDS, STATUS )
+\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} routine 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{AST\_CURVE}{AST\_CURVE} and
+\htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} (\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{AST\_GRIDLINE}{AST\_GRIDLINE} routine allows these curves to be drawn, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER AXIS
+ DOUBLE PRECISION LENGTH
+
+ ...
+
+ CALL AST_GRIDLINE( PLOT, AXIS, START, LENGTH, STATUS )
+\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{AST\_GENCURVE}{AST\_GENCURVE},
+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.
+AST\_GENCURVE,
+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
+AST\_GENCURVE,
+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{AST\_CLIP}{AST\_CLIP} routine, as follows:
+
+\small
+\begin{terminalv}
+ INTEGER IFRAME, NAXES
+ DOUBLE PRECISION LBND( NAXES ), UBND( NAXES )
+
+ ...
+
+ CALL AST_CLIP( PLOT, IFRAME, LBND, UBND, STATUS )
+\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 routines. 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{AST\_CLIP}{AST\_CLIP}---\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{AST\_GETMAPPING}{AST\_GETMAPPING}) 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{AST\_DISTANCE}{AST\_DISTANCE} and \htmlref{AST\_OFFSET}{AST\_OFFSET}
+routines will compute distances and offsets in physical coordinate
+space, and \htmlref{AST\_FORMAT}{AST\_FORMAT} 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{AST\_BORDER}{AST\_BORDER} routine 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. AST\_BORDER requires only a
+pointer to the Plot and the usual STATUS argument:
+
+\small
+\begin{terminalv}
+ LOGICAL HOLES
+
+ ...
+
+ HOLES = AST_BORDER( PLOT, STATUS )
+\end{terminalv}
+\normalsize
+
+It returns a logical 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
+.TRUE.. Otherwise, it will draw a simple rectangular border and return
+.FALSE..
+
+\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{AST\_TEXT}{AST\_TEXT}, for example:
+
+\small
+\begin{terminalv}
+ CHARACTER * ( 20 ) TEXT
+ DOUBLE PRECISION POS( NCOORD )
+ REAL UP( 2 )
+ DATA UP / 0.0, 1.0 /
+
+ ...
+
+ CALL AST_TEXT( PLOT, TEXT, POS, UP, 'TL', STATUS )
+\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 penultimate 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 routine available is \htmlref{AST\_GRID}{AST\_GRID}, 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} and a STATUS argument:
+
+\small
+\begin{terminalv}
+ CALL AST_GRID( PLOT, STATUS )
+\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{AST\_TEXT}{AST\_TEXT}.
+
+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.
+Currently, it is not possible to write such ``grf modules'' in Fortran.
+If you want to use wrapper functions written in Fortran, then you must
+use the \htmlref{AST\_GRFSET}{AST\_GRFSET} method as described below.
+
+\item The
+AST\_GRFSET
+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
+the reference documentation for the AST\_GRFSET 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 AST Include Files}
+
+
+The include files provided for use with Fortran are:
+
+\begin{quote}
+\begin{description}
+\item[AST\_PAR]\mbox{}\\
+Declares the types of all AST functions and defines parameter
+constants, except those that identify error values.
+
+\item[AST\_ERR]\mbox{}\\
+Defines parameter constants to represent the various error values to
+which the AST error status may be set when an error occurs
+(\secref{ss:errordetection}).
+\end{description}
+\end{quote}
+
+References to AST include files should be in upper case. Most modern
+Fortran compilers allow the directory to be specified as a command line
+option:
+
+\small
+\begin{terminalv}
+f77 prog.f -I/star/include -o prog
+\end{terminalv}
+\normalsize
+
+If you are using such a compiler then your Fortran source code should,
+for instance, include:
+
+\small
+\begin{terminalv}
+ INCLUDE 'AST_PAR'
+\end{terminalv}
+\normalsize
+
+(that is, there is no need to include the directory within the INCLUDE
+statement). If your compiler does not provide such an option then your
+source code must contain an absolute file name identifying the directory
+where the include files reside, for instance:
+
+\small
+\begin{terminalv}
+ INCLUDE '/star/include/AST_PAR'
+\end{terminalv}
+\normalsize
+
+
+\subsection{\label{ss:linking}Linking with AST Facilities}
+
+Fortran programs may be linked with AST 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}
+f77 prog.f -L/star/lib `ast_link` -o prog
+\end{terminalv}
+\normalsize
+
+On Linux systems you should usually use \verb+g77 -fno-second-underscore+ in
+place of \verb+f77+ - see \xref{``Software development on Linux''}{sun212}
+{software_development_on_linux} in \xref{SUN/212}{sun212}{}.
+
+
+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.}
+
+\begin{small}
+\begin{terminalv}
+f77 prog.f -L/star/lib `ast_link -pgplot` -o prog
+\end{terminalv}
+\end{small}
+
+again using \verb+g77 -fno-second-underscore+ in place of \verb+f77+
+on Linux systems.
+
+
+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.f `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.
+ Moc - An arbitrary region within a SkyFrame
+ 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
+ ChebyMap - N-dimensional Chebyshev 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 Routine Descriptions}
+\small
+\sstroutine{
+ AST\_SET
+}{
+ Set attribute values for an Object
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_SET( THIS, SETTINGS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ SETTINGS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing a comma-separated list of
+ attribute settings in the form described above.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ CALL AST\_SET( MAP, \texttt{'} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{'} , STATUS )
+ }{
+ Sets the Report attribute for Object MAP to the value 1 and
+ the Zoom attribute to 25.0.
+ }
+ \sstexamplesubsection{
+ CALL AST\_SET( FRAME, \texttt{'} Label( 1 ) =Offset from cluster axis\texttt{'} , STATUS )
+ }{
+ Sets the Label(1) attribute for Object FRAME to a suitable
+ string.
+ }
+ }
+ \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.
+
+ \sstitem
+ An error will result if an attempt is made to set a value for
+ a read-only attribute.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDCELL
+}{
+ Adds a single HEALPix cell into an existing Moc
+}{
+ \sstdescription{
+ This function modifies a \htmlref{Moc}{Moc} by combining it with a single
+ specified HEALPix cell. The way in which they are combined is
+ determined by the
+ CMODE parameter.
+ }
+ \sstinvocation{
+ CALL AST\_ADDCELL( THIS, CMODE, ORDER, NPIX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ CMODE = INTEGER (Given)
+ }{
+ Indicates how the Moc and specified cell are to be combined. Any
+ of the following values may be supplied:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_AND: If the specified cell is included in the Moc, it is
+ removed. Otherwise the Moc is left unchanged.
+
+ \sstitem
+ AST\_\_OR: If the specified cell is not included in the Moc, it is
+ added. Otherwise the Moc is left unchanged.
+
+ \sstitem
+ AST\_\_XOR: The specified cell is toggled - it is removed from
+ the Moc if originally present, and it is added to the Moc if not
+ originally present.
+ }
+ }
+ \sstsubsection{
+ ORDER = INTEGER (Given)
+ }{
+ The HEALPix order of the cell. An error is reported if this is
+ higher than the maximum order allowed in the Moc (as given by its
+ \htmlref{MaxOrder}{MaxOrder} attribute). If no value has been set for the MaxOrder
+ attribute, calling this method causes it to be set to the supplied
+ order value. So the highest order cells should usually be added
+ first.
+ }
+ \sstsubsection{
+ NPIX = INTEGER$*$8 (Given)
+ }{
+ The \texttt{"} npix\texttt{"} value identifying the required cell (see the MOC
+ recommendation for more details).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDCOLUMN
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_ADDCOLUMN( THIS, NAME, TYPE, NDIM, DIMS, UNIT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Table}{Table}.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The column name. Trailing spaces are ignored (all other spaces
+ are significant). The supplied string is converted to upper case.
+ }
+ \sstsubsection{
+ TYPE = INTEGER (Given)
+ }{
+ The data type associated with the column. See \texttt{"} Applicability:\texttt{"}
+ below.
+ }
+ \sstsubsection{
+ NDIM = INTEGER (Given)
+ }{
+ 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( NDIM ) = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A string specifying the units of the column. Supply a blank
+ string if the column is unitless.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Table
+ }{
+ Tables can hold columns with any of the following data types -
+ AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+ INTEGER$*$2),
+ AST\_\_BYTETYPE (for
+ bytes),
+ 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{AST\_MAPPUTU}{AST\_MAPPUTU}).
+ }
+ \sstsubsection{
+ \htmlref{FitsTable}{FitsTable}
+ }{
+ FitsTables can hold columns with any of the following data types -
+ AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+ INTEGER$*$2),
+ AST\_\_BYTETYPE (for
+ bytes),
+ AST\_\_DOUBLETYPE (for double
+ precision floating point), AST\_\_FLOATTYPE (for single
+ precision floating point), AST\_\_STRINGTYPE (for character string).
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This
+ routine
+ 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{
+ AST\_ADDFRAME
+}{
+ Add a Frame to a FrameSet to define a new coordinate system
+}{
+ \sstdescription{
+ This routine 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 routine
+ may also be used to merge two FrameSets, or to append extra axes
+ to every Frame in a FrameSet.
+ }
+ \sstinvocation{
+ CALL AST\_ADDFRAME( THIS, IFRAME, MAP, FRAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ Pointer to a Mapping which describes how to convert
+ coordinates from the old coordinate system (described by the
+ Frame with index IFRAME) 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 IFRAME is equal to AST\_\_ALLFRAMES.
+ }
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ Pointer to a Frame that describes the new coordinate system.
+ Any class of Frame may be supplied (including Regions and
+ FrameSets).
+
+ This routine may also be used to merge two FrameSets by
+ supplying a pointer to a second FrameSet for this argument
+ (see the Notes section for details).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Deep copies of the supplied
+ MAPPING and FRAME
+ 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
+ IFRAME argument to specify the base Frame or the current
+ Frame respectively.
+
+ \sstitem
+ This routine 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 IFRAME argument. 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
+ FRAME argument, this is treated as a request to merge a pair of
+ FrameSets. This is done by appending all the new Frames (in the
+ FRAME 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 IFRAME argument (in the original FrameSet) and the current
+ Frame of the FRAME 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
+ IFRAME,
+ 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
+ FRAME.
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ before being stored in the FrameSet.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDMOCDATA
+}{
+ Adds a FITS binary table into an existing Moc
+}{
+ \sstdescription{
+ This function modifies a \htmlref{Moc}{Moc} by combining it with a binary data array
+ describing a MOC read from a FITS binary table. The way in which they
+ are combined is determined by the
+ CMODE parameter.
+ }
+ \sstinvocation{
+ CALL AST\_ADDMOCDATA( THIS, CMODE, NEGATE, MAXORDER, LEN, NBYTE, DATA,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ CMODE = INTEGER (Given)
+ }{
+ Indicates how the Moc and data are to be combined. Any of the
+ following values may be supplied:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_AND: The modified Moc is the intersection of the original
+ Moc and the data.
+
+ \sstitem
+ AST\_\_OR: The modified Moc is the union of the original Moc and
+ the data.
+
+ \sstitem
+ AST\_\_XOR: The modified Moc is the exclusive disjunction of the
+ original Moc and the data.
+ }
+ }
+ \sstsubsection{
+ NEGATE = LOGICAL (Given)
+ }{
+ If
+ .FALSE.,
+ the cells added to the Moc will be those included in the
+ supplied data array.
+ If
+ .TRUE.,
+ the cells added to the Moc will be those not included in the
+ supplied data array.
+ }
+ \sstsubsection{
+ MAXORDER = INTEGER (Given)
+ }{
+ The maximum HEALPix order to use. If a negative value is supplied,
+ the maximum order will be determined by searching the data array
+ (this will take extra time). In either case, if a value has already
+ been set for the \htmlref{MaxOrder}{MaxOrder} attribute in the Moc, then the attribute
+ value is used in preference to the value supplied for this parameter.
+ Any HEALPix cells in the data array that refer to an order greater
+ than
+ MAXORDER
+ are ignored.
+ }
+ \sstsubsection{
+ LEN = INTEGER (Given)
+ }{
+ The length of the supplied array (i.e. the number of 4 or 8 byte
+ integer values it contains). Note, this class only supports binary
+ MOCs with lengths that can be represented in a 4 byte signed
+ integer.
+ }
+ \sstsubsection{
+ NBYTE = INTEGER (Given)
+ }{
+ The number of bytes in each integer value stored in the supplied
+ array. Must be 4 or 8.
+ }
+ \sstsubsection{
+ DATA( $*$ ) = BYTE (Given)
+ }{
+ The
+ data array holding a description of a MOC in the form used by
+ FITS binary tables. See the IVOA MOC recommendation for details.
+ The values in this array are signed integers, each with the
+ number of bytes specified by parameter
+ NBYTE.
+ The number of bytes in this array should be at least
+ LEN$*$NBYTE.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If no value has yet been set for attribute MaxOrder, then this
+ function will automatically set it to the value supplied for
+ MAXORDER,
+ or to the largest order present in the supplied binary MOC if
+ MAXORDER is negative.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDMOCSTRING
+}{
+ Adds a JSON or string-encoded MOC into an existing Moc
+}{
+ \sstdescription{
+ This function modifies a \htmlref{Moc}{Moc} by combining it with the MOC described
+ by the supplied string - assumed to be encoded using either the string
+ or JSON serialisation described in the MOC recommendation. The way in
+ which they are combined is determined by the
+ CMODE parameter.
+ }
+ \sstinvocation{
+ CALL AST\_ADDMOCSTRING( THIS, CMODE, NEGATE, MAXORDER, LEN, STRING,
+ JSON, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ CMODE = INTEGER (Given)
+ }{
+ Indicates how the supplied MOC is to be combined with the
+ existing Moc. Any of the following values may be supplied:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_AND: The modified Moc is the intersection of the original
+ Moc and the sipplied MOC.
+
+ \sstitem
+ AST\_\_OR: The modified Moc is the union of the original Moc and
+ the supplied MOC.
+
+ \sstitem
+ AST\_\_XOR: The modified Moc is the exclusive disjunction of the
+ original Moc and the supplied MOC.
+ }
+ }
+ \sstsubsection{
+ NEGATE = LOGICAL (Given)
+ }{
+ If
+ .FALSE.,
+ the cells added to the existing Moc will be those included in the
+ supplied MOC.
+ If
+ .TRUE.,
+ the cells added to the existing Moc will be those not included in the
+ supplied MOC.
+ }
+ \sstsubsection{
+ MAXORDER = INTEGER (Given)
+ }{
+ The maximum HEALPix order to use. If a negative value is supplied,
+ the maximum order will be determined by searching the supplied MOC
+ (this will take extra time). In either case, if a value has already
+ been set for the \htmlref{MaxOrder}{MaxOrder} attribute in the Moc, then the attribute
+ value is used in preference to the value supplied for this parameter.
+ Any HEALPix cells in the supplied MOC that refer to an order greater
+ than
+ MAXORDER
+ are ignored.
+ }
+ \sstsubsection{
+ LEN = INTEGER (Given)
+ }{
+ The number of characters to read from the supplied string. If
+ this is greater than the length of the string, it is ignored and the
+ whole string is read.
+ }
+ \sstsubsection{
+ STRING = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The
+ array of characters holding the supplied MOC. It should be
+ encoded using either the string or JSON serialisation described
+ in the MOC recommendation. The used serialisation is determined
+ from the first non-blank character, which should be either a
+ curly brace (\texttt{'} \{\texttt{'} - JSON serialisation) or a digit (string
+ serialisation).
+ }
+ \sstsubsection{
+ JSON = LOGICAL (Returned)
+ }{
+ A
+ boolean flag indicating if the supplied string was interpreted
+ using the JSON (.TRUE.) or string (.FALSE.) serialisation.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If no value has yet been set for attribute MaxOrder, then this
+ function will automatically set it to the value supplied for
+ MAXORDER,
+ or to the largest order present in the supplied string MOC if
+ MAXORDER is negative.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDPARAMETER
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_ADDPARAMETER( THIS, NAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Table}{Table}.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The parameter name. Trailing spaces are ignored (all other spaces
+ are significant). The supplied string is converted to upper case.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Unlike columns, the definition of a parameter does not specify its type,
+ size or dimensionality.
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDPIXELMASK$<$X$>$
+}{
+ Add a set of pixels to a Moc
+}{
+ \sstdescription{
+ This is a set of functions that modifies a \htmlref{Moc}{Moc} by combining it
+ with a subset of the pixel positions contained within a supplied
+ 2-dimensional array. A \htmlref{FrameSet}{FrameSet} must be supplied describing the World
+ Coordinate Systems associated with the array. The current \htmlref{Frame}{Frame} of
+ this FrameSet must be a \htmlref{SkyFrame}{SkyFrame} or a \htmlref{CmpFrame}{CmpFrame} containing a SkyFrame.
+
+ The subset of pixels to be combined with the Moc are selected using
+ the VALUE and OPER
+ parameters. The way in which the existing Moc and the selected pixels
+ are combined together is determined by the
+ CMODE parameter.
+
+ An adaptive alogorithm is used to find the HEALPix cells that are
+ inside the selected area in the pixel array. An initial grid,
+ corresponding to the HEALPix cells at the order given by the Moc\texttt{'} s
+ \texttt{"} \htmlref{MinOrder}{MinOrder}\texttt{"} attribute, is placed over the pixel array. Each of these
+ cells is tested at 9 positions (corners, edge-centres and cell-centre).
+ If all 9 positions are inside the selected area of pixels, then the
+ whole cell is assumed to be inside. If no positions are inside the
+ selected area, then the whole cell is assumed to be outside. If there
+ is a mix of inside and outside positions, the cell is divided into
+ four sub-cells at HEALPix order \texttt{"} MinOrder$+$1\texttt{"} , and the same test is
+ applied to each sub-cell in turn. When the HEALPix order reaches the
+ value of the Moc\texttt{'} s \texttt{"} \htmlref{MaxOrder}{MaxOrder}\texttt{"} attribute, each cell is tested only at
+ the cell centre, and is assumed to be inside the selected area if the
+ cell centre is inside the selected area.
+
+ This process means that contiguous \texttt{"} islands\texttt{"} or \texttt{"} holes\texttt{"} in the
+ supplied pixel mask may be missed if they are smaller than the cell
+ size associated with HEALPix order \texttt{"} MinOrder\texttt{"} .
+
+ If no value has yet been set for the MaxOrder attribute, then this
+ function will automatically set it to the smallest value that results
+ in the cells in the Moc being no larger than half the size of the pixels
+ in the centre of the array. Note, if the value set for attribute
+ MinOrder is greater than or equal to MaxOrder, a value of
+ (MaxOrder-1) will be used in place of MinOrder.
+
+ You should use a function which matches the numerical type of the
+ data you are processing by replacing $<$X$>$ in the generic function
+ name
+ AST\_ADDPIXELMASK$<$X$>$
+ are procesing data with type
+ REAL, you should use the function AST\_ADDPIXELMASKR
+ (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to
+ other numerical types).
+ }
+ \sstinvocation{
+ CALL AST\_ADDPIXELMASK$<$X$>$( THIS, CMODE, WCS, VALUE, OPER, FLAGS,
+ BADVAL, ARRAY, DIMS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ CMODE = INTEGER (Given)
+ }{
+ Indicates how the Moc and select pixels are to be combined. Any of the
+ following values may be supplied:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_AND: The modified Moc is the intersection of the original
+ Moc and the selected pixels.
+
+ \sstitem
+ AST\_\_OR: The modified Moc is the union of the original Moc and
+ the selected pixels.
+
+ \sstitem
+ AST\_\_XOR: The modified Moc is the exclusive disjunction of the
+ original Moc and the selected pixels.
+ }
+ }
+ \sstsubsection{
+ WCS = AstFrameSet $*$ (Given)
+ }{
+ Pointer to a FrameSet defining the World Coordinate Systems
+ associated with the image. The current Frame should be a SkyFrame
+ or a CmpFrame containing a SkyFrame. The base Frame should have
+ the same number of axes as the current Frame and should represent
+ \texttt{"} grid\texttt{"} coordinates within a pixel array (i.e. the first pixel is
+ centred at (1.0,1.0,...) and the distance between pixel centres
+ is 1.0 on both axes). The array supplied for parameter
+ ARRAY
+ is assumed to be a 2-dimensional slice from this array, spanned
+ by the grid axes corresponding to the SkyFrame axes.
+ }
+ \sstsubsection{
+ VALUE = $<$Xtype$>$ (Given)
+ }{
+ A data value that specifies the selected pixels. See parameter
+ OPER.
+ }
+ \sstsubsection{
+ OPER = INTEGER (Given)
+ }{
+ Indicates how the
+ VALUE
+ parameter is used to select the required pixels. It can
+ have any of the following values:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_LT: select pixels with value less than VALUE.
+
+ \sstitem
+ AST\_\_LE: select pixels with value less than or equal to VALUE.
+
+ \sstitem
+ AST\_\_EQ: select pixels with value equal to VALUE.
+
+ \sstitem
+ AST\_\_NE: select pixels with value not equal to VALUE.
+
+ \sstitem
+ AST\_\_GE: select pixels with value greater than or equal to VALUE.
+
+ \sstitem
+ AST\_\_GT: select pixels with value greater than VALUE.
+ }
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ The sum of a set of flag values which may be used to
+ provide additional control over the 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{
+ BADVAL = $<$Xtype$>$ (Given)
+ }{
+ This parameter should have the same type as the elements of
+ the data array. It specifies the value used to flag missing
+ data (bad pixels). Such pixels are never included in the Moc.
+
+ If the AST\_\_USEBAD flag is set via the FLAGS parameter,
+ then this value is used to test for bad pixels in the
+ supplied data array.
+ }
+ \sstsubsection{
+ ARRAY( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ The
+ 2-dimensional data array. 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
+ AST\_ADDPIXELMASKR, the type of each array element should be REAL).
+
+ The storage order of data within this array should be such that the
+ index of the first grid dimension varies most rapidly (i.e.
+ normal Fortran array storage order).
+ }
+ \sstsubsection{
+ DIMS( 2 ) = INTEGER (Given)
+ }{
+ An array
+ containing the length of each pixel axis, in pixels.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstdiytopic{
+ Control Flags
+ }{
+ The following flags are defined in the AST\_PAR include file and
+ may be used to provide additional control over the process.
+ Having selected a set of flags, you should supply the
+ sum of their values via the FLAGS parameter:
+
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_USEBAD: Indicates that there may be bad pixels in the
+ input array which must be recognised by comparing with the
+ value given for BADVAL.
+ If this flag is not set, all input values are treated literally.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate masking function, you should
+ replace $<$X$>$ in the generic function name AST\_ADDPIXELMASK$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ UI: INTEGER (treated as unsigned)
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ US: INTEGER$*$2 (short integer, treated as unsigned)
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_ADDPIXELMASKD would be used to process DOUBLE
+ PRECISION data, while AST\_ADDPIXELMASKS would be used to process
+ short integer data (stored in an INTEGER$*$2 array), etc.
+
+ For compatibility with other Starlink facilities, the codes W
+ and UW are provided as synonyms for S and US respectively (but
+ only in the Fortran interface to AST).
+ }
+}
+\sstroutine{
+ AST\_ADDREGION
+}{
+ Add a Region into a Moc
+}{
+ \sstdescription{
+ This function modifies a \htmlref{Moc}{Moc} by combining it with a supplied \htmlref{Region}{Region}.
+ The Region must be defined within a \htmlref{SkyFrame}{SkyFrame}, or within a \htmlref{CmpFrame}{CmpFrame} that
+ contains a SkyFrame. The Region will be converted to ICRS before being
+ combined with the Moc. The way in which they are combined is determined
+ by the
+ CMODE parameter.
+
+ Note, since Moc is a subclass of Region this method can be used to add
+ a Moc into another Moc. In such cases, the data is transferred from
+ one Moc to another directly. For other classes of Region an adaptive
+ algorithm is used to find the HEALPix cells that are inside the Region.
+ An initial grid, corresponding to the HEALPix cells at the order given
+ by the Moc\texttt{'} s \texttt{"} \htmlref{MinOrder}{MinOrder}\texttt{"} attribute, is placed over the bounding box of
+ the supplied Region. Each of these cells is tested at 9 positions
+ (corners, edge-centres and cell-centre). If all 9 positions are inside
+ the supplied Region, then the whole cell is assumed to be inside the
+ Region. If no positions are inside the supplied Region, then the whole
+ cell is assumed to be outside the Region. If there is a mix of inside
+ and outside positions, the cell is divided into four sub-cells at
+ HEALPix order \texttt{"} MinOrder$+$1\texttt{"} , and the same test is applied to each
+ sub-cell in turn. When the HEALPix order reaches the value of the
+ Moc\texttt{'} s \texttt{"} \htmlref{MaxOrder}{MaxOrder}\texttt{"} attribute, each cell is tested only at the cell
+ centre, and is assumed to be inside the Region if the cell centre is
+ in the Region.
+
+ This process means that contiguous \texttt{"} islands\texttt{"} or \texttt{"} holes\texttt{"} in the
+ supplied region may be missed if they are smaller than the cell size
+ associated with HEALPix order \texttt{"} MinOrder\texttt{"} .
+ }
+ \sstinvocation{
+ CALL AST\_ADDREGION( THIS, CMODE, REGION, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ CMODE = INTEGER (Given)
+ }{
+ Indicates how the Moc and Region are to be combined. Any of the
+ following values may be supplied:
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_AND: The modified Moc is the intersection of the original
+ Moc and the Region.
+
+ \sstitem
+ AST\_\_OR: The modified Moc is the union of the original Moc and
+ the Region.
+
+ \sstitem
+ AST\_\_XOR: The modified Moc is the exclusive disjunction of the
+ original Moc and the Region.
+ }
+ }
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the Region to be combined with the Moc.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ When combining the Region with the Moc, it is assumed that the Moc
+ has not been inverted (i.e. the current value of the Moc\texttt{'} s \texttt{'} \htmlref{Negated}{Negated}\texttt{'}
+ attribute is ignored).
+
+ \sstitem
+ If no value has yet been set for attribute MaxOrder, then this
+ function will automatically set it to a value that depends on the
+ class of Region being added. If the Region being added is another
+ Moc, the MaxOrder attribute of the Moc is used. For other classes
+ of Region, the value used corresponds to the resolution closest to
+ 0.1\% of the linear size of the Region being added (determined using
+ method astGetRegionDisc).
+ }
+ }
+}
+\sstroutine{
+ AST\_ADDVARIANT
+}{
+ Store a new variant Mapping for the current Frame in a FrameSet
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_ADDVARIANT( THIS, MAP, NAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ MAP = INTEGER (Given)
+ }{
+ Pointer to a Mapping which describes how to convert
+ coordinates from the current Frame to the new variant of the
+ current Frame. If
+ AST\_\_NULL
+ is supplied, then the name associated with the currently selected
+ variant of the current Frame is set to the value supplied for
+ NAME, but no new variant is added.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The name to associate with the new variant Mapping (or the currently
+ selected variant Mapping if
+ MAP is AST\_\_NULL).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ 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{AST\_MIRRORVARIANTS}{AST\_MIRRORVARIANTS} routine
+ has been called to make the current Frame act as a mirror.
+ }
+ }
+}
+\sstroutine{
+ AST\_ANGLE
+}{
+ Calculate the angle subtended by two points at a third point
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_ANGLE( THIS, A, B, C, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ A( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+ }
+ \sstsubsection{
+ B( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute) containing the coordinates of the second point.
+ }
+ \sstsubsection{
+ C( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute) containing the coordinates of the third point.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_ANGLE = DOUBLE PRECISION
+ }{
+ 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 STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_ANNUL
+}{
+ Annul a pointer to an Object
+}{
+ \sstdescription{
+ This routine 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 routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_ANNUL( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given and Returned)
+ }{
+ The Object pointer to be annulled. A null pointer value (AST\_\_NULL)
+ is always returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an
+ error value
+ 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{
+ AST\_AXANGLE
+}{
+ Returns the angle from an axis, to a line through two points
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_AXANGLE( THIS, A, B, AXIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Frame}{Frame}.
+ }
+ \sstsubsection{
+ A( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+ }
+ \sstsubsection{
+ B( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute) containing the coordinates of the second point.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ The number of the Frame axis from which the angle is to be
+ measured (axis numbering starts at 1 for the first axis).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_AXANGLE = DOUBLE PRECISION
+ }{
+ 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 routine is the path of
+ shortest distance between two points, as defined by the
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE} 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{
+ AST\_AXDISTANCE
+}{
+ Find the distance between two axis values
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_AXDISTANCE( THIS, AXIS, V1, V2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ The index of the axis to which the supplied values refer. The
+ first axis has index 1.
+ }
+ \sstsubsection{
+ V1 = DOUBLE PRECISION (Given)
+ }{
+ The first axis value.
+ }
+ \sstsubsection{
+ V2 = DOUBLE PRECISION (Given)
+ }{
+ The second axis value.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_AXDISTANCE = DOUBLE PRECISION
+ }{
+ 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 STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_AXNORM
+}{
+ Normalise an array of axis values
+}{
+ \sstdescription{
+ This routine
+ modifies a supplied array of axis values so that they are normalised
+ in the manner indicated by
+ argument OPER.
+
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_AXNORM( THIS, AXIS, OPER, NVAL, VALUES, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ The index of the axis to which the supplied values refer. The
+ first axis has index 1.
+ }
+ \sstsubsection{
+ OPER = INTEGER (Given)
+ }{
+ Indicates the type of normalisation to be applied. If zero is
+ supplied, the normalisation will be the same as that performed by
+ routine \htmlref{AST\_NORM}{AST\_NORM}.
+ If 1 is supplied, the normalisation will be chosen automatically
+ so that the resulting list has the smallest range.
+ }
+ \sstsubsection{
+ NVAL = INTEGER (Given)
+ }{
+ The number of points in the values array.
+ }
+ \sstsubsection{
+ VALUES( NVAL ) = DOUBLE PRECISION (Given and Returned)
+ }{
+ On entry, the axis values to be normalised. Modified on exit to
+ hold the normalised values.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ SkyFrame
+ }{
+ If OPER
+ is 0, longitude values are returned in the range [0,2$*$PI].
+ If OPER
+ 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{
+ AST\_AXOFFSET
+}{
+ Add an increment onto a supplied axis value
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_AXOFFSET( THIS, AXIS, V1, DIST, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ The index of the axis to which the supplied values refer. The
+ first axis has index 1.
+ }
+ \sstsubsection{
+ V1 = DOUBLE PRECISION (Given)
+ }{
+ The original axis value.
+ }
+ \sstsubsection{
+ DIST = DOUBLE PRECISION (Given)
+ }{
+ The axis increment to add to the original axis value.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_AXOFFSET = DOUBLE PRECISION
+ }{
+ 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 STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_BBUF
+}{
+ Begin a new graphical buffering context
+}{
+ \sstdescription{
+ This routine
+ starts a new graphics buffering context. A matching call to the
+ routine \htmlref{AST\_EBUF}{AST\_EBUF}
+ should be used to end the context.
+ }
+ \sstinvocation{
+ CALL AST\_BBUF( THIS STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Plot}{Plot}.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 routine
+ to this routine
+ simply invokes the astGBBuf function in the grf module.
+ }
+ }
+}
+\sstroutine{
+ AST\_BEGIN
+}{
+ Begin a new AST context
+}{
+ \sstdescription{
+ This routine begins a new AST context. Any \htmlref{Object}{Object} pointers
+ created within this context will be annulled when it is later
+ ended using \htmlref{AST\_END}{AST\_END} (just as if \htmlref{AST\_ANNUL}{AST\_ANNUL} had been invoked),
+ unless they have first been exported using \htmlref{AST\_EXPORT}{AST\_EXPORT} or rendered
+ exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}. 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.
+ }
+ \sstinvocation{
+ CALL AST\_BEGIN( STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an
+ error value.
+
+ \sstitem
+ Contexts delimited by AST\_BEGIN and AST\_END may be nested to any
+ depth.
+ }
+ }
+}
+\sstroutine{
+ AST\_BORDER
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_BORDER( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_BORDER = LOGICAL
+ }{
+ .FALSE. 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, .TRUE. is
+ returned.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of .FALSE. will be returned if this function is invoked
+ with STATUS set to an error value, 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{
+ AST\_BOUNDINGBOX
+}{
+ Return a bounding box for previously drawn graphics
+}{
+ \sstdescription{
+ This routine 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 routine is undefined.
+ }
+ \sstinvocation{
+ CALL AST\_BOUNDINGBOX( THIS, LBND, UBND, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ LBND( 2 ) = REAL (Returned)
+ }{
+ 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( 2 ) = REAL (Returned)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ An error results if the base Frame of the Plot is not
+ 2-dimensional.
+ }
+ }
+}
+\sstroutine{
+ AST\_BOX
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_BOX( FRAME, FORM, POINT1, POINT2, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (\htmlref{Naxes}{Naxes} attribute). If
+ FORM
+ is zero, this array should contain the coordinates at the centre of
+ the box.
+ If FORM
+ is one, it should contain the coordinates at the corner of the box
+ which is diagonally opposite the corner specified by
+ POINT2.
+ }
+ \sstsubsection{
+ POINT2( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute) containing the coordinates at any corner of the
+ box.
+ }
+ \sstsubsection{
+ UNC = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_BOX = INTEGER
+ }{
+ A pointer to the new Box.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_CHANNEL
+}{
+ 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{AST\_WRITE}{AST\_WRITE}) will generate a
+ textual representation of that Object, and reading from a
+ Channel (using \htmlref{AST\_READ}{AST\_READ}) 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{"} routines 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CHANNEL( SOURCE, SINK, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SOURCE = SUBROUTINE (Given)
+ }{
+ A source routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SourceFile attribute, this routine will be used by
+ the Channel to obtain lines of input text. On each
+ invocation, it should read the next input line from some
+ external data store, and then return the resulting text to
+ the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a
+ negative line length when there are no more lines to read.
+ If an error occurs, it should set its own error status
+ argument to an error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SOURCE value,
+ and no value has been set for the SourceFile attribute,
+ the Channel will read from standard input instead.
+ }
+ \sstsubsection{
+ SINK = SUBROUTINE (Given)
+ }{
+ A sink routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SinkFile attribute, this routine will be used by
+ the Channel to deliver lines of output text. On each
+ invocation, it should obtain the next output line from the
+ AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the
+ resulting text to some external data store. If an error
+ occurs, it should set its own error status argument to an
+ error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SINK value,
+ and no value has been set for the SinkFile attribute,
+ the Channel will write to standard output instead.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CHANNEL = INTEGER
+ }{
+ A pointer to the new Channel.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The names of the routines supplied for the SOURCE and SINK
+ arguments should appear in EXTERNAL statements in the Fortran
+ routine which invokes AST\_CHANNEL. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null Object
+ pointer.
+ }
+ }
+}
+\sstroutine{
+ AST\_CHEBYDOMAIN
+}{
+ Returns the bounding box of the domain of a ChebyMap
+}{
+ \sstdescription{
+ This routine
+ returns the upper and lower limits of the box defining the domain
+ of either the forward or inverse transformation of a \htmlref{ChebyMap}{ChebyMap}. These
+ are the values that were supplied when the ChebyMap was created.
+ }
+ \sstinvocation{
+ CALL AST\_CHEBYDOMAIN( THIS, FORWARD, LBND, UBND, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the ChebyMap.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ A .TRUE.
+ value indicates that the domain of the ChebyMap\texttt{'} s
+ forward transformation is to be returned, while a zero
+ value indicates that the domain of the inverse transformation
+ should be returned.
+ }
+ \sstsubsection{
+ LBND() = DOUBLE PRECISION (Returned)
+ }{
+ An
+ array in which to return the lower axis bounds of the ChebyMap
+ domain. The number of elements should be at least equal to the
+ number of ChebyMap inputs (if
+ FORWARD is .TRUE.), or outputs (if FORWARD is .FALSE.).
+ }
+ \sstsubsection{
+ UBND() = DOUBLE PRECISION (Returned)
+ }{
+ An
+ array in which to return the upper axis bounds of the ChebyMap
+ domain. The number of elements should be at least equal to the
+ number of ChebyMap inputs (if
+ FORWARD is .TRUE.), or outputs (if FORWARD is .FALSE.).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If the requested transformation is undefined (i.e. no
+ transformation coefficients were specified when the ChebyMap was
+ created), this method returns a box determined using the
+ \htmlref{AST\_MAPBOX}{AST\_MAPBOX}
+ method on the opposite transformation, if the opposite
+ transformation is defined.
+
+ \sstitem
+ If the above procedure fails to determine a bounding box, the supplied
+ arrays are filled with AST\_\_BAD values but no error is reported.
+ }
+ }
+}
+\sstroutine{
+ AST\_CHEBYMAP
+}{
+ Create a ChebyMap
+}{
+ \sstdescription{
+ This function creates a new \htmlref{ChebyMap}{ChebyMap} and optionally initialises
+ its attributes.
+
+ A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
+ transformation. Each output coordinate is a linear combination of
+ Chebyshev polynomials of the first kind, of order zero up to a
+ specified maximum order, evaluated at the input coordinates. The
+ coefficients to be used in the linear combination are specified
+ separately for each output coordinate.
+
+ For a 1-dimensional ChebyMap, the forward transformation is defined
+ as follows:
+
+ f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
+
+ where:
+ \sstitemlist{
+
+ \sstitem
+ Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
+
+ \sstitem
+ T0(x\texttt{'} ) = 1
+
+ \sstitem
+ T1(x\texttt{'} ) = x\texttt{'}
+
+ \sstitem
+ Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
+
+ \sstitem
+ x\texttt{'} is the inpux axis value, x, offset and scaled to the range
+ [-1, 1] as x ranges over a specified bounding box, given when the
+ ChebyMap is created. The input positions, x, supplied to the
+ forward transformation must fall within the bounding box - bad
+ axis values (AST\_\_BAD) are generated for points outside the
+ bounding box.
+
+ }
+ For an N-dimensional ChebyMap, the forward transformation is a
+ generalisation of the above form. Each output axis value is the sum
+ of NCOEFF
+ terms, where each term is the product of a single coefficient
+ value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"} is the
+ normalised value of the i\texttt{'} th input axis value.
+
+ The forward and inverse transformations are defined independantly
+ by separate sets of coefficients, supplied when the ChebyMap is
+ created. If no coefficients are supplied to define the inverse
+ transformation, the
+ \htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}
+ method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
+ inverse transformation. The inverse transformation so generated
+ will be a Chebyshev polynomial with coefficients chosen to minimise
+ the residuals left by a round trip (forward transformation followed
+ by inverse transformation).
+ }
+ \sstinvocation{
+ RESULT = AST\_CHEBYMAP( NIN, NOUT, NCOEFF\_F, COEFF\_F, NCOEFF\_I, COEFF\_I,
+ LBND\_F, UBND\_F, LBND\_I, UBND\_I, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates.
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates.
+ }
+ \sstsubsection{
+ NCOEFF\_F = INTEGER (Given)
+ }{
+ The number of non-zero coefficients necessary to define the
+ forward transformation of the ChebyMap. If zero is supplied, the
+ forward transformation will be undefined.
+ }
+ \sstsubsection{
+ COEFF\_F( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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
+ ChebyMap output which uses the coefficient within its defining
+ expression (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).
+
+ For instance, if the ChebyMap 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 the Chebyshev
+ polynomial of power 1 evaluated at input coordinate 1, and the
+ value of the Chebyshev polynomial of power 3 evaluated at input
+ coordinate 2. 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{"} 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 = INTEGER (Given)
+ }{
+ The number of non-zero coefficients necessary to define the
+ inverse transformation of the ChebyMap. If zero is supplied, the
+ inverse transformation will be undefined.
+ }
+ \sstsubsection{
+ COEFF\_I( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ LBND\_F( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the lower bounds of the input bounding box within
+ which the ChebyMap is defined. This argument is not used or
+ accessed if
+ NCOEFF\_F is zero.
+ If supplied, the array should contain
+ \texttt{"} NIN\texttt{"} elements.
+ }
+ \sstsubsection{
+ UBND\_F( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the upper bounds of the input bounding box within
+ which the ChebyMap is defined. This argument is not used or
+ accessed if
+ NCOEFF\_F is zero.
+ If supplied, the array should contain
+ \texttt{"} NIN\texttt{"} elements.
+ }
+ \sstsubsection{
+ LBND\_I( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the lower bounds of the output bounding box within
+ which the ChebyMap is defined. This argument is not used or
+ accessed if
+ NCOEFF\_I is zero.
+ If supplied, the array should contain
+ \texttt{"} NOUT\texttt{"} elements.
+ }
+ \sstsubsection{
+ UBND\_I( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the upper bounds of the output bounding box within
+ which the ChebyMap is defined. This argument is not used or
+ accessed if
+ NCOEFF\_I is zero.
+ If supplied, the array should contain
+ \texttt{"} NOUT\texttt{"} elements.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing an optional comma-separated
+ list of attribute assignments to be used for initialising the
+ new ChebyMap. The syntax used is identical to that for the
+ \htmlref{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CHEBYMAP = INTEGER
+ }{
+ A pointer to the new ChebyMap.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CIRCLE
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_CIRCLE( FRAME, FORM, CENTRE, POINT, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of
+ the circle or sphere.
+ }
+ \sstsubsection{
+ POINT( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ If FORM
+ 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 FORM
+ 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 = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CIRCLE = INTEGER
+ }{
+ A pointer to the new Circle.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CIRCLEPARS
+}{
+ Returns the geometric parameters of an Circle
+}{
+ \sstdescription{
+ This routine
+ returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}.
+ }
+ \sstinvocation{
+ CALL AST\_CIRCLEPARS( THIS, CENTRE, RADIUS, P1, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ CENTRE( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ 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 = DOUBLE PRECISION (Returned)
+ }{
+ Returned holding the radius of the Circle, as an geodesic
+ distance in the associated coordinate system.
+ }
+ \sstsubsection{
+ P1( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_CLEAR
+}{
+ Clear attribute values for an Object
+}{
+ \sstdescription{
+ This routine 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{AST\_TEST}{AST\_TEST} function to return the value .FALSE. for
+ the attribute, indicating that no value has been set.
+ }
+ \sstinvocation{
+ CALL AST\_CLEAR( THIS, ATTRIB, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ ATTRIB = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing a comma-separated list of the
+ names of the attributes to be cleared.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine 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{
+ AST\_CLIP
+}{
+ Set up or remove clipping for a Plot
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_CLIP( THIS, IFRAME, LBND, UBND, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping
+ limits supplied in LBND and UBND (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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each axis of the clipping Frame
+ (identified by the index IFRAME). This should contain the
+ lower bound, on each axis, of the region which is to remain
+ visible (unclipped).
+ }
+ \sstsubsection{
+ UBND( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each axis of the clipping Frame
+ (identified by the index IFRAME). This should contain the
+ upper bound, on each axis, of the region which is to remain
+ visible (unclipped).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Only one clipping Frame may be active at a time. This routine
+ will deactivate any previously-established clipping Frame before
+ setting up new clipping limits.
+
+ \sstitem
+ The clipping produced by this routine 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{AST\_PLOT}{AST\_PLOT}). 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
+ LBND and UBND). 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{AST\_TRAN2}{AST\_TRAN2}), 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{
+ AST\_CLONE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CLONE( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Original pointer to the Object.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This function applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CLONE = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CMPFRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CMPFRAME( FRAME1, FRAME2, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME1 = INTEGER (Given)
+ }{
+ Pointer to the first component Frame.
+ }
+ \sstsubsection{
+ FRAME2 = INTEGER (Given)
+ }{
+ Pointer to the second component Frame.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CMPFRAME = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_CMPMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CMPMAP( MAP1, MAP2, SERIES, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ MAP1 = INTEGER (Given)
+ }{
+ Pointer to the first component Mapping.
+ }
+ \sstsubsection{
+ MAP2 = INTEGER (Given)
+ }{
+ Pointer to the second component Mapping.
+ }
+ \sstsubsection{
+ SERIES = LOGICAL (Given)
+ }{
+ If a .TRUE. value is given for this argument, the two
+ component Mappings will be connected in series. A
+ .FALSE. value requests that they are connected in parallel.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CMPMAP = INTEGER
+ }{
+ 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
+ AST\_CMPMAP (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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CMPREGION
+}{
+ 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{AST\_CONVERT}{AST\_CONVERT}
+ 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
+ AST\_CONVERT
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CMPREGION( REGION1, REGION2, OPER, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION1 = INTEGER (Given)
+ }{
+ Pointer to the first component Region.
+ }
+ \sstsubsection{
+ REGION2 = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CMPREGION = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_COLUMNNAME
+}{
+ 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
+ one to 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_COLUMNNAME( THIS, INDEX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ INDEX = INTEGER (Given)
+ }{
+ The index into the list of columns. The first column has index
+ one, and the last has index \texttt{"} Ncolumn\texttt{"} .
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_COLUMNNAME = CHARACTER $*$ ( AST\_\_SZCHR )
+ }{
+ The
+ upper case column name.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A blank string will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any
+ reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_COLUMNNULL
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_COLUMNNULL( THIS, COLUMN, SET, NEWVAL, WASSET, HASNULL,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Table}{Table}.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ SET = LOGICAL (Given)
+ }{
+ If .TRUE., the value supplied for argument NEWVAL
+ will be stored as the current null value, replacing any value
+ set by a previous call to this function.
+ If .FALSE., the value supplied for argument NEWVAL
+ is ignored and the current null value is left unchanged.
+ }
+ \sstsubsection{
+ NEWVAL = INTEGER (Given)
+ }{
+ The new null value to use. Ignored if
+ SET is .FALSE.
+ 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 = LOGICAL (Returned)
+ }{
+ .TRUE. will be returned
+ if the returned null value was set previously via an
+ earlier invocation of this function.
+ .FALSE.
+ is returned otherwise. If the named column does not exist, or an
+ error occurs, a value of
+ .FALSE. is returned.
+ }
+ \sstsubsection{
+ HASNULL = LOGICAL (Returned)
+ }{
+ .TRUE. will be returned
+ if and only if the named column currently contains any values
+ equal to the null value on exit (i.e.
+ NEWVAL if SET is .TRUE.
+ 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
+ .FALSE. is returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_COLUMNNULL = INTEGER
+ }{
+ 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
+ SET is .TRUE., the supplied NEWVAL
+ 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{
+ AST\_COLUMNSHAPE
+}{
+ Returns the shape of the values in a named column
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}.
+ }
+ \sstinvocation{
+ CALL AST\_COLUMNSHAPE( THIS, COLUMN, MXDIM, NDIM, DIMS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the upper case name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ MXDIM = INTEGER (Given)
+ }{
+ The length of the
+ DIMS array.
+ }
+ \sstsubsection{
+ NDIM = INTEGER (Returned)
+ }{
+ The
+ number of dimensions spanned by values in the named column.
+ This will be zero if the column contains scalar values.
+ }
+ \sstsubsection{
+ DIMS( MXDIM ) = INTEGER (Returned)
+ }{
+ An
+ array in which to return the length of each dimension. Any
+ excess trailing elements will be filled with the value 1.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ NDIM and the supplied values in DIMS
+ are left unchanged.
+
+ \sstitem
+ A value of zero is returned for
+ NDIM
+ if an error occurs.
+ }
+ }
+}
+\sstroutine{
+ AST\_COLUMNSIZE
+}{
+ 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{AST\_GETCOLUMNDATA}{AST\_GETCOLUMNDATA}.
+ }
+ \sstinvocation{
+ RESULT = AST\_COLUMNSIZE( THIS, COLUMN, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Table}{Table}.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL} = INTEGER
+ }{
+ 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{
+ AST\_CONVERT
+}{
+ 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.
+ AST\_CONVERT 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CONVERT( FROM, TO, DOMAINLIST, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FROM = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 a blank 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 FROM or TO arguments is a pointer to a
+ FrameSet, then AST\_CONVERT will attempt to convert from the
+ coordinate system described by the current Frame of the FROM
+ FrameSet to that described by the current Frame of the TO
+ 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 DOMAINLIST 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 DOMAINLIST 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 DOMAINLIST field, the conversion path is
+ accepted. Otherwise, the next DOMAINLIST 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 DOMAINLIST 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{
+ AST\_CONVERT = INTEGER
+ }{
+ 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 FROM argument. Frame number 2
+ (its current Frame) will describe the destination coordinate
+ system, corresponding to the TO argument. 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{AST\_TRAN2}{AST\_TRAN2}), 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 = AST\_CONVERT( A, B, \texttt{'} \texttt{'} , STATUS )
+ }{
+ Attempts to convert between the coordinate systems represented
+ by A and B (assumed to be Frames). If successful, a FrameSet
+ is returned via the CVT pointer which may be used to apply the
+ conversion to sets of coordinates (e.g. using AST\_TRAN2).
+ }
+ \sstexamplesubsection{
+ CVT = AST\_CONVERT( \htmlref{AST\_SKYFRAME}{AST\_SKYFRAME}( \texttt{'} \texttt{'} , STATUS ), AST\_SKYFRAME( \texttt{'} \htmlref{Equinox}{Equinox}=2005\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ Creates a FrameSet which describes precession in the default
+ FK5 celestial coordinate system between equinoxes J2000 (also
+ the default) and J2005. The returned CVT pointer may then
+ be passed to AST\_TRAN2 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 = AST\_CONVERT( A, B, \texttt{'} SKY,DETECTOR,\texttt{'} , STATUS )
+ }{
+ Attempts to convert between the coordinate systems
+ represented by the current Frames of A and B
+ (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 CVT indicates whether conversion was
+ possible and will have the value AST\_\_NULL if it was not. If
+ conversion was possible, CVT will point at a new FrameSet
+ describing the conversion.
+
+ The Base attributes of the two FrameSets
+ will be set by AST\_CONVERT 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 TO 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 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CONVEX$<$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
+ STARPIX.
+
+ You should use a function which matches the numerical type of the
+ data you are processing by replacing $<$X$>$ in the generic function
+ name
+ AST\_CONVEX$<$X$>$
+ are procesing data with type
+ REAL, you should use the function AST\_CONVEXR
+ (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to
+ other numerical types).
+ }
+ \sstinvocation{
+ RESULT = AST\_CONVEX$<$X$>$( VALUE, OPER, ARRAY, LBND, UBND, STARPIX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ VALUE = $<$Xtype$>$ (Given)
+ }{
+ A data value that specifies the pixels to be included within the
+ convex hull.
+ }
+ \sstsubsection{
+ OPER = INTEGER (Given)
+ }{
+ Indicates how the
+ VALUE
+ 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 VALUE.
+
+ \sstitem
+ AST\_\_LE: include pixels with value less than or equal to VALUE.
+
+ \sstitem
+ AST\_\_EQ: include pixels with value equal to VALUE.
+
+ \sstitem
+ AST\_\_NE: include pixels with value not equal to VALUE.
+
+ \sstitem
+ AST\_\_GE: include pixels with value greater than or equal to VALUE.
+
+ \sstitem
+ AST\_\_GT: include pixels with value greater than VALUE.
+ }
+ }
+ \sstsubsection{
+ ARRAY( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_CONVEXR, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ LBND( 2 ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND( 2) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND and UBND 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. 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
+ STARPIX.
+ }
+ \sstsubsection{
+ STARPIX = LOGICAL (Given)
+ }{
+ A flag indicating the nature of the pixel coordinate system used
+ to describe the vertex positions in the returned Polygon. If
+ .TRUE.,
+ 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 .FALSE.,
+ the definition of pixel coordinate used by other AST functions
+ such as AST\_RESAMPLE, AST\_MASK,
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CONVEX$<$X$>$ = INTEGER
+ }{
+ A pointer to the required Polygon.
+ AST\_\_NULL
+ is returned without error if the array contains no pixels that
+ satisfy the criterion specified by
+ VALUE and OPER.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_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 AST\_CONVEX$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ UI: INTEGER (treated as unsigned)
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ US: INTEGER$*$2 (short integer, treated as unsigned)
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_CONVEXD would be used to process DOUBLE
+ PRECISION data, while AST\_CONVEXS would be used to process
+ short integer data (stored in an INTEGER$*$2 array), etc.
+
+ For compatibility with other Starlink facilities, the codes W
+ and UW are provided as synonyms for S and US respectively (but
+ only in the Fortran interface to AST).
+ }
+}
+\sstroutine{
+ AST\_COPY
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_COPY( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object to be copied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This function applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_COPY = INTEGER
+ }{
+ Pointer to the new Object.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_CURRENTTIME
+}{
+ Return the current system time
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_CURRENTTIME( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the TimeFrame.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_CURRENTTIME = DOUBLE
+ }{
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Values of AST\_\_BAD will be returned if this function is
+ invoked with STATUS set to an error value, 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{
+ AST\_CURVE
+}{
+ Draw a geodesic curve
+}{
+ \sstdescription{
+ This routine 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{AST\_DISTANCE}{AST\_DISTANCE} 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{AST\_CLIP}{AST\_CLIP}.
+
+ If you need to draw many geodesic curves end-to-end, then the
+ \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} routine is equivalent to repeatedly calling
+ AST\_CURVE, but will usually be more efficient.
+
+ If you need to draw curves which are not geodesics, see \htmlref{AST\_GENCURVE}{AST\_GENCURVE}
+ or \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}.
+ }
+ \sstinvocation{
+ CALL AST\_CURVE( THIS, START, FINISH, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ START( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array, with one element for each axis of the Plot, giving
+ the physical coordinates of the second point on the geodesic
+ curve.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ No curve is drawn if either of the START or FINISH 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{
+ AST\_DECOMPOSE
+}{
+ Decompose a Mapping into two component Mappings
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_DECOMPOSE( THIS, MAP1, MAP2, SERIES, INVERT1, INVERT2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping.
+ }
+ \sstsubsection{
+ MAP1 = INTEGER (Returned)
+ }{
+ A pointer to first component
+ Mapping.
+ }
+ \sstsubsection{
+ MAP2 = INTEGER (Returned)
+ }{
+ A pointer to second component
+ Mapping.
+ }
+ \sstsubsection{
+ SERIES = LOGICAL (Returned)
+ }{
+ Indicates if the
+ component Mappings are applied in series or parallel. A .TRUE.
+ 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 = INTEGER (Returned)
+ }{
+ The value of the \htmlref{Invert}{Invert} attribute to be used with MAP1.
+ }
+ \sstsubsection{
+ INVERT2 = INTEGER (Returned)
+ }{
+ 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 AST\_\_NULL. 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 AST\_\_NULL.
+ }
+ }
+ \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{
+ AST\_DELETE
+}{
+ Delete an Object
+}{
+ \sstdescription{
+ This routine 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{AST\_BEGIN}{AST\_BEGIN}/\htmlref{AST\_END}{AST\_END}
+ (together with \htmlref{AST\_CLONE}{AST\_CLONE} and \htmlref{AST\_ANNUL}{AST\_ANNUL} if necessary).
+ }
+ \sstinvocation{
+ CALL AST\_DELETE( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given and Returned)
+ }{
+ Pointer to the Object to be deleted. A null pointer value
+ (AST\_\_NULL) is always returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an error
+ value
+ on entry, although no further error report will be
+ made if it subsequently fails under these circumstances.
+ }
+ }
+}
+\sstroutine{
+ AST\_DELFITS
+}{
+ Delete the current FITS card in a FitsChan
+}{
+ \sstdescription{
+ This routine 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{AST\_FINDFITS}{AST\_FINDFITS} (if only the FITS keyword is
+ known).
+
+ After deletion, the following card becomes the current card.
+ }
+ \sstinvocation{
+ CALL AST\_DELFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_DISTANCE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_DISTANCE( THIS, POINT1, POINT2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ POINT1( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+ }
+ \sstsubsection{
+ POINT2( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ containing the coordinates of the second point.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_DISTANCE = DOUBLE PRECISION
+ }{
+ 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 STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_DOWNSIZE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_DOWNSIZE( THIS, MAXERR, MAXVERT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Polygon.
+ }
+ \sstsubsection{
+ MAXERR = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_DOWNSIZE = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_DSBSPECFRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_DSBSPECFRAME( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_DSBSPECFRAME = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_EBUF
+}{
+ End the current graphical buffering context
+}{
+ \sstdescription{
+ This routine
+ ends the current graphics buffering context. It should match a
+ corresponding call to the
+ AST\_EBUF routine.
+ }
+ \sstinvocation{
+ CALL AST\_EBUF( THIS STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Plot}{Plot}.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 routine
+ simply invokes the astGEBuf function in the grf module.
+ }
+ }
+}
+\sstroutine{
+ AST\_ELLIPSE
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_ELLIPSE( FRAME, FORM, CENTRE, POINT1, POINT2, UNC, OPTIONS,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array
+ containing the coordinates at the centre of
+ the ellipse.
+ }
+ \sstsubsection{
+ POINT1( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ If FORM
+ 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 FORM
+ 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( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ If FORM
+ is zero, this array should containing the coordinates at some other
+ point on the circumference of the ellipse, distinct from
+ POINT1. If FORM
+ 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
+ POINT1
+ 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 = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_ELLIPSE = INTEGER
+ }{
+ A pointer to the new Ellipse.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_ELLIPSEPARS
+}{
+ Returns the geometric parameters of an Ellipse
+}{
+ \sstdescription{
+ This routine
+ returns the geometric parameters describing the supplied ellipse.
+ }
+ \sstinvocation{
+ CALL AST\_ELLIPSEPARS( THIS, CENTRE, A, B, ANGLE, P1, P2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ CENTRE( 2 ) = DOUBLE PRECISION (Returned)
+ }{
+ The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays.
+ }
+ \sstsubsection{
+ A = DOUBLE PRECISION (Returned)
+ }{
+ Returned holding the half-length of the first axis of the
+ ellipse.
+ }
+ \sstsubsection{
+ B = DOUBLE PRECISION (Returned)
+ }{
+ Returned holding the half-length of the second axis of the
+ ellipse.
+ }
+ \sstsubsection{
+ ANGLE = DOUBLE PRECISION (Returned)
+ }{
+ If the coordinate system in which the Ellipse is defined has
+ axes (X,Y), then
+ ANGLE
+ 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( 2 ) = DOUBLE PRECISION (Returned)
+ }{
+ An array in which to return the coordinates at one of the two ends
+ of the first axis of the ellipse.
+ }
+ \sstsubsection{
+ P2( 2 ) = DOUBLE PRECISION (Returned)
+ }{
+ An array in which to return the coordinates at one of the two ends
+ of the second axis of the ellipse.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_EMPTYFITS
+}{
+ Delete all cards in a FitsChan
+}{
+ \sstdescription{
+ This routine
+ deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}.
+ }
+ \sstinvocation{
+ CALL AST\_EMPTYFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This method simply deletes the cards currently in the FitsChan.
+ Unlike \htmlref{AST\_WRITEFITS}{AST\_WRITEFITS},
+ 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{
+ AST\_END
+}{
+ End an AST context
+}{
+ \sstdescription{
+ This routine ends an AST context which was
+ begun with a matching invocation of \htmlref{AST\_BEGIN}{AST\_BEGIN}. Any \htmlref{Object}{Object}
+ pointers created within this context will be annulled (just as
+ if \htmlref{AST\_ANNUL}{AST\_ANNUL} had been invoked) and will cease to be valid
+ afterwards, unless they have previously been exported using
+ \htmlref{AST\_EXPORT}{AST\_EXPORT} or rendered exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}.
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_END( STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an
+ error value.
+
+ \sstitem
+ Contexts delimited by AST\_BEGIN and AST\_END may be nested to any
+ depth.
+ }
+ }
+}
+\sstroutine{
+ AST\_ESCAPES
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_ESCAPES( NEWVAL, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NEWVAL = INTEGER (Given)
+ }{
+ 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 routine applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_ESCAPES = INTEGER
+ }{
+ The value of the flag on entry to this function.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This function also controls whether the
+ \htmlref{AST\_STRIPESCAPES}{AST\_STRIPESCAPES}
+ 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{
+ AST\_EXEMPT
+}{
+ Exempt an Object pointer from AST context handling
+}{
+ \sstdescription{
+ This routine exempts an \htmlref{Object}{Object} pointer from AST context
+ handling, as implemented by \htmlref{AST\_BEGIN}{AST\_BEGIN} and \htmlref{AST\_END}{AST\_END}. This means that
+ the pointer will not be affected when AST\_END is called and will
+ remain active until the end of the program, or until explicitly
+ annulled using \htmlref{AST\_ANNUL}{AST\_ANNUL}.
+
+ If possible, you should avoid using this routine 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 AST\_BEGIN and AST\_END.
+ }
+ \sstinvocation{
+ CALL AST\_EXEMPT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Object pointer to be exempted from context handling.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+}
+\sstroutine{
+ AST\_EXPORT
+}{
+ Export an Object pointer to an outer context
+}{
+ \sstdescription{
+ This routine 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{AST\_END}{AST\_END}), but only when the next outer context (if
+ any) ends.
+ }
+ \sstinvocation{
+ CALL AST\_EXPORT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Object pointer to be exported.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ It is only sensible to apply this routine to pointers that
+ have been created within (or exported to) the current context
+ and have not been rendered exempt using \htmlref{AST\_EXEMPT}{AST\_EXEMPT}.
+ Applying it to an unsuitable Object pointer has no effect.
+ }
+ }
+}
+\sstroutine{
+ AST\_FINDFITS
+}{
+ 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
+ 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 .FALSE. and the Card attribute
+ is set to the \texttt{"} end-of-file\texttt{"} .
+ }
+ \sstinvocation{
+ RESULT = AST\_FINDFITS( THIS, NAME, CARD, INC, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 = CHARACTER $*$ ( 80 ) (Returned)
+ }{
+ A character variable with at least 80 characters
+ in which the FITS card which is found will be returned. If
+ the search is not successful, a
+ card will not be returned.
+ }
+ \sstsubsection{
+ INC = LOGICAL (Given)
+ }{
+ If this value is .FALSE. (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 .TRUE., however, the Card
+ attribute will be incremented to identify the card which
+ follows the one found.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FINDFITS = LOGICAL
+ }{
+ .TRUE. if the search was successful, otherwise .FALSE..
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} \%f\texttt{'} , CARD, .TRUE., STATUS )
+ }{
+ 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 = AST\_FINDFITS( FITSCHAN, \texttt{'} BITPIX\texttt{'} , CARD, .TRUE., STATUS )
+ }{
+ 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 = AST\_FINDFITS( FITSCHAN, \texttt{'} COMMENT\texttt{'} , CARD, .FALSE., STATUS )
+ }{
+ Sets the Card attribute of a FitsChan to identify the next
+ COMMENT card (if any) and returns that card.
+ }
+ \sstexamplesubsection{
+ RESULT = AST\_FINDFITS( FITSCHAN, \texttt{'} CRVAL\%1d\texttt{'} , CARD, .TRUE., STATUS )
+ }{
+ 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{AST\_CLEAR}{AST\_CLEAR}). 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 .FALSE. 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{
+ AST\_FINDFRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FINDFRAME( TARGET, TEMPLATE, DOMAINLIST, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ TARGET = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 a blank string.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 DOMAINLIST 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 DOMAINLIST 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 DOMAINLIST field, it is
+ accepted. Otherwise, the next DOMAINLIST 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{
+ AST\_FINDFRAME = INTEGER
+ }{
+ 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
+ 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 = AST\_FINDFRAME( TARGET, \htmlref{AST\_FRAME}{AST\_FRAME}( 3, \texttt{'} \texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ Searches for a 3-dimensional coordinate system in the target
+ Frame (or FrameSet). No attributes have been set in the
+ template Frame (created by AST\_FRAME), 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 RESULT FrameSet.
+ }
+ \sstexamplesubsection{
+ RESULT = AST\_FINDFRAME( TARGET, \htmlref{AST\_SKYFRAME}{AST\_SKYFRAME}( \texttt{'} \texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ Searches for a celestial coordinate system in the target
+ Frame (or FrameSet). The type of celestial coordinate system
+ is unspecified, so AST\_FINDFRAME will return the first one
+ found as part of the RESULT 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 = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{MaxAxes}{MaxAxes}=100\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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 = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{System}{System}=FK5\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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 = AST\_FINDFRAME( TARGET, AST\_FRAME( 2, \texttt{'} \texttt{'} , STATUS ), \texttt{'} SKY,PIXEL,\texttt{'} , STATUS )
+ }{
+ 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 RESULT
+ 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 = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} Domain=WAVELENGTH\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ Searches for any 1-dimensional coordinate system in the
+ target which has the domain \texttt{"} WAVELENGTH\texttt{"} .
+ }
+ \sstexamplesubsection{
+ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} \texttt{'} , STATUS ), \texttt{'} WAVELENGTH\texttt{'} , STATUS )
+ }{
+ 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 DOMAINLIST string.
+ }
+ \sstexamplesubsection{
+ RESULT = AST\_FINDFRAME( TARGET, AST\_FRAME( 1, \texttt{'} MaxAxes=3\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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 RESULT
+ 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 = AST\_FINDFRAME( TARGET, AST\_SKYFRAME( \texttt{'} \htmlref{Permute}{Permute}=0\texttt{'} , STATUS ), \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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{AST\_PERMAXES}{AST\_PERMAXES}).
+ }
+ }
+ \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 TEMPLATE 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 DOMAINLIST 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 STATUS set to an error value, 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 DOMAINLIST
+ 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
+ DOMAINLIST 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{
+ AST\_FITSCHAN
+}{
+ 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{AST\_WRITE}{AST\_WRITE}) 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{AST\_FINDFITS}{AST\_FINDFITS}), new
+ cards may be inserted (\htmlref{AST\_PUTFITS}{AST\_PUTFITS}, \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}, \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}) and
+ existing ones may be deleted (\htmlref{AST\_DELFITS}{AST\_DELFITS}) or changed (AST\_SETFITS$<$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 AST\_PUTFITS, AST\_PUTCARDS, AST\_WRITE
+ 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 AST\_FINDFITS or \htmlref{AST\_READ}{AST\_READ}).
+
+ 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 AST\_READ and AST\_WRITE, when used with
+ a FitsChan, depends on the encoding in use. In general, however,
+ all use of AST\_READ 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{AST\_RETAINFITS}{AST\_RETAINFITS} routine).
+
+ 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 AST\_WRITE 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FITSCHAN( SOURCE, SINK, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SOURCE = FUNCTION (Given)
+ }{
+ A source routine, which is a function taking two arguments: a
+ character argument of length 80 to contain a FITS card, and an
+ integer error status argument. It should return an integer value.
+ 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 the contents of the card via its character
+ argument. It should return a function result of one unless
+ there are no more cards to be read, in which case it should
+ return zero. If an error occurs, it should set its error
+ status argument to an error value before returning.
+
+ If the null routine AST\_NULL is supplied as the SOURCE value,
+ the FitsChan will remain empty until cards are explicitly
+ stored in it (e.g. using AST\_PUTCARDS, AST\_PUTFITS or via the
+ SourceFile attribute).
+ }
+ \sstsubsection{
+ SINK = SUBROUTINE (Given)
+ }{
+ A sink routine, which is a subroutine which takes two
+ arguments: a character argument of length 80 to contain a
+ FITS card, and an integer error status argument. If no
+ value has been set for the SinkFile attribute, this routine
+ 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 an error occurs, it should set its error
+ status argument to an error value before returning.
+
+ If the null routine AST\_NULL is supplied as the SINK value,
+ and no value has been set for the SinkFile attribute, the
+ contents of the FitsChan will be lost when it is deleted.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+
+ Note, the FITSCHAN\_OPTIONS environment variable may be used
+ to specify default options for all newly created FitsChans.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FITSCHAN = INTEGER
+ }{
+ A pointer to the new FitsChan.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The names of the routines supplied for the SOURCE and SINK
+ arguments should appear in EXTERNAL statements in the Fortran
+ routine which invokes AST\_FITSCHAN. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \sstitem
+ No FITS \texttt{"} END\texttt{"} card will be written via the sink routine. 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.
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null Object
+ pointer.
+ }
+ }
+ \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{
+ AST\_FITSTABLE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FITSTABLE( HEADER, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ HEADER = INTEGER (Given)
+ }{
+ Pointer to an optional FitsChan containing headers to be stored
+ in the FitsTable.
+ AST\_\_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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FITSTABLE = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_FLUXFRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FLUXFRAME( SPECVAL, SPECFRM, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SPECVAL = DOUBLE PRECISION (Given)
+ }{
+ The spectral value to which the flux values refer, given in the
+ spectral coordinate system specified by
+ SPECFRM. The value supplied for the SPECVAL
+ 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{AST\_CONVERT}{AST\_CONVERT}
+ function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and
+ some other FluxFrame.
+ }
+ \sstsubsection{
+ SPECFRM = INTEGER (Given)
+ }{
+ A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system
+ in which the
+ SPECVAL
+ 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.
+ AST\_\_NULL can be supplied if AST\_\_BAD is supplied for SPECVAL.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FLUXFRAME = INTEGER
+ }{
+ A pointer to the new FluxFrame.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ When conversion between two FluxFrames is requested (as when
+ supplying FluxFrames AST\_CONVERT),
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_FORMAT
+}{
+ Format a coordinate value for a Frame axis
+}{
+ \sstdescription{
+ This function returns a character 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FORMAT( THIS, AXIS, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ The number of the Frame axis for which formatting is to be
+ performed (axis numbering starts at 1 for the first axis).
+ }
+ \sstsubsection{
+ VALUE = DOUBLE PRECISION (Given)
+ }{
+ The coordinate value to be formatted.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FORMAT = CHARACTER $*$ ( AST\_\_SZCHR )
+ }{
+ The formatted value.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A formatted value may be converted back into a numerical
+ (double precision) value using \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}.
+
+ \sstitem
+ A blank string will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any
+ reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_FRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FRAME( NAXES, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NAXES = INTEGER (Given)
+ }{
+ The number of Frame axes (i.e. the number of dimensions of
+ the coordinate space which the Frame describes).
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FRAME = INTEGER
+ }{
+ A pointer to the new Frame.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ FRAME = AST\_FRAME( 2, \texttt{'} Title=Energy Spectrum\texttt{'} , STATUS );
+ }{
+ Creates a new 2-dimensional Frame and initialises its Title
+ attribute to the string \texttt{"} Energy Spectrum\texttt{"} .
+ }
+ \sstexamplesubsection{
+ FRAME = AST\_FRAME( 2, \texttt{'} Label(1)=Energy, Label(2)=Response\texttt{'} , STATUS );
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_FRAMESET
+}{
+ 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{AST\_INVERT}{AST\_INVERT}), 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_FRAMESET( FRAME, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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{AST\_ADDFRAME}{AST\_ADDFRAME} routine.)
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_FRAMESET
+ }{
+ A pointer to the new FrameSet.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If a pointer to an existing FrameSet is given for the FRAME
+ argument, 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{AST\_COPY}{AST\_COPY}), 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GENCURVE
+}{
+ Draw a generalized curve
+}{
+ \sstdescription{
+ This routine 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{AST\_CLIP}{AST\_CLIP}.
+
+ If you need to draw simple straight lines (geodesics), \htmlref{AST\_CURVE}{AST\_CURVE}
+ or \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE} will usually be easier to use and faster.
+ }
+ \sstinvocation{
+ CALL AST\_GENCURVE( THIS, MAP )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Plot}{Plot}.
+ }
+ \sstsubsection{
+ MAP = INTEGER (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_GET$<$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, I, L or R, to obtain a result in Character, Double
+ precision, Integer, Logical or Real format, respectively.
+
+ If possible, the attribute value is converted to the type you
+ request. If conversion is not possible, an error will result.
+ }
+ \sstinvocation{
+ RESULT = AST\_GET$<$X$>$( THIS, ATTRIB, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ ATTRIB = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the name of the attribute whose
+ value is required.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ These functions apply to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GET$<$X$>$ = $<$X$>$type
+ }{
+ The attribute value, in the data type corresponding to $<$X$>$.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ WRITE( $*$, \texttt{'} (\texttt{'} \texttt{'} \htmlref{RefCount}{RefCount} = \texttt{'} \texttt{'} , A10 )\texttt{'} ) AST\_GETC( Z, \texttt{'} RefCount\texttt{'} , STATUS )
+ }{
+ Prints the RefCount attribute value for Object Z as a character
+ string.
+ }
+ \sstexamplesubsection{
+ NAXES = AST\_GETI( FRAME, \texttt{'} \htmlref{Naxes}{Naxes}\texttt{'} , STATUS )
+ }{
+ Obtains the value of the Naxes attribute for Object FRAME as an
+ integer.
+ }
+ }
+ \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 STATUS set to an error value, or if it should
+ fail for any reason. This null value is zero for numeric
+ values, .FALSE. for logical values, and blank for character values.
+
+ \sstitem
+ Numerical attribute values of zero translate to logical value
+ .FALSE. and all other numerical values translate to .TRUE..
+ }
+ }
+}
+\sstroutine{
+ AST\_GETACTIVEUNIT
+}{
+ Determines how the Unit attribute will be used
+}{
+ \sstdescription{
+ This routine
+ returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See
+ the description of the \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine
+ for a description of the ActiveUnit flag.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETACTIVEUNIT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETACTIVEUNIT = LOGICAL
+ }{
+ The current value of the ActiveUnit flag.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of .FALSE. will be returned if this function is
+ invoked with STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETCELL
+}{
+ Identify the next cell in a normalised Moc
+}{
+ \sstdescription{
+ This function returns the order and \texttt{"} npix\texttt{"} value for the cell at a
+ specified index in the normalised \htmlref{Moc}{Moc}. See the MOC recommendation
+ for more information about \texttt{"} npix\texttt{"} values and MOC normalisation.
+ }
+ \sstinvocation{
+ CALL AST\_GETCELL( THIS, ICELL, ORDER, NPIX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ ICELL = INTEGER (Given)
+ }{
+ The index of the cell for which information is required. The
+ first cell has index
+ one.
+ An error will be reported if the supplied value is greater than
+ the value of the \htmlref{MocLength}{MocLength} attribute.
+ }
+ \sstsubsection{
+ ORDER = INTEGER (Returned)
+ }{
+ Returned holding the HEALPix order of the cell at the requested
+ index.
+ }
+ \sstsubsection{
+ NPIX = INTEGER$*$8 (Returned)
+ }{
+ Returned holding the \texttt{"} npix\texttt{"} value of the cell at the requested
+ index.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETCOLUMNDATA
+}{
+ Retrieve all the data values stored in a column
+}{
+ \sstdescription{
+ This routine
+ copies all data values from a named column into a supplied buffer
+ }
+ \sstinvocation{
+ CALL AST\_GETCOLUMNDATA( THIS, COLUMN, RNULL, DNULL, MXSIZE,
+ COLDATA, NELEM, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{FitsTable}{FitsTable}.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ RNULL = REAL (Given)
+ }{
+ The value to return in
+ COLDATA
+ 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\_\_NANR
+ will cause a single precision IEEE NaN value to be used.
+ }
+ \sstsubsection{
+ DNULL = REAL (Given)
+ }{
+ The value to return in
+ COLDATA
+ 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 = INTEGER (Given)
+ }{
+ The size of the
+ COLDATA
+ array, in bytes. The amount of memory needed to hold the data
+ from a column may be determined using
+ \htmlref{AST\_COLUMNSIZE}{AST\_COLUMNSIZE}.
+ 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( $*$ ) = BYTE (Given)
+ }{
+ 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 = INTEGER (Return)
+ }{
+ The number of elements returned in the
+ COLDATA
+ array. This is the product of the number of rows returned and
+ the number of elements in each column value.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The RNULL and DNULL arguments
+ 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
+ \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL} functiom.
+ For columns holding string values, the ASCII NULL character is returned
+ for empty cells.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETFITS$<$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{"}
+ argument
+
+ depends on $<$X$>$ as follows:
+
+ \sstitemlist{
+
+ \sstitem
+ CF - DOUBLE PRECISION(2) (a 2 element array to hold the real and
+ imaginary parts of the complex value).
+
+ \sstitem
+ CI - INTEGER(2) (a 2 element array to hold the real and imaginary
+ parts of the complex value).
+
+ \sstitem
+ F - DOUBLE PRECISION.
+
+ \sstitem
+ I - INTEGER
+
+ \sstitem
+ L - LOGICAL
+
+ \sstitem
+ S - CHARACTER
+
+ \sstitem
+ CN - CHARACTER
+ }
+ }
+ \sstinvocation{
+ RESULT = AST\_GETFITS$<$X$>$( THIS, NAME, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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
+ a single dot \texttt{'} .\texttt{'}
+ is supplied, the value of the current card is returned.
+ }
+ \sstsubsection{
+ VALUE = $<$X$>$type (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETFITS$<$X$>$ = LOGICAL
+ }{
+ .FALSE.
+ is returned if the keyword was not found in the FitsChan (no error
+ is reported). Otherwise, a value of
+ .TRUE.
+ 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{AST\_TESTFITS}{AST\_TESTFITS}
+ 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
+ .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
+ AST\_GETFITSS
+ if the original string (including any trailing spaces) contains 8
+ or fewer characters. Trailing spaces are not removed from longer
+ strings.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETFRAME
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETFRAME( THIS, IFRAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETFRAME = INTEGER
+ }{
+ A pointer to the requested Frame.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+ IFRAME argument 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETGRFCONTEXT
+}{
+ Return the KeyMap that describes a Plot\texttt{'} s graphics context
+}{
+ \sstdescription{
+ This routine
+ returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing
+ routines registered using \htmlref{AST\_GRFSET}{AST\_GRFSET}.
+ This KeyMap can be used by an application to pass information to
+ the drawing routines
+ about the context in which they are being called. The contents of
+ the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETGRFCONTEXT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETGRFCONTEXT = INTEGER
+ }{
+ A pointer to the graphics context KeyMap. The returned pointer
+ should be annulled when it is no longer needed.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETLINE
+}{
+ Obtain text to be written by a Channel sink routine
+}{
+ \sstdescription{
+ This routine should only be used when implementing a routine
+ which will be passed as the SINK argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL}. It
+ should be used to obtain (from the AST library) each line of
+ text which is to be written to the external data sink. One such
+ line should be obtained in this way for each invocation of the
+ sink routine.
+ }
+ \sstinvocation{
+ CALL AST\_GETLINE( LINE, L, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ LINE = CHARACTER $*$ ( $*$ ) (Returned)
+ }{
+ The line of text to be written. Depending on the length of
+ character variable supplied, the returned text may be
+ truncated if necessary. Note, however, that it will not be
+ padded with blanks in order to fill this variable.
+ }
+ \sstsubsection{
+ L = INTEGER (Returned)
+ }{
+ The number of characters returned, which may be zero. Note
+ that characters beyond the L\texttt{'} th character in the LINE
+ variable are not modified and may therefore contain junk.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine is only available in the Fortran interface to the
+ AST library.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETMAPPING
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETMAPPING( THIS, IFRAME1, IFRAME2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME1 = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The index of the second Frame in the FrameSet. This Frame
+ describes the coordinate system for the \texttt{"} output\texttt{"} end of the
+ Mapping.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETMAPPING = INTEGER
+ }{
+ 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 IFRAME1 and IFRAME2 arguments
+ 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 arguments 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETMOCDATA
+}{
+ Get the FITS binary table data describing a Moc
+}{
+ \sstdescription{
+ This function retrieves the data values that form the FITS binary
+ table representation of the MOC and stores them in a supplied array.
+ Such a table contains a single scalar-valued column in which each
+ row holds a signed integer identifier for a single HEALPix cell,
+ following the scheme described in the MOC recommendation. Depending
+ on the order of the \htmlref{Moc}{Moc}, these integers may be 4 bytes or 8 bytes.
+
+ The number of rows in the table and the required integer data type
+ are available through the \htmlref{MocType}{MocType} and \htmlref{MocLength}{MocLength} attributes of the
+ Moc class.
+
+ The FITS headers to store in the FITS binary table can be obtained
+ using function
+ \htmlref{AST\_GETMOCHEADER}{AST\_GETMOCHEADER}.
+ }
+ \sstinvocation{
+ CALL AST\_GETMOCDATA( THIS, MXSIZE, DATA, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ MXSIZE = INTEGER (Given)
+ }{
+ The length of the supplied array in bytes. An error will be reported
+ if this value is smaller than the number required to describe the
+ Moc (the product of the MocType and MocLength attributes).
+ }
+ \sstsubsection{
+ DATA( $*$ ) = BYTE (Returned)
+ }{
+ The
+ area of memory in which to return the signed integer cell
+ identifiers. This area is assumed to contain at least
+ MXSIZE bytes.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETMOCHEADER
+}{
+ Get the FITS binary table headers describing a Moc
+}{
+ \sstdescription{
+ This function returns a \htmlref{FitsChan}{FitsChan} holding the headers that should be
+ stored in a FITS binary table extension describing the supplied \htmlref{Moc}{Moc}.
+ The data values for the extension can be obtained using method
+ \htmlref{AST\_GETMOCDATA}{AST\_GETMOCDATA}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETMOCHEADER( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETMOCSTRING
+}{
+ Get the JSON or string-encoded representation of a Moc
+}{
+ \sstdescription{
+ This function stores the JSON or string-encoded representation of
+ the supplied \htmlref{Moc}{Moc} in the supplied string buffer.
+ }
+ \sstinvocation{
+ CALL AST\_GETMOCSTRING( THIS, JSON, MXSIZE, STRING, SIZE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc.
+ }
+ \sstsubsection{
+ JSON = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ the Moc is encoded using JSON serialisation. Otherwise it is
+ encoded using string-serialisation.
+ }
+ \sstsubsection{
+ MXSIZE = INTEGER (Given)
+ }{
+ The length of the supplied string buffer in bytes. An error will
+ be reported if this value is smaller than the number required to
+ describe the Moc. However, if zero is supplied, the buffer will
+ be ignored - no string will be returned but the required size of
+ the buffer will still be returned in
+ SIZE.
+ }
+ \sstsubsection{
+ STRING( $*$ ) = BYTE (Returned)
+ }{
+ The
+ area of memory in which to return the JSON or string-encoded
+ representation of the Moc. This area is assumed to contain at least
+ MXSIZE bytes. Only used if MXSIZE is greater than zero.
+ }
+ \sstsubsection{
+ SIZE = INTEGER$*$8 (Returned)
+ }{
+ Returned holding the number of bytes needed to store the complete
+ JSON or string-encoded representation of the Moc.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETREFPOS
+}{
+ Return the reference position in a specified celestial coordinate system
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_GETREFPOS( THIS, FRM, LON, LAT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{SpecFrame}{SpecFrame}.
+ }
+ \sstsubsection{
+ FRM = INTEGER (Given)
+ }{
+ Pointer to the SkyFrame which defines the required celestial
+ coordinate system.
+ If AST\_\_NULL
+ is supplied, then the longitude and latitude values are returned
+ as FK5 J2000 RA and Dec values.
+ }
+ \sstsubsection{
+ LON = DOUBLE PRECISION (Returned)
+ }{
+ The
+ longitude of the reference point, in the coordinate system
+ represented by the supplied SkyFrame (radians).
+ }
+ \sstsubsection{
+ LAT = DOUBLE PRECISION (Returned)
+ }{
+ The
+ latitude of the reference point, in the coordinate system
+ represented by the supplied SkyFrame (radians).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Values of AST\_\_BAD will be returned if this function is
+ invoked with STATUS set to an error value, or if it should fail for
+ any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETREGIONBOUNDS
+}{
+ Returns the bounding box of Region
+}{
+ \sstdescription{
+ This routine
+ 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).
+ }
+ \sstinvocation{
+ CALL AST\_GETREGIONBOUNDS( THIS, LBND, UBND, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ LBND() = DOUBLE PRECISION (Returned)
+ }{
+ 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() = DOUBLE PRECISION (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_GETREGIONDisc
+}{
+ Returns the centre and radius of a disc containing a 2D Region
+}{
+ \sstdescription{
+ This routine
+ returns the centre and radius of a disce that just encloses the
+ supplied 2-dimensional \htmlref{Region}{Region}. The centre is returned as a pair
+ of 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).
+ }
+ \sstinvocation{
+ CALL AST\_GETREGIONDISC( THIS, CENTRE, RADIUS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ CENTRE( 2 ) = DOUBLE PRECISION (Returned)
+ }{
+ A
+ two-element array in which to return the axis values at the centre
+ of the bounding disc.
+ }
+ \sstsubsection{
+ RADIUS = DOUBLE PRECISION (Returned)
+ }{
+ The
+ radius of the bounding disc, as a geodesic distance within the
+ Frame represented by the Region. It will be returned holding
+ AST\_\_BAD If the Region is unbounded.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ An error is reported if the Region is not 2-dimensional.
+
+ \sstitem
+ The value of the Negated attribute is ignored (i.e. it is assumed that
+ the Region has not been negated).
+
+ \sstitem
+ If the Region is unbounded, the radius will be returned set to
+ AST\_\_BAD and the supplied centre axis values will be returned unchanged.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETREGIONFRAME
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETREGIONFRAME( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETREGIONFRAME = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETREGIONFRAMESET
+}{
+ 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{AST\_GETREGIONFRAME}{AST\_GETREGIONFRAME}).
+ }
+ \sstinvocation{
+ RESULT = AST\_GETREGIONFRAMESET( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETREGIONFRAMESET = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETREGIONMESH
+}{
+ Return a mesh of points covering the surface or volume of a Region
+}{
+ \sstdescription{
+ This routine
+ 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 determined by the \htmlref{MeshSize}{MeshSize} attribute.
+ }
+ \sstinvocation{
+ CALL AST\_GETREGIONMESH( THIS, SURFACE, MAXPOINT, MAXCOORD, NPOINT,
+ POINTS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ SURFACE = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ the returned points will cover the surface or the Region.
+ Otherwise, they will fill the interior of the Region.
+ }
+ \sstsubsection{
+ MAXPOINT = INTEGER (Given)
+ }{
+ If zero, the number of points in the mesh is returned in
+ NPOINT,
+ but no axis values are returned and all other parameters are ignored.
+ If not zero, the supplied value should be the length of the
+ first dimension of the POINTS
+ array. An error is reported if the number of points in the mesh
+ exceeds this number.
+ }
+ \sstsubsection{
+ MAXCOORD = INTEGER (Given)
+ }{
+ The length of the
+ second dimension of the POINTS array.
+ An error is reported if the number of axes in the supplied Region
+ exceeds this number.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Returned)
+ }{
+ The
+ number of points in the returned mesh.
+ }
+ \sstsubsection{
+ POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned)
+ }{
+ An array in which to return the coordinates values at the mesh
+ positions. These are stored such that the value of coordinate
+ number COORD for point number POINT is found in element
+ POINTS(POINT,COORD).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_GETREGIONPOINTS
+}{
+ Returns the positions that define the given Region
+}{
+ \sstdescription{
+ This routine
+ 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{"} .
+ }
+ \sstinvocation{
+ CALL AST\_GETREGIONPOINTS( THIS, MAXPOINT, MAXCOORD, NPOINT, POINTS,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ MAXPOINT = INTEGER (Given)
+ }{
+ If zero, the number of points needed to define the Region is
+ returned in
+ NPOINT,
+ but no axis values are returned and all other parameters are ignored.
+ If not zero, the supplied value should be the length of the
+ first dimension of the POINTS
+ array. An error is reported if the number of points needed to define
+ the Region exceeds this number.
+ }
+ \sstsubsection{
+ MAXCOORD = INTEGER (Given)
+ }{
+ The length of the
+ second dimension of the POINTS array.
+ An error is reported if the number of axes in the supplied Region
+ exceeds this number.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Returned)
+ }{
+ The
+ number of points defining the Region.
+ }
+ \sstsubsection{
+ POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned)
+ }{
+ An array in which to return the coordinates values at the
+ positions that define the Region. These are stored such that the
+ value of coordinate number COORD for point number POINT
+ is found in element POINTS(POINT,COORD).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ NPOINT
+ 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{AST\_DECOMPOSE}{AST\_DECOMPOSE}
+ 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
+ NPOINT
+ 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
+ NPOINT
+ 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
+ AST\_DECOMPOSE
+ 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{
+ AST\_GETSTCCOORD
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETSTCCOORD( THIS, ICOORD, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Stc.
+ }
+ \sstsubsection{
+ ICOORD = INTEGER (Given)
+ }{
+ 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 \htmlref{AST\_GETSTCNCOORD}{AST\_GETSTCNCOORD}.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETSTCCOORD = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETSTCNCOORD
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETSTCNCOORD( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Stc.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETSTCNCOORD = INTEGER
+ }{
+ The number of AstroCoords elements stored in the Stc.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Zero will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETSTCREGION
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETSTCREGION( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Stc.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETSTCREGION = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETTABLES
+}{
+ 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{AST\_PUTTABLE}{AST\_PUTTABLE} (or \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES})
+ method to store existing tables in the FitsChan, or of using the
+ \htmlref{AST\_WRITE}{AST\_WRITE}
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_GETTABLES( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GETTABLES = INTEGER
+ }{
+ A pointer to a deep copy of the KeyMap holding the tables currently
+ in the FitsChan, or
+ AST\_\_NULL
+ if the FitsChan does not contain any tables. The returned
+ pointer should be annulled using
+ \htmlref{AST\_ANNUL}{AST\_ANNUL}
+ when no longer needed.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GETUNC
+}{
+ 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{AST\_SETUNC}{AST\_SETUNC}
+ for more information about Region uncertainties and their use.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETUNC( THIS, DEF, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ DEF = LOGICAL (Given)
+ }{
+ Controls what is returned if no uncertainty information has been
+ associated explicitly with the supplied Region. If
+ .TRUE.
+ is supplied, then the default uncertainty Region used internally
+ within AST is returned (see \texttt{"} Applicability\texttt{"} below). If
+ .FALSE. is supplied, then AST\_\_NULL
+ will be returned (without error).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_GETUNC = INTEGER
+ }{
+ 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{AST\_MAPREGION}{AST\_MAPREGION}
+ 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 (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GRFPOP
+}{
+ Restore previously saved graphics functions used by a Plot
+}{
+ \sstdescription{
+ The \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH} and AST\_GRFPOP functions are intended for situations
+ where it is necessary to make temporary changes to the graphics
+ functions used by the \htmlref{Plot}{Plot}. The current functions should first be
+ saved by calling AST\_GRFPUSH. New functions should then be registered
+ using \htmlref{AST\_GRFSET}{AST\_GRFSET}. The required graphics should then be produced.
+ Finally, AST\_GRFPOP should be called to restore the original graphics
+ functions.
+ }
+ \sstinvocation{
+ CALL AST\_GRFPOP( THIS STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine returns without action if there are no snapshots to
+ restore. No error is reported in this case.
+ }
+ }
+}
+\sstroutine{
+ AST\_GRFPUSH
+}{
+ Save the current graphics functions used by a Plot
+}{
+ \sstdescription{
+ This routine 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{AST\_GRFPOP}{AST\_GRFPOP}.
+
+ The AST\_GRFPUSH and AST\_GRFPOP 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 AST\_GRFPUSH. New functions should then be registered
+ using \htmlref{AST\_GRFSET}{AST\_GRFSET}. The required graphics should then be produced.
+ Finally, AST\_GRFPOP should be called to restore the original graphics
+ functions.
+ }
+ \sstinvocation{
+ CALL AST\_GRFPUSH( THIS STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_GRFSET
+}{
+ Register a graphics routine for use by a Plot
+}{
+ \sstdescription{
+ This routine can be used to select the underlying graphics
+ routines to be used when the supplied \htmlref{Plot}{Plot} produces graphical output.
+ If this routine is not called prior to producing graphical
+ output, then the underlying graphics routines selected at
+ link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use
+ alternative graphics routines, call this routine before
+ the graphical output is created, specifying the graphics
+ routines to be used. This will register the routine for future
+ use, but the routine will not actually be used until the \htmlref{Grf}{Grf}
+ attribute is given a non-zero value.
+ }
+ \sstinvocation{
+ CALL AST\_GRFSET( THIS, NAME, FUN, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A name indicating the graphics routine to be replaced.
+ Various graphics routines are used by the
+ Plot class, and any combination of them may be supplied by calling
+ this routine once for each routine to be replaced. If any of the
+ graphics routines are not replaced in this way, the
+ corresponding routines in the graphics interface selected at
+ link-time (using the ast\_link command) are used. The allowed
+ function 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 = INTEGER FUNCTION (Given)
+ }{
+ The name of the routine to be used to provide the
+ functionality indicated by parameter NAME (the name
+ should also appear in a Fortran EXTERNAL statement in the
+ routine which invokes AST\_GRFSET).
+
+ Once a routine has been provided, the \texttt{"} null\texttt{"} routine AST\_NULL can
+ be supplied in a subsequent call to astGrfSet to reset the routine
+ to the corresponding routine in the graphics interface selected at
+ link-time. AST\_NULL is defined in the AST\_PAR include file.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_PLOT}{AST\_PLOT} call which created the Plot.
+
+ The first argument (GRFCON)
+ 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{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT} routine,
+ 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:
+
+ INTEGER FUNCTION ATTR( GRFCON, ATT, VAL, OLDVAL, PRIM )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ ATT = INTEGER (Given) - An integer identifying the required attribute.
+ The following symbolic values are defined in GRF\_PAR:
+ 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
+ VAL = DOUBLE PRECISION (Given) -
+ no value is stored.
+
+ \sstitem
+ OLDVAL = DOUBLE PRECISION (Returned) - Returned holding
+ the attribute value.
+
+ \sstitem
+ PRIM = INTEGER (Given) -
+ The sort of graphics primitive to be drawn with the new attribute.
+ Identified by the following values defined in GRF\_PAR:
+ 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.
+
+ INTEGER FUNCTION BBUF( GRFCON )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ 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:
+
+ INTEGER FUNCTION CAP( GRFCON, CAP, VALUE )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ CAP = INTEGER (Given)
+ The capability being inquired about. This will be one of the
+ following constants defined in GRF\_PAR:
+
+ }
+ GRF\_\_SCALES: This function should return a non-zero value if the
+ \texttt{"} Scales\texttt{"} function is implemented, and zero otherwise. The supplied
+ VALUE 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
+ VALUE 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 VALUE argument should be
+ ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"} and
+ \texttt{"} TxExt\texttt{"} . Otherwise, VALUE indicates whether \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"}
+ should interpret escape sequences in subsequent calls. If VALUE 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 = INTEGER (Given)
+ The use of this parameter depends on the value of CAP as
+ described above.
+
+ \sstitem
+ Returned Function Value:
+ The value returned by the function depends on the value of CAP
+ 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:
+
+ INTEGER FUNCTION EBUF( GRFCON )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ 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:
+
+ INTEGER FUNCTION FLUSH( GRFCON )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ 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:
+
+ INTEGER FUNCTION LINE( GRFCON, N, X, Y )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ N = INTEGER (Given) - The number of positions to be joined together.
+
+ \sstitem
+ X( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} x values.
+
+ \sstitem
+ Y( N ) = REAL (Given) - 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:
+
+ INTEGER FUNCTION MARK( GRFCON, N, X, Y, TYPE )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ N = INTEGER (Given) - The number of positions to be marked.
+
+ \sstitem
+ X( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} x values.
+
+ \sstitem
+ Y( N ) = REAL (Given) - An array holding the \texttt{"} n\texttt{"} y values.
+
+ \sstitem
+ TYPE = INTEGER (Given) - 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:
+
+ INTEGER FUNCTION QCH( GRFCON, CHV, CHH )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ CHV = REAL (Returned) The height of
+ characters drawn with a vertical baseline. This will be an
+ increment in the X axis.
+
+ \sstitem
+ CHH = REAL (Returned) 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:
+
+ INTEGER FUNCTION SCALES( GRFCON, ALPHA, BETA )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ ALPHA = REAL (Returned) The
+ scale for the X axis (i.e. Xnorm = alpha$*$Xworld).
+
+ \sstitem
+ BETA = REAL (Returned) 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:
+
+ INTEGER FUNCTION TEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ TEXT = CHARACTER $*$ ( $*$ ) (Given) - The string to be displayed.
+
+ \sstitem
+ X = REAL (Given) - The reference x coordinate.
+
+ \sstitem
+ Y = REAL (Given) - The reference y coordinate.
+
+ \sstitem
+ JUST = CHARACTER $*$ ( $*$ ) (Given ) - A 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 = REAL (Given) - 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
+ UPX = REAL (Given) - 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:
+
+ INTEGER FUNCTION TXEXT( GRFCON, TEXT, X, Y, JUST, UPX, UPY, XB, YB )
+
+ \sstitemlist{
+
+ \sstitem
+ GRFCON = INTEGER (Given) -
+ A KeyMap containing information passed from the calling application.
+
+ \sstitem
+ TEXT = CHARACTER $*$ ( $*$ ) (Given) - The string to be displayed.
+
+ \sstitem
+ X = REAL (Given) - The reference x coordinate.
+
+ \sstitem
+ Y = REAL (Given) - The reference y coordinate.
+
+ \sstitem
+ JUST = CHARACTER $*$ ( $*$ ) (Given ) - A 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 = REAL (Given) - The x component of the up-vector for the text.
+ See \texttt{"} Text\texttt{"} above.
+
+ \sstitem
+ UPX = REAL (Given) - The y component of the up-vector for the text.
+ See \texttt{"} Text\texttt{"} above.
+
+ \sstitem
+ XB( 4 ) = REAL (Returned) - Returned holding the x coordinate of
+ each corner of the bounding box.
+
+ \sstitem
+ YB( 4 ) = REAL (Returned) - Returned holding the y coordinate of
+ each corner of the bounding box.
+ }
+ }
+}
+\sstroutine{
+ AST\_GRID
+}{
+ Draw a set of labelled coordinate axes
+}{
+ \sstdescription{
+ This routine 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.).
+ }
+ \sstinvocation{
+ CALL AST\_GRID( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_GRIDLINE
+}{
+ Draw a grid line (or axis) for a Plot
+}{
+ \sstdescription{
+ This routine 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{AST\_GRID}{AST\_GRID} routine).
+
+ 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{AST\_CLIP}{AST\_CLIP}.
+ }
+ \sstinvocation{
+ CALL AST\_GRIDLINE( THIS, AXIS, START, LENGTH, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array, with one element for each axis of the Plot, giving
+ the physical coordinates of the start of the curve.
+ }
+ \sstsubsection{
+ LENGTH = DOUBLE PRECISION (Given)
+ }{
+ The length of curve to be drawn, given as an increment along
+ the selected physical axis. This may be positive or negative.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ No curve is drawn if the START array contains any
+ coordinates with the value AST\_\_BAD, nor if LENGTH 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{
+ AST\_GRISMMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_GRISMMAP( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GRISMMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_GetTableHeader
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_GETTABLEHEADER( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsTable.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_GetTableHeader = INTEGER
+ }{
+ A pointer to a deep copy of the FitsChan stored within the
+ FitsTable.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The returned pointer should be annulled using
+ \htmlref{AST\_ANNUL}{AST\_ANNUL}
+ 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{AST\_PUTTABLEHEADER}{AST\_PUTTABLEHEADER}.
+ }
+ }
+}
+\sstroutine{
+ AST\_HASATTRIBUTE
+}{
+ Test if an Object has a named attribute
+}{
+ \sstdescription{
+ This function returns a logical result to indicate
+ whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name.
+ }
+ \sstinvocation{
+ RESULT = AST\_HASATTRIBUTE( THIS, ATTRIB, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the first Object.
+ }
+ \sstsubsection{
+ ATTRIB = INTEGER (Given)
+ }{
+ The
+ name of the attribute to be tested.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ \htmlref{AST\_SAME}{AST\_SAME} = LOGICAL
+ }{
+ .TRUE. if the Object has the named attribute, otherwise
+ .FALSE.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of .FALSE. will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_HASCOLUMN
+}{
+ Returns a flag indicating if a column is present in a Table
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}.
+ }
+ \sstinvocation{
+ RESULT = AST\_HASCOLUMN( THIS, COLUMN, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the upper case name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of
+ .FALSE.
+ is returned for if an error occurs.
+ }
+ }
+}
+\sstroutine{
+ AST\_HASPARAMETER
+}{
+ Returns a flag indicating if a named global parameter is present in a Table
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}.
+ }
+ \sstinvocation{
+ RESULT = AST\_HASPARAMETER( THIS, PARAMETER, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ PARAMETER = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the upper case name of the parameter. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of
+ .FALSE.
+ is returned for if an error occurs.
+ }
+ }
+}
+\sstroutine{
+ AST\_IMPORT
+}{
+ Import an Object pointer to the current context
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_END}{AST\_END}).
+ }
+ \sstinvocation{
+ CALL AST\_IMPORT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Object pointer to be imported.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+}
+\sstroutine{
+ AST\_INTERSECT
+}{
+ Find the point of intersection between two geodesic curves
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_INTERSECT( THIS, A1, A2, B1, B2, CROSS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ A1( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( 2 ) = DOUBLE PRECISION (Returned)
+ }{
+ An array with one element for each Frame axis
+ in which the coordinates of the required intersection will
+ be returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ A1.
+
+ \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 routine is the path of
+ shortest distance between two points, as defined by the
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE} function.
+
+ \sstitem
+ An error will be reported if the Frame is not 2-dimensional.
+ }
+ }
+}
+\sstroutine{
+ AST\_INTERVAL
+}{
+ 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,
+ }
+ \sstinvocation{
+ RESULT = AST\_INTERVAL( FRAME, LBND, UBND, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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 = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_INTERVAL = INTEGER
+ }{
+ A pointer to the new Interval.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_INTRAMAP
+}{
+ 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 routine
+ (e.g. written in Fortran) 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{AST\_INTRAREG}{AST\_INTRAREG} before creating an IntraMap.
+ }
+ \sstinvocation{
+ RESULT = AST\_INTRAMAP( NAME, NIN, NOUT, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the name of the transformation
+ routine to use (which should previously have been registered
+ using AST\_INTRAREG). This name is case sensitive. All white
+ space will be removed before use.
+ }
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates. This must be compatible with
+ the number of input coordinates accepted by the
+ transformation routine (as specified when this routine was
+ registered using AST\_INTRAREG).
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates. This must be compatible
+ with the number of output coordinates produced by the
+ transformation routine (as specified when this routine was
+ registered using AST\_INTRAREG).
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_INTRAMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_INTRAREG
+}{
+ Register a transformation routine for use by an IntraMap
+}{
+ \sstdescription{
+ This function registers a privately-defined coordinate
+ transformation routine written in Fortran 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 Fortran routine 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 routines is required
+ before using the \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} constructor function to create an
+ IntraMap or reading an external representation of an IntraMap
+ from a \htmlref{Channel}{Channel}.
+ }
+ \sstinvocation{
+ CALL AST\_INTRAREG( NAME, NIN, NOUT, TRAN, FLAGS, PURPOSE, AUTHOR,
+ CONTACT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing a unique name to be associated
+ with the transformation routine in order to identify it. This
+ name is case sensitive. All white space will be removed
+ before use.
+ }
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates accepted by the
+ transformation routine (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 routine is able to accommodate a variable
+ number of input coordinates.
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates produced by the
+ transformation routine (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 routine is able to produce a variable
+ number of output coordinates.
+ }
+ \sstsubsection{
+ TRAN = SUBROUTINE (Given)
+ }{
+ The transformation routine to be registered. This routine
+ should perform whatever coordinate transformations are
+ required and should have an interface like \htmlref{AST\_TRANN}{AST\_TRANN} (q.v.).
+
+ This transformation routine must also appear in an EXTERNAL
+ statement in the routine which calls AST\_INTRAREG.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This value may be used to supply a set of flags which
+ describe the transformation routine 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 sum of a
+ set of flags as described in the \texttt{"} Transformation Flags\texttt{"}
+ section (below).
+ }
+ \sstsubsection{
+ PURPOSE = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing a short (one line) textual
+ comment to describe the purpose of the transformation
+ routine.
+ }
+ \sstsubsection{
+ AUTHOR = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the name of the author of the
+ transformation routine.
+ }
+ \sstsubsection{
+ CONTACT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing contact details for the author
+ of the transformation routine (e.g. an e-mail or WWW
+ address). If any IntraMap which uses this transformation
+ routine is exported as part of a dataset to an external user
+ who does not have access to the routine, then these contact
+ details should allow them to obtain the necessary code.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Beware that an external representation of an IntraMap (created
+ by writing it to a Channel) will not include the coordinate
+ transformation routine which it uses, so will only refer to the
+ routine by its name (as assigned using AST\_INTRAREG).
+ Consequently, the external representation cannot be utilised by
+ another program unless that program has also registered the same
+ transformation routine with the same name using an identical
+ invocation of AST\_INTRAREG. If no such registration has been
+ performed, then attempting to read the external representation
+ will result in an error.
+
+ \sstitem
+ You may use AST\_INTRAREG to register a transformation routine
+ 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 routine 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 routine, this may be
+ indicated by setting its STATUS argument to an error value
+ 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). The AST\_\_ITFER error
+ value is defined in the AST\_ERR include file.
+ }
+ }
+ \sstdiytopic{
+ Transformation Flags
+ }{
+ The following flags are defined in the AST\_PAR include file and
+ allow you to provide further information about the nature of the
+ transformation routine. Having selected the set of flags which
+ apply, you should supply the sum of their values as the FLAGS
+ argument to AST\_INTRAREG.
+
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_NOFWD: If this flag is set, it indicates that the
+ transformation routine 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 routine itself will not be called with its
+ FORWARD argument set to .TRUE.. By default, it is assumed that a
+ forward transformation is provided.
+
+ \sstitem
+ AST\_\_NOINV: If this flag is set, it indicates that the
+ transformation routine 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 routine itself will not be called with its
+ FORWARD argument set to .FALSE.. By default, it is assumed that
+ an inverse transformation is provided.
+
+ \sstitem
+ AST\_\_SIMPFI: You may set this flag if applying the
+ transformation routine\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{AST\_SIMPLIFY}{AST\_SIMPLIFY}). It is
+ not necessary that both transformations have actually been
+ implemented.
+
+ \sstitem
+ AST\_\_SIMPIF: You may set this flag if applying the
+ transformation routine\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 AST\_SIMPLIFY). It is
+ not necessary that both transformations have actually been
+ implemented.
+ }
+ }
+}
+\sstroutine{
+ AST\_INVERT
+}{
+ Invert a Mapping
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_INVERT( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_ISA$<$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 $<$CLASS$>$, or of any class derived from
+ it.
+ }
+ \sstinvocation{
+ RESULT = AST\_ISA$<$CLASS$>$( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ These functions apply to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_ISA$<$CLASS$>$ = LOGICAL
+ }{
+ .TRUE. if the Object belongs to the class called $<$CLASS$>$ (or to
+ a class derived from it), otherwise .FALSE..
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ MEMBER = AST\_ISAFRAME( OBJ, STATUS );
+ }{
+ Tests whether Object OBJ 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 (AST\_ISA$<$CLASS$>$) of this
+ form, where $<$CLASS$>$ should be replaced by the class name.
+
+ \sstitem
+ This function attempts to execute even if STATUS is set to an
+ error value
+ on entry, although no further error report will be made
+ if it subsequently fails under these circumstances.
+
+ \sstitem
+ A value of .FALSE. 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{
+ AST\_KEYMAP
+}{
+ 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{AST\_MAPPUT0$<$X$>$}{AST\_MAPPUT0$<$X$>$} and \htmlref{AST\_MAPPUT1$<$X$>$}{AST\_MAPPUT1$<$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),
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_KEYMAP( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAP = INTEGER
+ }{
+ A pointer to the new KeyMap.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_LINEARAPPROX
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_LINEARAPPROX( THIS, LBND, UBND, TOL, FIT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping.
+ }
+ \sstsubsection{
+ LBND( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array
+ containing the upper bounds of the box specifying the region over
+ which linearity is required.
+ }
+ \sstsubsection{
+ TOL = DOUBLE PRECISION (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array
+ 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(1) $+$ fit(4)$*$X\_in $+$ fit(5)$*$Y\_in
+
+ Y\_out = fit(2) $+$ fit(6)$*$X\_in $+$ fit(7)$*$Y\_in
+
+ Z\_out = fit(3) $+$ fit(8)$*$X\_in $+$ fit(9)$*$Y\_in
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_LINEARAPPROX = LOGICAL
+ }{
+ If the forward transformation is sufficiently linear,
+ .TRUE is returned. Otherwise .FALSE. 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{AST\_INVERT}{AST\_INVERT}
+ before invoking this function.
+
+ \sstitem
+ If a Mapping output is found to have a bad value (AST\_\_BAD) at
+ one or more of the test points used in the linearity test, then all
+ the values in the returned fit that correspond to that output are
+ set to AST\_\_BAD. However, this does not affect the linearity tests
+ on the other Mapping outputs - if they are all found to be linear
+ then usable coefficients will be returned for them in the fit, and
+ the function will return a
+ .TRUE. value.
+ Consequently, it may be necessary to check that the values in the
+ returned fit are not AST\_\_BAD before using them. If all Mapping
+ outputs generate bad values, then
+ .FALSE. is returned as the function value.
+
+ \sstitem
+ A value of .FALSE.
+ will be returned if this function is invoked
+ with the global error status set, or if it should fail for any
+ reason.
+
+ \sstitem
+ If all tested positions within the supplied box generate bad
+ output positions, then the returned function value will be
+ .FALSE.
+ However, the returned coefficients will represent a unit
+ transformation, except that the constant term for each output
+ will be set to AST\_\_BAD.
+ }
+ }
+}
+\sstroutine{
+ AST\_LUTMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_LUTMAP( NLUT, LUT, START, INC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NLUT = INTEGER (Given)
+ }{
+ The number of entries in the lookup table. This value must be
+ at least 2.
+ }
+ \sstsubsection{
+ LUT( NLUT ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the
+ lookup table entries.
+ }
+ \sstsubsection{
+ START = DOUBLE PRECISION (Given)
+ }{
+ The input coordinate value which corresponds to the first lookup
+ table entry.
+ }
+ \sstsubsection{
+ INC = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_LUTMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_MAPBOX
+}{
+ Find a bounding box for a Mapping
+}{
+ \sstdescription{
+ This routine 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 routine 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. 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.
+ }
+ \sstinvocation{
+ CALL AST\_MAPBOX( THIS, LBND\_IN, UBND\_IN, FORWARD, COORD\_OUT,
+ LBND\_OUT, UBND\_OUT, XL, XU, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping.
+ }
+ \sstsubsection{
+ LBND\_IN( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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 = LOGICAL (Given)
+ }{
+ If this value is .TRUE., 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 LBND\_IN
+ and UBND\_IN arrays should match the number of output
+ coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout} attribute.
+ Similarly, the COORD\_OUT argument, below, should nominate one
+ of the Mapping\texttt{'} s input coordinates.)
+ }
+ \sstsubsection{
+ COORD\_OUT = INTEGER (Given)
+ }{
+ 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 = DOUBLE PRECISION (Returned)
+ }{
+ The lowest value taken by the nominated output coordinate
+ within the specified region of input coordinate space.
+ }
+ \sstsubsection{
+ UBND\_OUT = DOUBLE PRECISION (Returned)
+ }{
+ The highest value taken by the nominated output coordinate
+ within the specified region of input coordinate space.
+ }
+ \sstsubsection{
+ XL( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array with one element for each Mapping input
+ coordinate. This will return 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 LBND\_OUT.
+ }
+ \sstsubsection{
+ XU( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array with one element for each Mapping input
+ coordinate. This will return 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 UBND\_OUT.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 routine 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 LBND\_OUT, UBND\_OUT, XL and XU will be
+ set to the value AST\_\_BAD if this routine should fail for any
+ reason. Their initial values on entry will not be altered if the
+ routine is invoked with STATUS set to an error value.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPCOPY
+}{
+ Copy entries from one KeyMap into another
+}{
+ \sstdescription{
+ This routine
+ copies all entries from one \htmlref{KeyMap}{KeyMap} into another.
+ }
+ \sstinvocation{
+ CALL AST\_MAPCOPY( THIS, THAT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the destination KeyMap.
+ }
+ \sstsubsection{
+ THAT = INTEGER (Given)
+ }{
+ Pointer to the source KeyMap.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_MAPDEFINED
+}{
+ 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
+ .FALSE. (unlike \htmlref{AST\_MAPHASKEY}{AST\_MAPHASKEY} which would return .TRUE.).
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPDEFINED( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPDEFINED = LOGICAL
+ }{
+ .TRUE.
+ is returned if the requested key name is present in the KeyMap
+ and has a defined value.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPGET0$<$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
+ AST\_MAPGET0$<$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 version of this function which returns character strings,
+ AST\_MAPGET0C, has an extra parameter in which is returned the number
+ of characters written into the supplied CHARACTER variable.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPGET0$<$X$>$( THIS, KEY, VALUE, STATUS )
+ RESULT = AST\_MAPGET0C( THIS, KEY, VALUE, L, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = $<$X$>$type (Returned)
+ }{
+ The requested value.
+ If the requested key is not found, or if it is found but has an
+ undefined value (see
+ \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}),
+ then the contents of the
+ buffer on entry to this function will be unchanged on exit.
+ }
+ \sstsubsection{
+ L = INTEGER (Returned)
+ }{
+ This parameter is only present in the interface for the AST\_MAPGET0C
+ function. It is returned holding the number of characters
+ written into the CHARACTER variable supplied for parameter VALUE.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPGET0$<$X$>$ = LOGICAL
+ }{
+ .TRUE.
+ is returned if the requested key name was found, and does not have
+ an undefined value (see
+ AST\_MAPPUTU). .FALSE.
+ is returned otherwise.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ No error is reported if the requested key cannot be found in the
+ given KeyMap, but a
+ .FALSE.
+ 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
+ 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{AST\_ANNUL}{AST\_ANNUL}
+ when it is no longer needed.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate
+ routine, you should replace $<$X$>$ in the generic routine name AST\_MAPGET0$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: Unsigned byte
+
+ }
+ For example, AST\_MAPGET0D would be used to get a DOUBLE PRECISION value,
+ while AST\_MAPGET0I would be used to get an INTEGER, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPGET1$<$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
+ AST\_MAPGET1$<$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).
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPGET1$<$X$>$( THIS, KEY, MXVAL, NVAL, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements in the
+ VALUE array.
+ }
+ \sstsubsection{
+ NVAL = INTEGER (Returned)
+ }{
+ The
+ number of elements stored in the
+ Any unused elements of the array are left unchanged.
+ }
+ \sstsubsection{
+ VALUE( MXVAL ) = $<$X$>$type (Returned)
+ }{
+ The requested values.
+ If the requested key is not found, or if it is found but has an
+ undefined value (see
+ \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}),
+ then the contents of the
+ buffer on entry to this function will be unchanged on exit.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPGET1$<$X$>$ = LOGICAL
+ }{
+ .TRUE.
+ is returned if the requested key name was found, and does not have
+ an undefined value (see
+ AST\_MAPPUTU). .FALSE.
+ is returned otherwise.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ No error is reported if the requested key cannot be found in the
+ given KeyMap, but a
+ .FALSE.
+ 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
+ NVAL
+ will be returned set to 1.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate
+ routine, you should replace $<$X$>$ in the generic routine name AST\_MAPGET1$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: Unsigned byte
+
+ }
+ For example, AST\_MAPGET1D would be used to get DOUBLE PRECISION values,
+ while AST\_MAPGET1I would be used to get INTEGER values, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPGETC
+}{
+ Get a scalar or vector value from a KeyMap as a single string
+}{
+ \sstdescription{
+ This function gets a named value from a \htmlref{KeyMap}{KeyMap} as a single string.
+ For scalar values it is equivalent to
+ AST\_MAPGET0C.
+ If the value is a vector, the returned string is a comma-separated
+ list of the vector elements, enclosed in parentheses.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPGETC( THIS, KEY, VALUE, L, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Returned)
+ }{
+ The requested value.
+ If the requested key is not found, or if it is found but has an
+ undefined value (see
+ \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}), then the contents of the supplied string
+ are unchanged on exit.
+ }
+ \sstsubsection{
+ L = INTEGER (Returned)
+ }{
+ This parameter is only present in the interface for the AST\_MAPGET0C
+ function. It is returned holding the number of characters
+ written into the CHARACTER variable supplied for parameter VALUE.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPGETC = LOGICAL
+ }{
+ .TRUE.
+ is returned if the requested key name was found, and does not have
+ an undefined value (see
+ AST\_MAPPUTU). .FALSE.
+ is returned otherwise.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ No error is reported if the requested key cannot be found in the
+ given KeyMap, but a
+ .FALSE.
+ value will be returned as the function value. The supplied buffer
+ will be returned unchanged.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPGETELEM$<$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
+ AST\_MAPGETELEM$<$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).
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPGETELEM$<$X$>$( THIS, KEY, ELEM, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The index of the required vector element, starting at
+ one.
+ An error will be reported if the value is outside the range of
+ the vector.
+ }
+ \sstsubsection{
+ VALUE = $<$X$>$type (Returned)
+ }{
+ The requested value.
+ If the requested key is not found, or if it is found but has an
+ undefined value (see
+ \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}),
+ then the contents of the
+ buffer on entry to this function will be unchanged on exit.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPGETELEM$<$X$>$ = LOGICAL
+ }{
+ .TRUE.
+ is returned if the requested key name was found, and does not have
+ an undefined value (see
+ AST\_MAPPUTU). .FALSE.
+ 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
+ .FALSE.
+ value will be returned as the function value.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate
+ routine, you should replace $<$X$>$ in the generic routine name
+ AST\_MAPGETELEM$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: Unsigned byte
+
+ }
+ For example, AST\_MAPGETELEMD would be used to get a DOUBLE PRECISION
+ value, while AST\_MAPGETELEMI would be used to get an INTEGER value, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPHASKEY
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPHASKEY( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPHASKEY = LOGICAL
+ }{
+ .TRUE. if the key was found, and .FALSE. otherwise.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ .TRUE.
+ 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{AST\_MAPDEFINED}{AST\_MAPDEFINED}, which returns zero in such a case.
+
+ \sstitem
+ A function value of
+ .FALSE.
+ will be returned if an error has already occurred, or if this
+ function should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPKEY
+}{
+ 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{AST\_MAPSIZE}{AST\_MAPSIZE}
+ and this function should then be called in a loop, with the index
+ value going from
+ one to the size of the KeyMap.
+ The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy}
+ attribute.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPKEY( THIS, INDEX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ INDEX = INTEGER (Given)
+ }{
+ The index into the KeyMap. The first entry has index
+ one, and the last has index SIZE, the value returned by the
+ AST\_MAPSIZE function.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPKEY = CHARACTER $*$ ( AST\_\_SZCHR )
+ }{
+ The key value.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A blank string will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any
+ reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPLENC
+}{
+ Get the number of characters in a character entry in a KeyMap
+}{
+ \sstdescription{
+ This function returns the minimum length that a character variable
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPLENC( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPLENC = INTEGER
+ }{
+ The length (i.e. number of characters) of the longest formatted
+ value associated with the named entry.
+ }
+ }
+ \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{
+ AST\_MAPLENGTH
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPLENGTH( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPLENGTH = INTEGER
+ }{
+ 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{
+ AST\_MAPPUT0$<$X$>$
+}{
+ Add a scalar value to a KeyMap
+}{
+ \sstdescription{
+ This is a set of routine
+ for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a
+ routine
+ which matches the data type of the data you wish to add to the KeyMap
+ by replacing $<$X$>$ in the generic
+ routine name AST\_MAPPUT0$<$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).
+ }
+ \sstinvocation{
+ CALL AST\_MAPPUT0$<$X$>$( THIS, KEY, VALUE, COMMENT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap in which to store the supplied value.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = $<$X$>$type (Given)
+ }{
+ The value to be stored. The data type of this value should match the
+ 1-character type code appended to the
+ routine name (e.g. if you are using AST\_MAPPUT0A, the type of this
+ value should be \texttt{"} integer pointer for an AstObject\texttt{"} ).
+ }
+ \sstsubsection{
+ COMMENT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A comment string to be stored with the value.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ AST\_MAPGET0A.
+ 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
+ routine, you should replace $<$X$>$ in the generic routine name AST\_MAPPUT0$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: Unsigned byte
+
+ }
+ For example, AST\_MAPPUT0D would be used to store a DOUBLE PRECISION value,
+ while AST\_MAPPUT0I would be used to store an INTEGER, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPPUT1$<$X$>$
+}{
+ Add a vector value to a KeyMap
+}{
+ \sstdescription{
+ This is a set of routine
+ for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a
+ routine
+ which matches the data type of the data you wish to add to the KeyMap
+ by replacing $<$X$>$ in the generic
+ routine name AST\_MAPPUT1$<$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).
+ }
+ \sstinvocation{
+ CALL AST\_MAPPUT1$<$X$>$( THIS, KEY, SIZE, VALUE, COMMENT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap in which to store the supplied values.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements in the supplied array of values.
+ }
+ \sstsubsection{
+ VALUE( $*$ ) = $<$X$>$type (Given)
+ }{
+ The array of values to be stored. The data type of this value should
+ match the 1-character type code appended to the
+ routine name (e.g. if you are using AST\_MAPPUT1A, the type of this
+ value should be \texttt{"} integer pointer for an AstObject)\texttt{"} .
+ }
+ \sstsubsection{
+ COMMENT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A comment string to be stored with the values.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ routine, you should replace $<$X$>$ in the generic routine name AST\_MAPPUT1$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: Unsigned byte
+
+ }
+ For example, AST\_MAPPUT1D would be used to store DOUBLE PRECISION values,
+ while AST\_MAPPUT1I would be used to store INTEGER, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPPUTELEM$<$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
+ AST\_MAPPUTELEM$<$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).
+ }
+ \sstinvocation{
+ CALL AST\_MAPPUTELEM$<$X$>$( THIS, KEY, ELEM, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The index of the vector element to modify, starting at
+ one.
+ }
+ \sstsubsection{
+ VALUE = $<$X$>$type (Given)
+ }{
+ The value to store.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ KeyMap
+ }{
+ If the
+ ELEM
+ 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
+ ELEM
+ 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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}.
+ }
+ }
+ \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
+ routine, you should replace $<$X$>$ in the generic routine name
+ AST\_MAPPUTELEM$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ C: CHARACTER
+
+ \sstitem
+ A: INTEGER used to identify an AstObject
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ B: BYTE (unsigned)
+
+ }
+ For example, AST\_MAPPUTELEMD would be used to put a DOUBLE PRECISION
+ value, while AST\_MAPPUTELEMI would be used to put an INTEGER value, etc.
+ }
+}
+\sstroutine{
+ AST\_MAPPUTU
+}{
+ Add an entry to a KeyMap with an undefined value
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_MAPPUTU( THIS, KEY, COMMENT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap in which to store the supplied value.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A comment string to be stored with the value.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If the supplied key is already in use in the KeyMap, the value
+ associated with the key will be removed.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPREGION
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPREGION( THIS, MAP, FRAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ MAP = INTEGER (Given)
+ }{
+ Pointer to a Mapping which transforms positions from the
+ coordinate system represented by the supplied Region to the
+ coordinate system specified by
+ FRAME.
+ 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 = INTEGER (Given)
+ }{
+ Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which
+ the new Region is required.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPREGION = INTEGER
+ }{
+ A pointer to a new Region. This Region will represent the area
+ within the coordinate system specified by
+ FRAME
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPREMOVE
+}{
+ Removed a named entry from a KeyMap
+}{
+ \sstdescription{
+ This routine
+ removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the
+ KeyMap does not contain the specified key.
+ }
+ \sstinvocation{
+ CALL AST\_MAPREMOVE( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPRENAME
+}{
+ Rename an existing KeyMap entry
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_MAPRENAME( THIS, OLDKEY, NEWKEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ OLDKEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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{
+ NEKEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPSIZE
+}{
+ Get the number of entries in a KeyMap
+}{
+ \sstdescription{
+ This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPSIZE( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPSIZE = INTEGER
+ }{
+ 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{
+ AST\_MAPSPLIT
+}{
+ Split a Mapping up into parallel component Mappings
+}{
+ \sstdescription{
+ This routine
+ 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
+ an AST\_\_NULL
+ Mapping pointer is returned.
+ }
+ \sstinvocation{
+ CALL AST\_MAPSPLIT( THIS, NIN, IN, OUT, MAP, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be split.
+ }
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of inputs to pick from THIS.
+ }
+ \sstsubsection{
+ IN( NIN ) = INTEGER (Given)
+ }{
+ An
+ array holding the indices within the supplied Mapping of the inputs
+ which are to be picked from the Mapping.
+ 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( $*$ ) = INTEGER (Returned)
+ }{
+ 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 = INTEGER (Returned)
+ }{
+ The
+ returned Mapping. This Mapping will have
+ NIN inputs (the number of outputs may be different to NIN). AST\_\_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
+ routine
+ is invoked with the global error status set, or if it should fail for
+ any reason, then
+ AST\_\_NULL
+ will be returned for
+ MAP.
+ }
+ }
+}
+\sstroutine{
+ AST\_MAPTYPE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MAPTYPE( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the KeyMap.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MAPTYPE = INTEGER
+ }{
+ One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+ INTEGER$*$2),
+ AST\_\_BYTETYPE (for unsigned bytes
+ ) 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{AST\_MAPPUTU}{AST\_MAPPUTU}).
+ 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{
+ AST\_MARK
+}{
+ Draw a set of markers for a Plot
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_MARK( THIS, NMARK, NCOORD, INDIM, IN, TYPE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ NMARK = INTEGER (Given)
+ }{
+ The number of markers to draw. This may be zero, in which
+ case nothing will be drawn.
+ }
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the IN
+ 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 NMARK.
+ }
+ \sstsubsection{
+ IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ A 2-dimensional array giving the physical coordinates of the
+ points where markers are to be drawn. These should be
+ stored such that the value of coordinate number COORD for
+ input mark number MARK is found in element IN(MARK,COORD).
+ }
+ \sstsubsection{
+ TYPE = INTEGER (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_CLIP}{AST\_CLIP}), 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{
+ AST\_MASK$<$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 INSIDE is .FALSE.)
+ 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 AST\_MASK$<$X$>$ by an appropriate 1- or
+ 2-character type code. For example, if you are masking data
+ with type REAL, you should use the function AST\_MASKR (see
+ the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to
+ other numerical types).
+ }
+ \sstinvocation{
+ RESULT = AST\_MASK$<$X$>$( THIS, MAP, INSIDE, NDIM, LBND, UBND, IN, VAL,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to a Region.
+ }
+ \sstsubsection{
+ MAP = INTEGER (Given)
+ }{
+ 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
+ LBND and UBND arguments. A value of AST\_\_NULL
+ 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 NDIM
+ below.
+ }
+ \sstsubsection{
+ INSIDE = INTEGER (Given)
+ }{
+ A boolean value which indicates which pixel are to be masked. If
+ .TRUE.
+ is supplied, then all grid pixels with centres inside the supplied
+ Region are assigned the value given by
+ VAL,
+ and all other pixels are left unchanged. If
+ .FALSE.
+ is supplied, then all grid pixels with centres not inside the supplied
+ Region are assigned the value given by
+ VAL,
+ 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 = INTEGER (Given)
+ }{
+ The number of dimensions in the input grid. This should be at
+ least one.
+ }
+ \sstsubsection{
+ LBND( NDIM ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND( NDIM ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND and UBND 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. 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( $*$ ) = $<$Xtype$>$ (Given and Returned)
+ }{
+ 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 AST\_MASKR, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+
+ On exit, the samples specified by
+ INSIDE are set to the value of VAL.
+ All other samples are left unchanged.
+ }
+ \sstsubsection{
+ VAL = $<$Xtype$>$ (Given)
+ }{
+ This argument should have the same type as the elements of
+ the IN array. It specifies the value used to flag the
+ masked data (see
+ INSIDE).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MASK$<$X$>$ = INTEGER
+ }{
+ The number of pixels to which a value of
+ BADVAL
+ 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 AST\_MASK$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ UI: INTEGER (treated as unsigned)
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ US: INTEGER$*$2 (short integer, treated as unsigned)
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_MASKD would be used to process DOUBLE
+ PRECISION data, while AST\_MASKS would be used to process
+ short integer data (stored in an INTEGER$*$2 array), etc.
+
+ For compatibility with other Starlink facilities, the codes W
+ and UW are provided as synonyms for S and US respectively (but
+ only in the Fortran interface to AST).
+ }
+}
+\sstroutine{
+ AST\_MATCHAXES
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_MATCHAXES( FRM1, FRM2, AXES, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRM1 = INTEGER (Given)
+ }{
+ Pointer to the first Frame.
+ }
+ \sstsubsection{
+ FRM2 = INTEGER (Given)
+ }{
+ Pointer to the second Frame.
+ }
+ \sstsubsection{
+ AXES = INTEGER( $*$ ) (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}.
+ 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{
+ AST\_MATHMAP
+}{
+ 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 Fortran. 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MATHMAP( NIN, NOUT, NFWD, FWD, NINV, INV, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER
+ }{
+ Number of input variables for the MathMap. This determines the
+ value of its \htmlref{Nin}{Nin} attribute.
+ }
+ \sstsubsection{
+ NOUT = INTEGER
+ }{
+ Number of output variables for the MathMap. This determines the
+ value of its \htmlref{Nout}{Nout} attribute.
+ }
+ \sstsubsection{
+ NFWD = INTEGER
+ }{
+ The number of forward transformation functions being supplied.
+ This must be at least equal to NOUT, 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 = CHARACTER $*$ ( $*$ )( NFWD )
+ }{
+ An array which contains the expressions defining the forward
+ transformation.
+ The syntax of these expressions is described below.
+ }
+ \sstsubsection{
+ NINV = INTEGER
+ }{
+ The number of inverse transformation functions being supplied.
+ This must be at least equal to NIN, 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 = CHARACTER $*$ ( $*$ )( NINV )
+ }{
+ An array which contains the expressions defining the inverse
+ transformation.
+ The syntax of these expressions is described below.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MATHMAP = INTEGER
+ }{
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}) 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 STATUS set to an error value, 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 FWD argument, 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 (R and THETA) provide names for the output variables and
+ those that appear on the right (X and Y) are references to input
+ variables.
+
+ To complement this, you must also supply expressions for the inverse
+ transformation via the INV argument. 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 (X and Y) are named on
+ the left of each expression, and the output variables (R and THETA)
+ 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 (R, ROUT
+ and THETA) and then use these to calculate the final results (XOUT
+ and YOUT). 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 XOUT and YOUT. The intermediate variables R,
+ ROUT and THETA (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 Fortran (with some extensions for
+ compatibility with the C language). They may contain references to
+ variables and literal constants, together with arithmetic, logical,
+ 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). 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 X1 and X2.
+
+ \sstitem
+ X1 - X2: Difference of X1 and X2.
+
+ \sstitem
+ X1 $*$ X2: Product of X1 and X2.
+
+ \sstitem
+ X1 / X2: Ratio of X1 and X2.
+
+ \sstitem
+ X1 $*$$*$ X2: X1 raised to the power of X2.
+
+ \sstitem
+ $+$ X: Unary plus, has no effect on its argument.
+
+ \sstitem
+ - X: Unary minus, negates its argument.
+ }
+ }
+ \sstdiytopic{
+ Logical Operators
+ }{
+ Logical 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 logical operators may therefore
+ be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"} logic is
+ implemented. For example, A.OR.B may evaluate to 1 if A is non-zero,
+ even if B has the value AST\_\_BAD. This is because the result of the
+ operation would not be affected by the value of B, so long as A is
+ non-zero.
+
+ The following logical operators are available:
+ \sstitemlist{
+
+ \sstitem
+ X1 .AND. X2: Logical AND between X1 and X2, returning 1 if both X1
+ and X2 are non-zero, and 0 otherwise. This operator implements
+ tri-state logic. (The synonym \texttt{"} \&\&\texttt{"} is also provided for compatibility
+ with C.)
+
+ \sstitem
+ X1 .OR. X2: Logical OR between X1 and X2, returning 1 if either X1
+ or X2 are non-zero, and 0 otherwise. This operator implements
+ tri-state logic. (The synonym \texttt{"} $|$$|$\texttt{"} is also provided for compatibility
+ with C.)
+
+ \sstitem
+ X1 .NEQV. X2: Logical exclusive OR (XOR) between X1 and X2,
+ returning 1 if exactly one of X1 and X2 is non-zero, and 0
+ otherwise. Tri-state logic is not used with this operator. (The
+ synonym \texttt{"} .XOR.\texttt{"} is also provided, although this is not standard
+ Fortran. In addition, the C-like synonym \texttt{"} $\wedge$$\wedge$\texttt{"} may be used, although
+ this is also not standard.)
+
+ \sstitem
+ X1 .EQV. X2: Tests whether the logical states of X1 and X2
+ (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
+ .NOT. X: Logical unary NOT operation, returning 1 if X is zero, and
+ 0 otherwise. (The synonym \texttt{"} !\texttt{"} is also provided for compatibility with
+ C.)
+ }
+ }
+ \sstdiytopic{
+ Relational Operators
+ }{
+ Relational operators return the logical 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 .EQ. X2: Tests whether X1 equals X2. (The synonym \texttt{"} ==\texttt{"} is also
+ provided for compatibility with C.)
+
+ \sstitem
+ X1 .NE. X2: Tests whether X1 is unequal to X2. (The synonym \texttt{"} !=\texttt{"} is
+ also provided for compatibility with C.)
+
+ \sstitem
+ X1 .GT. X2: Tests whether X1 is greater than X2. (The synonym \texttt{"} $>$\texttt{"} is
+ also provided for compatibility with C.)
+
+ \sstitem
+ X1 .GE. X2: Tests whether X1 is greater than or equal to X2. (The
+ synonym \texttt{"} $>$=\texttt{"} is also provided for compatibility with C.)
+
+ \sstitem
+ X1 .LT. X2: Tests whether X1 is less than X2. (The synonym \texttt{"} $<$\texttt{"} is also
+ provided for compatibility with C.)
+
+ \sstitem
+ X1 .LE. X2: Tests whether X1 is less than or equal to X2. (The synonym
+ \texttt{"} $<$=\texttt{"} is also provided for compatibility with C.)
+
+ }
+ 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.
+
+ Note, also, that because logical operators can operate on floating
+ point values, care must be taken to use parentheses in some cases
+ where they would not normally be required in Fortran. For example,
+ the expresssion:
+ \sstitemlist{
+
+ \sstitem
+ .NOT. A .EQ. B
+
+ }
+ must be written:
+ \sstitemlist{
+
+ \sstitem
+ .NOT. ( A .EQ. B )
+
+ }
+ to prevent the .NOT. operator from associating with the variable A.
+ }
+ \sstdiytopic{
+ Bitwise Operators
+ }{
+ Bitwise operators are often useful when operating on raw data
+ (e.g. from instruments), so they are provided for use in MathMap
+ expressions. In this case, however, the values on which they operate
+ are floating point values rather than the more usual 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 X2 is taken
+ (rounding towards zero) and the bits representing X1 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 X1 by
+ the corresponding power of 2.
+
+ \sstitem
+ X1 $<$$<$ X2: Leftward bit shift. The integer value of X2 is taken
+ (rounding towards zero), and the bits representing X1 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 X1
+ by the corresponding power of 2.
+
+ \sstitem
+ X1 \& X2: Bitwise AND between the bits of X1 and those of X2
+ (equivalent to a logical AND applied at each bit position in turn).
+
+ \sstitem
+ X1 $|$ X2: Bitwise OR between the bits of X1 and those of X2
+ (equivalent to a logical OR applied at each bit position in turn).
+
+ \sstitem
+ X1 $\wedge$ X2: Bitwise exclusive OR (XOR) between the bits of X1 and
+ those of X2 (equivalent to a logical XOR applied at each bit
+ position in turn).
+
+ }
+ Note that no bit inversion operator 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. X$\wedge$-1).
+ }
+ \sstdiytopic{
+ Functions
+ }{
+ The following functions are available:
+ \sstitemlist{
+
+ \sstitem
+ ABS(X): Absolute value of X (sign removal), same as FABS(X).
+
+ \sstitem
+ ACOS(X): Inverse cosine of X, in radians.
+
+ \sstitem
+ ACOSD(X): Inverse cosine of X, in degrees.
+
+ \sstitem
+ ACOSH(X): Inverse hyperbolic cosine of X.
+
+ \sstitem
+ ACOTH(X): Inverse hyperbolic cotangent of X.
+
+ \sstitem
+ ACSCH(X): Inverse hyperbolic cosecant of X.
+
+ \sstitem
+ AINT(X): Integer part of X (round towards zero), same as INT(X).
+
+ \sstitem
+ ASECH(X): Inverse hyperbolic secant of X.
+
+ \sstitem
+ ASIN(X): Inverse sine of X, in radians.
+
+ \sstitem
+ ASIND(X): Inverse sine of X, in degrees.
+
+ \sstitem
+ ASINH(X): Inverse hyperbolic sine of X.
+
+ \sstitem
+ ATAN(X): Inverse tangent of X, in radians.
+
+ \sstitem
+ ATAND(X): Inverse tangent of X, in degrees.
+
+ \sstitem
+ ATANH(X): Inverse hyperbolic tangent of X.
+
+ \sstitem
+ ATAN2(X1, X2): Inverse tangent of X1/X2, in radians.
+
+ \sstitem
+ ATAN2D(X1, X2): Inverse tangent of X1/X2, in degrees.
+
+ \sstitem
+ CEIL(X): Smallest integer value not less then X (round towards
+ plus infinity).
+
+ \sstitem
+ COS(X): Cosine of X in radians.
+
+ \sstitem
+ COSD(X): Cosine of X in degrees.
+
+ \sstitem
+ COSH(X): Hyperbolic cosine of X.
+
+ \sstitem
+ COTH(X): Hyperbolic cotangent of X.
+
+ \sstitem
+ CSCH(X): Hyperbolic cosecant of X.
+
+ \sstitem
+ DIM(X1, X2): Returns X1-X2 if X1 is greater than X2, otherwise 0.
+
+ \sstitem
+ EXP(X): Exponential function of X.
+
+ \sstitem
+ FABS(X): Absolute value of X (sign removal), same as ABS(X).
+
+ \sstitem
+ FLOOR(X): Largest integer not greater than X (round towards
+ minus infinity).
+
+ \sstitem
+ FMOD(X1, X2): Remainder when X1 is divided by X2, same as
+ MOD(X1, X2).
+
+ \sstitem
+ GAUSS(X1, X2): Random sample from a Gaussian distribution with mean
+ X1 and standard deviation X2.
+
+ \sstitem
+ INT(X): Integer part of X (round towards zero), same as AINT(X).
+
+ \sstitem
+ ISBAD(X): Returns 1 if X has the $<$bad$>$ value (AST\_\_BAD), otherwise 0.
+
+ \sstitem
+ LOG(X): Natural logarithm of X.
+
+ \sstitem
+ LOG10(X): Logarithm of X 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 X1 is divided by X2, same as
+ FMOD(X1, X2).
+
+ \sstitem
+ NINT(X): Nearest integer to X (round to nearest).
+
+ \sstitem
+ POISSON(X): Random integer-valued sample from a Poisson
+ distribution with mean X.
+
+ \sstitem
+ POW(X1, X2): X1 raised to the power of X2.
+
+ \sstitem
+ QIF(x1, x2, x3): Returns X2 if X1 is true, and X3 otherwise.
+
+ \sstitem
+ RAND(X1, X2): Random sample from a uniform distribution in the
+ range X1 to X2 inclusive.
+
+ \sstitem
+ SECH(X): Hyperbolic secant of X.
+
+ \sstitem
+ SIGN(X1, X2): Absolute value of X1 with the sign of X2
+ (transfer of sign).
+
+ \sstitem
+ SIN(X): Sine of X in radians.
+
+ \sstitem
+ SINC(X): Sinc function of X [= SIN(X)/X].
+
+ \sstitem
+ SIND(X): Sine of X in degrees.
+
+ \sstitem
+ SINH(X): Hyperbolic sine of X.
+
+ \sstitem
+ SQR(X): Square of X (= X$*$X).
+
+ \sstitem
+ SQRT(X): Square root of X.
+
+ \sstitem
+ TAN(X): Tangent of X in radians.
+
+ \sstitem
+ TAND(X): Tangent of X in degrees.
+
+ \sstitem
+ TANH(X): Hyperbolic tangent of X.
+ }
+ }
+ \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 precision) 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 precision) value.
+
+ \sstitem
+ $<$max$>$: Maximum representable floating point (double precision) value.
+
+ \sstitem
+ $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power
+ can be represented as a floating point (double precision) value.
+
+ \sstitem
+ $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that
+ power minus 1 can be represented as a floating point (double precision)
+ value.
+
+ \sstitem
+ $<$min$>$: Smallest positive number which can be represented as a
+ normalised floating point (double precision) value.
+
+ \sstitem
+ $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that
+ power can be represented as a normalised floating point (double
+ precision) 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 precision) 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 precision) 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{
+ AST\_MATRIXMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MATRIXMAP( NIN, NOUT, FORM, MATRIX, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates, which determines the number
+ of columns in the matrix.
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates, which determines the number
+ of rows in the matrix.
+ }
+ \sstsubsection{
+ FORM = INTEGER (Given)
+ }{
+ An integer which indicates the form in which the matrix
+ elements will be supplied.
+
+ A value of zero indicates that a full NOUT x NIN matrix
+ of values will be supplied via the MATRIX argument
+ (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 MATRIX 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 MATRIX argument is not used.
+ }
+ \sstsubsection{
+ MATRIX( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ The array of matrix elements to be used, stored according to
+ the value of FORM.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MATRIXMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_MIRRORVARIANTS
+}{
+ Make the current Frame mirror the variant Mappings in another Frame
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_MIRRORVARIANTS( THIS, IFRAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ 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
+ routine
+ is disabled.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_ADDVARIANT}{AST\_ADDVARIANT} routine
+ 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
+ IFRAME argument
+ to specify the base Frame.
+
+ \sstitem
+ Any variant Mappings explicitly added to the current Frame using
+ AST\_ADDVARIANT
+ will be ignored if the current Frame is mirroring another Frame.
+ }
+ }
+}
+\sstroutine{
+ AST\_MOC
+}{
+ Create a Moc
+}{
+ \sstdescription{
+ This function creates a new \htmlref{Moc}{Moc} object and optionally initialises
+ its attributes.
+
+ The Moc class uses the IVOA MOC (Multi-Order Coverage) recommendation
+ to describe a region on the sky. The region is made up of an
+ arbitrary collection of cells from the HEALPix sky tessellation,
+ and thus may represent any area on the sky, subject to the
+ constraint that the edges of the area correspond to edges of the
+ HEALPix cells. See the MOC recommendation for further information
+ (http://www.ivoa.net/documents/MOC/).
+
+ As a description of a region on the sky, the Moc class can be seen
+ as an alternative to the \htmlref{Region}{Region} class. Note, Mocs and Regions
+ are not interchangable (that is, a Moc is not a subclass of Region
+ and therefore Region methods cannot be applied to Mocs). The Moc
+ class is intended to describe an arbitrary collection of cells on
+ the sky, whereas the Region classes describe exact geometric shapes.
+ The Moc class has a method that allow a Region to be converted into
+ an approximating Moc, but Mocs cannot be converted into Regions.
+
+ The MOC recommendation requires that a MOC always describes a sky
+ area using the ICRS coordinate system. However, the Moc class
+ allows its attributes to be changed so that it represents any
+ celestial coordinate system that can be mapped to ICRS. Note,
+ changing the \htmlref{System}{System} attribute will not change the area on the
+ sky covered by the Moc - it will just change the way that area is
+ described. For instance, if a Moc is created that covers a particular
+ galaxy in ICRS, and the System attriubute is then changed to Galactic,
+ the Moc will still cover the same galaxy, but it will now be described
+ in Galactic coordinates rather than ICRS. When a Moc is written out
+ through a \htmlref{FitsChan}{FitsChan}, FITS headers describing the Moc will be stored
+ in the FitsChan. The binary data for the single column of the
+ coresponding FITS binary table can be retrieved from the Moc using
+ method \htmlref{AST\_GETMOCDATA}{AST\_GETMOCDATA}.
+
+ In practice, to use this class an empty Moc object (i.e. a Moc
+ describing a null area of the sky) should first be created using the
+ AST\_MOC
+ constructor. Areas of the sky should then be added into the empty
+ Moc using one or more of the class methods.
+ }
+ \sstinvocation{
+ RESULT = AST\_MOC( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ MAXORDER = INTEGER (Given)
+ }{
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing an optional comma-separated
+ list of attribute assignments to be used for initialising the
+ new Moc. The syntax used is identical to that for the
+ \htmlref{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MOC = INTEGER
+ }{
+ A pointer to the new Moc.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_MOCCHAN
+}{
+ Create a MocChan
+}{
+ \sstdescription{
+ This function creates a new \htmlref{MocChan}{MocChan} and optionally initialises
+ its attributes.
+
+ A MocChan is a specialised form of \htmlref{Channel}{Channel} which supports the
+ reading and writing of AST \htmlref{Moc}{Moc} objects as text, using the
+ conventions of the JSON and string encodings described in
+ the IVOA\texttt{'} s MOC recommendation, version 1.1. Writing a Moc
+ to a MocChan (using
+ \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Moc is suitable, generate a
+ textual description of that Moc, and reading from a MocChan will
+ create a new Moc from its textual description. See the Moc class
+ for further information.
+
+ Normally, when you use a MocChan, you should provide \texttt{"} source\texttt{"}
+ and \texttt{"} sink\texttt{"} routines which connect it to an external data store
+ by reading and writing the resulting text. These routines
+ should perform any conversions needed between external character
+ encodings and the internal ASCII encoding. If no such routines
+ are supplied, a Channel will read from standard input and write
+ to standard output.
+
+ Alternatively, a MocChan 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_MOCCHAN( SOURCE, SINK, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SOURCE = SUBROUTINE (Given)
+ }{
+ A source routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SourceFile attribute, this routine will be used by
+ the MocChan to obtain lines of input text. On each
+ invocation, it should read the next input line from some
+ external data store, and then return the resulting text to
+ the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a
+ negative line length when there are no more lines to read.
+ If an error occurs, it should set its own error status
+ argument to an error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SOURCE value,
+ and no value has been set for the SourceFile attribute,
+ the MocChan will read from standard input instead.
+ }
+ \sstsubsection{
+ SINK = SUBROUTINE (Given)
+ }{
+ A sink routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SinkFile attribute, this routine will be used by
+ the MocChan to deliver lines of output text. On each
+ invocation, it should obtain the next output line from the
+ AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the
+ resulting text to some external data store. If an error
+ occurs, it should set its own error status argument to an
+ error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SINK value,
+ and no value has been set for the SinkFile attribute,
+ the MocChan will write to standard output instead.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing an optional comma-separated
+ list of attribute assignments to be used for initialising the
+ new MocChan. The syntax used is identical to that for the
+ \htmlref{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_MOCCHAN = INTEGER
+ }{
+ A pointer to the new MocChan.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The names of the routines supplied for the SOURCE and SINK
+ arguments should appear in EXTERNAL statements in the Fortran
+ routine which invokes AST\_MOCCHAN. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \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 \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.
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null Object
+ pointer.
+ }
+ }
+}
+\sstroutine{
+ AST\_NEGATE
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_NEGATE( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_NORM
+}{
+ Normalise a set of Frame coordinates
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_NORM( THIS, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ VALUE( $*$ ) = DOUBLE PRECISION (Given and Returned)
+ }{
+ An array 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ AST\_NORM routine
+ 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{AST\_FORMAT}{AST\_FORMAT}).
+ }
+ }
+}
+\sstroutine{
+ AST\_NORMMAP
+}{
+ 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{AST\_NORM}{AST\_NORM} routine
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ function will replace neighbouring pairs of forward and inverse
+ NormMaps by a single \htmlref{UnitMap}{UnitMap} (so long as the Frames encapsulated by
+ the two NormMaps are equal - i.e. have the same class and the same
+ attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
+ a NormMap, the CmpMap will still cancel with its own inverse.
+ }
+ \sstinvocation{
+ RESULT = AST\_NORMMAP( FRAME, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ A pointer to the Frame which is to be used to normalise the
+ supplied axis values.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_NORMMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_NULLREGION
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_NULLREGION( FRAME, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ may be supplied, in which case a default uncertainty of zero is
+ used.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_NULLREGION = INTEGER
+ }{
+ A pointer to the new NullRegion.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_OFFSET
+}{
+ Calculate an offset along a geodesic curve
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_OFFSET( THIS, POINT1, POINT2, OFFSET, POINT3, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ POINT1( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis.
+ This should contain the coordinates of the point marking the
+ end of the geodesic curve.
+ }
+ \sstsubsection{
+ OFFSET = DOUBLE PRECISION
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array with one element for each Frame axis
+ in which the coordinates of the required point will be returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The geodesic curve used by this routine is the path of
+ shortest distance between two points, as defined by the
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE} 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{
+ AST\_OFFSET2
+}{
+ Calculate an offset along a geodesic curve in a 2D Frame
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_OFFSET2( THIS, POINT1, ANGLE, OFFSET, POINT2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ POINT1( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = DOUBLE PRECISION
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array with one element for each Frame axis
+ in which the coordinates of the required point will be returned.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_OFFSET2 = DOUBLE PRECISION
+ }{
+ 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 routine is the path of
+ shortest distance between two points, as defined by the
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE} 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{
+ AST\_OUTLINE$<$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
+ STARPIX.
+
+ The
+ MAXERR and MAXVERT
+ 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
+ AST\_OUTLINE$<$X$>$
+ are procesing data with type
+ REAL, you should use the function AST\_OUTLINER
+ (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to
+ other numerical types).
+ }
+ \sstinvocation{
+ RESULT = AST\_OUTLINE$<$X$>$( VALUE, OPER, ARRAY, LBND, UBND, MAXERR,
+ MAXVERT, INSIDE, STARPIX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ VALUE = $<$Xtype$>$ (Given)
+ }{
+ A data value that specifies the pixels to be outlined.
+ }
+ \sstsubsection{
+ OPER = INTEGER (Given)
+ }{
+ Indicates how the
+ VALUE
+ 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 VALUE.
+
+ \sstitem
+ AST\_\_LE: outline pixels with value less than or equal to VALUE.
+
+ \sstitem
+ AST\_\_EQ: outline pixels with value equal to VALUE.
+
+ \sstitem
+ AST\_\_NE: outline pixels with value not equal to VALUE.
+
+ \sstitem
+ AST\_\_GE: outline pixels with value greater than or equal to VALUE.
+
+ \sstitem
+ AST\_\_GT: outline pixels with value greater than VALUE.
+ }
+ }
+ \sstsubsection{
+ ARRAY( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_OUTLINER, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ LBND( 2 ) = INTEGER (Given)
+ }{
+ An array
+ containing the pixel index of the first pixel in the input grid
+ along each dimension.
+ }
+ \sstsubsection{
+ UBND( 2) = INTEGER (Given)
+ }{
+ An array
+ containing the pixel index of the last pixel in the input grid
+ along each dimension.
+
+ Note that LBND and UBND 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
+ STARPIX.
+ }
+ \sstsubsection{
+ MAXERR = DOUBLE PRECISION (Given)
+ }{
+ Together with
+ MAXVERT,
+ 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
+ MAXVERT,
+ or the largest discrepancy between the accurate outline and the
+ returned Polygon is greater than
+ MAXERR. If MAXERR
+ is zero or less, its value is ignored and the returned Polygon will
+ have the number of vertices specified by
+ MAXVERT.
+ }
+ \sstsubsection{
+ MAXVERT = INTEGER (Given)
+ }{
+ Together with
+ MAXERR,
+ 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
+ MAXVERT,
+ or the largest discrepancy between the accurate outline and the
+ returned Polygon is greater than
+ MAXERR. If MAXVERT
+ 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
+ MAXERR.
+ }
+ \sstsubsection{
+ INSIDE( 2 ) = INTEGER (Given)
+ }{
+ An array
+ 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
+ VALUE and OPER.
+ In such cases, the area described by the returned Polygon will
+ be the one that contains the pixel specified by
+ INSIDE.
+ If the specified pixel is outside the bounds given by
+ LBND and UBND,
+ or has a value that does not meet the criterion specified by
+ VALUE and OPER,
+ 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 = LOGICAL (Given)
+ }{
+ A flag indicating the nature of the pixel coordinate system used
+ to describe the vertex positions in the returned Polygon. If
+ .TRUE.,
+ 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 .FALSE.,
+ the definition of pixel coordinate used by other AST functions
+ such as AST\_RESAMPLE, AST\_MASK,
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_OUTLINE$<$X$>$ = INTEGER
+ }{
+ 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{AST\_DOWNSIZE}{AST\_DOWNSIZE}.
+
+ \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
+ AST\_\_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 AST\_OUTLINE$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ UI: INTEGER (treated as unsigned)
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ US: INTEGER$*$2 (short integer, treated as unsigned)
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_OUTLINED would be used to process DOUBLE
+ PRECISION data, while AST\_OUTLINES would be used to process
+ short integer data (stored in an INTEGER$*$2 array), etc.
+
+ For compatibility with other Starlink facilities, the codes W
+ and UW are provided as synonyms for S and US respectively (but
+ only in the Fortran interface to AST).
+ }
+}
+\sstroutine{
+ AST\_OVERLAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_OVERLAP( THIS, THAT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the first \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ THAT = INTEGER (Given)
+ }{
+ Pointer to the second Region.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_OVERLAP = INTEGER
+ }{
+ 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{
+ AST\_PARAMETERNAME
+}{
+ 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
+ one to 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_PARAMETERNAME( THIS, INDEX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ INDEX = INTEGER (Given)
+ }{
+ The index into the list of parameters. The first parameter has index
+ one, and the last has index \texttt{"} Nparameter\texttt{"} .
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PARAMETERNAME = CHARACTER $*$ ( AST\_\_SZCHR )
+ }{
+ The
+ upper case parameter name.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A blank string will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any
+ reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PCDMAP
+}{
+ 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{AST\_INVERT}{AST\_INVERT}) 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_PCDMAP( DISCO, PCDCEN, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ DISCO = DOUBLE PRECISION (Given)
+ }{
+ The distortion coefficient. Negative values give barrel
+ distortion, positive values give pincushion distortion, and
+ zero gives no distortion.
+ }
+ \sstsubsection{
+ PCDCEN( 2 ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the coordinates of the centre of the
+ distortion.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PCDMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_PERMAXES
+}{
+ Permute the axis order in a Frame
+}{
+ \sstdescription{
+ This routine permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur.
+ }
+ \sstinvocation{
+ CALL AST\_PERMAXES( THIS, PERM, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ PERM( $*$ ) = INTEGER (Given)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Only genuine permutations of the axis order are permitted, so
+ each axis must be referenced exactly once in the PERM array.
+
+ \sstitem
+ If successive axis permutations are applied to a Frame, then
+ the effects are cumulative.
+ }
+ }
+}
+\sstroutine{
+ AST\_PERMMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_PERMMAP( NIN, INPERM, NOUT, OUTPERM, CONSTANT, OPTIONS,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates.
+ }
+ \sstsubsection{
+ INPERM = INTEGER( NIN ) (Given)
+ }{
+ An array 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 CONSTANT argument.
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates.
+ }
+ \sstsubsection{
+ OUTPERM = INTEGER( NOUT ) (Given)
+ }{
+ An array 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 CONSTANT argument.
+ }
+ \sstsubsection{
+ CONSTANT = DOUBLE PRECISION( $*$ ) (Given)
+ }{
+ An 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 INPERM or
+ OUTPERM arrays contains a negative value, it is used to
+ address this CONSTANT 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 INPERM and OUTPERM arrays do not
+ contain negative values.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PERMMAP = INTEGER
+ }{
+ A pointer to the new PermMap.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If either of the INPERM or OUTPERM 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PICKAXES
+}{
+ 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.
+
+ A \htmlref{Mapping}{Mapping} that converts between the coordinate
+ systems described by the two Frames will also be returned.
+ }
+ \sstinvocation{
+ RESULT = AST\_PICKAXES( THIS, NAXES, AXES, MAP, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the original Frame.
+ }
+ \sstsubsection{
+ NAXES = INTEGER (Given)
+ }{
+ The number of axes required in the new Frame.
+ }
+ \sstsubsection{
+ AXES( NAXES ) = INTEGER (Given)
+ }{
+ An array 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 = INTEGER (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ AXES
+ array must not contain any zero values.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PICKAXES = INTEGER
+ }{
+ A pointer to the new Frame.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The new Frame will contain a \texttt{"} deep\texttt{"} copy (c.f. \htmlref{AST\_COPY}{AST\_COPY}) 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PLOT
+}{
+ 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{AST\_CURVE}{AST\_CURVE}). A Plot also provides facilities for drawing
+ markers or symbols (\htmlref{AST\_MARK}{AST\_MARK}), text (\htmlref{AST\_TEXT}{AST\_TEXT}) and grid lines
+ (\htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}). It is also possible to draw curvilinear axes
+ with optional coordinate grids (\htmlref{AST\_GRID}{AST\_GRID}).
+ A range of Plot attributes is available to allow precise control
+ over the appearance of graphical output produced by these
+ routines.
+
+ 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{AST\_CLIP}{AST\_CLIP}) 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_PLOT( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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( 4 ) = REAL (Given)
+ }{
+ 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( 4 ) = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PLOT
+ }{
+ 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 FRAME 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 FRAME 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
+ FRAME 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PLOT3D
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_PLOT3D( FRAME, GRAPHBOX, BASEBOX, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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( 6 ) = REAL (Given)
+ }{
+ 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( 6 ) = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PLOT3D = INTEGER
+ }{
+ 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 FRAME 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 FRAME 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
+ FRAME 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_POINTLIST
+}{
+ 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}.
+ }
+ \sstinvocation{
+ RESULT = AST\_POINTLIST( FRAME, NPNT, COORD, DIM, POINTS, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of points in the Region.
+ }
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the POINTS
+ 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 NPNT.
+ }
+ \sstsubsection{
+ POINTS( DIM, NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ A 2-dimensional array giving the physical coordinates of the
+ points. These should be stored such that the value of coordinate
+ number COORD for point number PNT is found in element IN(PNT,COORD).
+ }
+ \sstsubsection{
+ UNC = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_POINTLIST = INTEGER
+ }{
+ A pointer to the new PointList.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_POLYCOEFFS
+}{
+ Retrieve the coefficient values used by a PolyMap
+}{
+ \sstdescription{
+ This function returns the coefficient values used by either the
+ forward or inverse transformation of a \htmlref{PolyMap}{PolyMap}, in the same form
+ that they are supplied to the PolyMap constructor.
+
+ Usually, you should call this method first with
+ NEL
+ set to zero to determine the number of coefficients used by the
+ PolyMap. This allows you to allocate an array of the correct size to
+ hold all coefficient data. You should then call this method a
+ second time to get the coefficient data.
+ }
+ \sstinvocation{
+ CALL AST\_POLYCOEFFS( THIS, FORWARD, NEL, COEFFS, NCOEFF, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the original \htmlref{Mapping}{Mapping}.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ the coefficients of the forward PolyMap transformation are
+ returned. Otherwise the inverse transformation coefficients are
+ returned.
+ }
+ \sstsubsection{
+ NEL = INTEGER (Given)
+ }{
+ The length of the supplied
+ COEFFS
+ array. It should be at least \texttt{"} ncoeff$*$( nin $+$ 2 )\texttt{"} if
+ FORWARD is .TRUE.,
+ and \texttt{"} ncoeff$*$( nout $+$ 2 )\texttt{"} otherwise, where \texttt{"} ncoeff\texttt{"} is the
+ number of coefficients to be returned. If a value of zero
+ is supplied, no coefficient values are returned, but the
+ number of coefficients used by the transformation is still
+ returned in
+ NCOEFF.
+ }
+ \sstsubsection{
+ COEFFS( NEL ) = DOUBLE PRECISION (Returned)
+ }{
+ An array in which to return the coefficients used by the
+ requested transformation of the PolyMap. Ignored if
+ NEL is zero.
+ The coefficient data is returned in the form in which it is
+ supplied to the PolyMap constructor. That is, each group of
+ \texttt{"} 2 $+$ nin\texttt{"} or \texttt{"} 2 $+$ nout\texttt{"} adjacent elements describe a single
+ coefficient of the forward or inverse transformation. See the
+ PolyMap constructor documentation for further details.
+
+ If the supplied array is too short to hold all the coefficients,
+ trailing coefficients are excluded. If the supplied array is
+ longer than needed to hold all the coefficients, trailing
+ elements are filled with zeros.
+ }
+ \sstsubsection{
+ NCOEFF = INTEGER (Returned)
+ }{
+ The number of coefficients used by the requested transformation.
+ A value of zero is returned if the transformation does not
+ have any defining polynomials. A value is returned for this argument
+ even if
+ NEL is zero.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_POLYCURVE
+}{
+ Draw a series of connected geodesic curves
+}{
+ \sstdescription{
+ This routine 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 calls to the
+ \htmlref{AST\_CURVE}{AST\_CURVE} routine (q.v.), except that AST\_POLYCURVE 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 AST\_CURVE, full account is taken of the \htmlref{Mapping}{Mapping} between
+ physical and graphical coordinate systems. This includes any
+ discontinuities and clipping established using \htmlref{AST\_CLIP}{AST\_CLIP}.
+ }
+ \sstinvocation{
+ CALL AST\_POLYCURVE( THIS, NPOINT, NCOORD, INDIM, IN, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Given)
+ }{
+ The number of points between which geodesic curves are to be drawn.
+ }
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the IN
+ 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 NPOINT.
+ }
+ \sstsubsection{
+ IN( INDIM, NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ A 2-dimensional array 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 COORD for input point number POINT is found
+ in element IN(POINT,COORD).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_POLYGON
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_POLYGON( FRAME, NPNT, DIM, POINTS, UNC, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of points in the Region.
+ }
+ \sstsubsection{
+ DIM = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the POINTS
+ 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 NPNT.
+ }
+ \sstsubsection{
+ POINTS( DIM, 2 ) = DOUBLE PRECISION (Given)
+ }{
+ A 2-dimensional array giving the physical coordinates of the
+ vertices. These should be stored such that the value of coordinate
+ number COORD for point number PNT is found in element IN(PNT,COORD).
+ }
+ \sstsubsection{
+ UNC = INTEGER (Given)
+ }{
+ 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 (AST\_\_NULL)
+ 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{AST\_OVERLAP}{AST\_OVERLAP}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}),
+ the uncertainties are used to determine if the transformed boundary
+ can be accurately represented by a specific shape of Region.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_POLYGON = INTEGER
+ }{
+ A pointer to the new Polygon.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A null Object pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_POLYMAP
+}{
+ 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, the default behaviour is to use
+ an iterative method to evaluate the inverse based only on the forward
+ transformation (see attribute \htmlref{IterInverse}{IterInverse}).
+ }
+ \sstinvocation{
+ RESULT = AST\_POLYMAP( NIN, NOUT, NCOEFF\_F, COEFF\_F, NCOEFF\_I, COEFF\_I,
+ OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ The number of input coordinates.
+ }
+ \sstsubsection{
+ NOUT = INTEGER (Given)
+ }{
+ The number of output coordinates.
+ }
+ \sstsubsection{
+ NCOEFF\_F = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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).
+
+ 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 = INTEGER (Given)
+ }{
+ The number of non-zero coefficients necessary to define the
+ inverse transformation of the PolyMap. If zero is supplied, the
+ default behaviour is to use an iterative method to evaluate the
+ inverse based only on the forward transformation (see attribute
+ IterInverse).
+ }
+ \sstsubsection{
+ COEFF\_I( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_POLYMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_POLYTRAN
+}{
+ 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
+ FORWARD 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 FORWARD
+ parameter specifies the transformation to be replaced. If it is
+ is .TRUE.,
+ 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 FORWARD is .FALSE. (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
+ MAXACC.
+ If it is not, a NULL pointer is returned but no error is reported.
+ }
+ \sstinvocation{
+ RESULT = AST\_POLYTRAN( THIS, FORWARD, ACC, MAXACC, MAXORDER, LBND,
+ UBND, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the original \htmlref{Mapping}{Mapping}.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ the forward PolyMap transformation is replaced. Otherwise the
+ inverse transformation is replaced.
+ }
+ \sstsubsection{
+ ACC = DOUBLE (Given)
+ }{
+ The target accuracy, expressed as a geodesic distance within
+ the PolyMap\texttt{'} s input space (if
+ FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
+ }
+ \sstsubsection{
+ MAXACC = DOUBLE (Given)
+ }{
+ The maximum allowed accuracy for an acceptable polynomial,
+ expressed as a geodesic distance within the PolyMap\texttt{'} s input
+ space (if
+ FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
+ }
+ \sstsubsection{
+ MAXORDER = INTEGER (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An
+ array holding the lower bounds of a rectangular region within
+ the PolyMap\texttt{'} s input space (if
+ FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
+ 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
+ FORWARD.
+ }
+ \sstsubsection{
+ UBND( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An
+ array holding the upper bounds of a rectangular region within
+ the PolyMap\texttt{'} s input space (if
+ FORWARD is .FALSE.) or output space (if FORWARD is .TRUE.).
+ 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
+ FORWARD.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ PolyMap
+ }{
+ All PolyMaps have this method.
+ }
+ \sstsubsection{
+ \htmlref{ChebyMap}{ChebyMap}
+ }{
+ The returned PolyMap will be a ChebyMap, and the new transformation
+ will be defined as a weighted sum of Chebyshev functions of the
+ first kind.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_POLYTRAN = INTEGER
+ }{
+ A pointer to the new PolyMap.
+ AST\_\_NULL
+ will be returned if the fit fails to achieve the accuracy
+ specified by
+ MAXACC,
+ but no error will be reported.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The \htmlref{IterInverse}{IterInverse} attribute is always cleared in the returned PolyMap.
+ This means that the returned PolyMap will always use the new fit by
+ default, rather than the iterative inverse, regardless of the setting
+ of IterInverse in the supplied PolyMap.
+
+ \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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PRISM
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_PRISM( REGION1, REGION2, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION1 = INTEGER (Given)
+ }{
+ Pointer to the Region to be extruded.
+ }
+ \sstsubsection{
+ REGION2 = INTEGER (Given)
+ }{
+ Pointer to the Region defining the extent of the extrusion.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_PRISM = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_PURGEROWS
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_PURGEROWS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_PURGEWCS
+}{
+ Delete all cards in the FitsChan describing WCS information
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_PURGEWCS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_PUTCARDS
+}{
+ Store a set of FITS header cards in a FitsChan
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_READ}{AST\_READ}
+ can be made immediately without the need to re-wind the FitsChan
+ first.
+ }
+ \sstinvocation{
+ CALL AST\_PUTCARDS( THIS, CARDS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ CARDS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ An error will result if the supplied string contains any cards
+ which cannot be interpreted.
+ }
+ }
+}
+\sstroutine{
+ AST\_PUTCOLUMNDATA
+}{
+ Store new data values for all rows of a column
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_PUTCOLUMNDATA( THIS, COLUMN, CLEN, SIZE, COLDATA, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{FitsTable}{FitsTable}.
+ }
+ \sstsubsection{
+ COLUMN = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The character string holding the name of the column. Trailing
+ spaces are ignored.
+ }
+ \sstsubsection{
+ CLEN = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The size of the
+ COLDATA
+ 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( $*$ ) = BYTE (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_PUTFITS
+}{
+ Store a FITS header card in a FitsChan
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_PUTFITS( THIS, CARD, OVERWRITE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ CARD = CHARACTER $*$ ( 80 ) (Given)
+ }{
+ A character string string containing the FITS card to be
+ stored. No more than 80 characters will be used from this
+ string.
+ }
+ \sstsubsection{
+ OVERWRITE = LOGICAL (Given)
+ }{
+ If this value is .FALSE., 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 .TRUE., 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_PUTLINE
+}{
+ Store a text line read by a Channel source routine
+}{
+ \sstdescription{
+ This routine should only be used when implementing a routine
+ which will be passed as the SOURCE argument to \htmlref{AST\_CHANNEL}{AST\_CHANNEL}. It
+ should be used to pass back (to the AST library) each line of
+ text read from the external data source. One such line should be
+ passed back in this way for each invocation of the source
+ routine.
+ }
+ \sstinvocation{
+ CALL AST\_PUTLINE( LINE, L, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ LINE = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the line of input text which
+ has been read.
+ }
+ \sstsubsection{
+ L = INTEGER (Given)
+ }{
+ The number of characters in the input line, which may be
+ zero. If there is no more input available (e.g. an end of
+ file has been reached), this value should be set negative and
+ this will terminate the read operation on the \htmlref{Channel}{Channel}.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine is only available in the Fortran interface to the
+ AST library.
+ }
+ }
+}
+\sstroutine{
+ AST\_PUTTABLE
+}{
+ Store a single FitsTable in a FitsChan
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_READ}{AST\_READ}, the \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE} routine
+ provides an alternative mechanism in which a caller-supplied
+ function is invoked to store a named table in the FitsChan.
+ }
+ \sstinvocation{
+ CALL AST\_PUTTABLE( THIS, TABLE, EXTNAM, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ TABLE = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The name of the FITS extension associated with the table.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Tables stored in the FitsChan may be retrieved using
+ \htmlref{AST\_GETTABLES}{AST\_GETTABLES}.
+
+ \sstitem
+ The \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES} method can add multiple FitsTables in a single call.
+ }
+ }
+}
+\sstroutine{
+ AST\_PUTTABLEHEADER
+}{
+ Store new FITS headers in a FitsTable
+}{
+ \sstdescription{
+ This routine
+ stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing
+ headers are first deleted.
+ }
+ \sstinvocation{
+ CALL AST\_PUTTABLEHEADER( THIS, HEADER, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsTable.
+ }
+ \sstsubsection{
+ HEADER = INTEGER (Given)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_PUTTABLES
+}{
+ Store one or more FitsTables in a FitsChan
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_READ}{AST\_READ}, the \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE} routine
+ provides an alternative mechanism in which a caller-supplied
+ function is invoked to store a named table in the FitsChan.
+ }
+ \sstinvocation{
+ CALL AST\_PUTTABLES( THIS, TABLES, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ TABLES = INTEGER (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Tables stored in the FitsChan may be retrieved using
+ \htmlref{AST\_GETTABLES}{AST\_GETTABLES}.
+
+ \sstitem
+ The tables in the supplied KeyMap are added to any tables already
+ in the FitsChan.
+
+ \sstitem
+ The \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}
+ method provides a simpler means of adding a single table to a FitsChan.
+ }
+ }
+}
+\sstroutine{
+ AST\_QUADAPPROX
+}{
+ 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
+ LBND and UBND.
+ 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 FIT
+ array is returned holding the values of the co-efficients a\_0\_0,
+ a\_0\_1, etc.
+ }
+ \sstinvocation{
+ RESULT = AST\_QUADAPPROX( THIS, LBND, UBND, NX, NY, FIT, RMS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping.
+ }
+ \sstsubsection{
+ LBND( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array
+ containing the upper bounds of the box specifying the region over
+ which the fit is to be performed.
+ }
+ \sstsubsection{
+ NX = INTEGER (Given)
+ }{
+ The number of points to place along the first Mapping input. The
+ first point is at
+ LBND( 1 ) and the last is at UBND( 1 ).
+ If a value less than three is supplied a value of three will be used.
+ }
+ \sstsubsection{
+ NY = INTEGER (Given)
+ }{
+ The number of points to place along the second Mapping input. The
+ first point is at
+ LBND( 2 ) and the last is at UBND( 2 ).
+ If a value less than three is supplied a value of three will be used.
+ }
+ \sstsubsection{
+ FIT( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array
+ 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(1) $+$ fit(2)$*$X\_in $+$ fit(3)$*$Y\_in $+$ fit(4)$*$X\_in$*$Y\_in $+$
+ fit(5)$*$X\_in$*$X\_in $+$ fit(6)$*$Y\_in$*$Y\_in
+ Y\_out = fit(7) $+$ fit(8)$*$X\_in $+$ fit(9)$*$Y\_in $+$ fit(10)$*$X\_in$*$Y\_in $+$
+ fit(11)$*$X\_in$*$X\_in $+$ fit(12)$*$Y\_in$*$Y\_in
+ }
+ \sstsubsection{
+ RMS = DOUBLE PRECISION (Returned)
+ }{
+ The
+ RMS residual between the fit and the Mapping, summed over all
+ Mapping outputs.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_QUADAPPROX = LOGICAL
+ }{
+ If a quadratic approximation was created,
+ .TRUE is returned. Otherwise .FALSE. 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{AST\_INVERT}{AST\_INVERT}
+ before invoking this function.
+
+ \sstitem
+ A value of .FALSE.
+ will be returned if this function is invoked
+ with the global error status set, or if it should fail for any
+ reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_RATE
+}{
+ Calculate the rate of change of a Mapping output
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_RATE( THIS, AT, AX1, AX2, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be applied.
+ }
+ \sstsubsection{
+ AT( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_RATE = DOUBLE PRECISION
+ }{
+ The rate of change of Mapping output AX1 with respect to input
+ AX2, evaluated at AT, 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{
+ AST\_RATEMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_RATEMAP( MAP, AX1, AX2, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ MAP = INTEGER (Given)
+ }{
+ Pointer to the encapsulated Mapping.
+ }
+ \sstsubsection{
+ AX1 = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_RATEMAP = INTEGER
+ }{
+ 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
+ AST\_RATEMAP (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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_READ
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_READ( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Channel.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{FitsChan}{FitsChan}
+ }{
+ All successful use of AST\_READ 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{AST\_RETAINFITS}{AST\_RETAINFITS} routine).
+ An unsuccessful call of
+ AST\_READ
+ (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
+ AST\_READ
+ 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{
+ AST\_READ = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it should fail
+ for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_READFITS
+}{
+ Read cards into a FitsChan from the source function
+}{
+ \sstdescription{
+ This routine
+ 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 routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_READFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ routine.
+ New cards are read from the source file whenever a new value is
+ assigned to the SourceFile attribute.
+ }
+ }
+}
+\sstroutine{
+ AST\_REBIN$<$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{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$} routines
+ 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 AST\_REBIN$<$X$>$ by an appropriate 1- or
+ 2-character type code. For example, if you are rebinning data
+ with type REAL, you should use the function AST\_REBINR (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
+ WLIM argument.
+
+ 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).
+ }
+ \sstinvocation{
+ CALL AST\_REBIN$<$X$>$( THIS, WLIM, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR,
+ SPREAD, PARAMS, FLAGS,
+ TOL, MAXPIX, BADVAL,
+ NDIM\_OUT, LBND\_OUT, UBND\_OUT,
+ LBND, UBND, OUT, OUT\_VAR, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ 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 NDIM\_IN
+ below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+ attribute) should match the number of output grid dimensions
+ given by NDIM\_OUT.
+ }
+ \sstsubsection{
+ WLIM = DOUBLE PRECISION (Given)
+ }{
+ 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
+ WLIM
+ value, then the output pixel value is returned set to the
+ supplied bad value.
+ }
+ \sstsubsection{
+ NDIM\_IN = INTEGER (Given)
+ }{
+ The number of dimensions in the input grid. This should be at
+ least one.
+ }
+ \sstsubsection{
+ LBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND\_IN and UBND\_IN 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. 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( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_REBINR, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ An optional second array with the same size and type as the
+ IN array. If the AST\_\_USEVAR flag is set via the FLAGS
+ argument (below), this array should contain a set of
+ non-negative values which represent estimates of the
+ statistical variance associated with each element of the IN
+ array. Estimates of the variance of the rebined output data
+ will then be calculated.
+
+ If the AST\_\_USEVAR flag is not set, no input variance
+ estimates are required and this array will not be used. A
+ dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ SPREAD = INTEGER (Given)
+ }{
+ This argument 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An optional array 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. A dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ The sum 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 MAXPIX
+ 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 TOL to zero). Although this may degrade
+ performance, accurate results will still be obtained.
+ }
+ \sstsubsection{
+ BADVAL = $<$Xtype$>$ (Given)
+ }{
+ This argument should have the same type as the elements of
+ the IN 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 FLAGS argument,
+ then this value is used to test for bad pixels in the IN
+ (and IN\_VAR) array(s).
+
+ In all cases, this value is also used to flag any output
+ elements in the OUT (and OUT\_VAR) 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 = INTEGER (Given)
+ }{
+ 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( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the output grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the output grid along each dimension.
+
+ Note that LBND\_OUT and UBND\_OUT together define the
+ shape, size and coordinate system of the output grid in the
+ same way as LBND\_IN and UBND\_IN define the shape, size
+ and coordinate system of the input grid.
+ }
+ \sstsubsection{
+ LBND( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ 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( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ 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 LBND and UBND 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 LBND\_IN and UBND\_IN arrays). Regions of
+ the input grid lying outside this region will not be used.
+ }
+ \sstsubsection{
+ OUT( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ 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 IN 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ An optional array with the same type and size as the OUT
+ array. If the AST\_\_USEVAR flag is set via the FLAGS argument,
+ this array will be used to return variance estimates for the
+ rebined data values.
+
+ 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 the AST\_\_USEVAR flag is not set, no output variance
+ estimates will be calculated and this array will not be
+ used. A dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate rebinning function, you should
+ replace $<$X$>$ in the generic function name AST\_REBIN$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_REBIND would be used to process DOUBLE
+ PRECISION data, while AST\_REBINI would be used to process
+ integer data (stored in an INTEGER array), etc.
+
+ Note that, unlike
+ \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}, the AST\_REBIN$<$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
+ AST\_RESAMPLE$<$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
+ AST\_RESAMPLE$<$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
+ AST\_PAR include file)
+ may be assigned to the
+ SPREAD
+ parameter. See the
+ AST\_RESAMPLE$<$X$>$
+ documentation for details of these schemes including the use of the
+ FSPREAD and PARAMS arguments:
+
+ \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
+ AST\_REBIN$<$X$>$ but not with AST\_RESAMPLE$<$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
+ PARAMS(2)
+ value and should be at least 0.1. The
+ PARAMS(1)
+ 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 AST\_PAR include file and
+ may be used to provide additional control over the rebinning
+ process. Having selected a set of flags, you should supply the
+ sum of their values via the FLAGS argument:
+
+ \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 BADVAL and propagated to the output array(s).
+ If this flag is not set, all input values are treated literally
+ and the BADVAL value is only used for flagging output array
+ values.
+
+ \sstitem
+ AST\_\_USEVAR: Indicates that variance information should be
+ processed in order to provide estimates of the statistical error
+ associated with the rebined values. If this flag is not set,
+ no variance processing will occur and the IN\_VAR and OUT\_VAR
+ arrays will not be used. (Note that this flag is only available
+ in the Fortran interface to AST.)
+ }
+ }
+ \sstdiytopic{
+ Propagation of Missing Data
+ }{
+ Instances of missing data (bad pixels) in the output grid are
+ identified by occurrences of the BADVAL value in the OUT
+ array. These are produced if the sum of the weights of the
+ contributing input pixels is less than
+ WLIM.
+
+ An input pixel is considered bad (and is consequently ignored) if
+ its
+ data value is equal to BADVAL and the AST\_\_USEBAD flag is
+ set via the FLAGS argument.
+
+ In addition, associated output variance estimates (if
+ calculated) may be declared bad and flagged with the BADVAL
+ value in the OUT\_VAR array for similar reasons.
+ }
+}
+\sstroutine{
+ AST\_REBINSEQ$<$X$>$
+}{
+ Rebin a region of a sequence of data grids
+}{
+ \sstdescription{
+ This set of
+ routines is identical to \htmlref{AST\_REBIN$<$X$>$}{AST\_REBIN$<$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
+ routine
+ 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
+ FLAGS argument.
+ 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{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$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
+ WLIM are set to BADVAL.
+
+ 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).
+ }
+ \sstinvocation{
+ CALL AST\_REBINSEQ$<$X$>$( THIS, WLIM, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR,
+ SPREAD, PARAMS, FLAGS, TOL, MAXPIX, BADVAL,
+ NDIM\_OUT, LBND\_OUT, UBND\_OUT, LBND, UBND, OUT,
+ OUT\_VAR, WEIGHTS, NUSED, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ 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 NDIM\_IN
+ below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+ attribute) should match the number of output grid dimensions
+ given by NDIM\_OUT.
+ }
+ \sstsubsection{
+ WLIM = DOUBLE PRECISION (Given)
+ }{
+ This value is only used if the AST\_\_REBINEND flag is specified
+ via the
+ FLAGS argument.
+ 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
+ WLIM
+ 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 = INTEGER (Given)
+ }{
+ The number of dimensions in the input grid. This should be at
+ least one.
+ }
+ \sstsubsection{
+ LBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND\_IN and UBND\_IN 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. 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( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_REBINSEQR, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ An optional
+ second array with the same size and type as the
+ IN
+ 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
+ IN
+ array.
+ If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no
+ input variance estimates are required and this
+ array
+ will not be used.
+ A dummy (e.g. one-element) array
+ may then be supplied.
+ }
+ \sstsubsection{
+ SPREAD = INTEGER (Given)
+ }{
+ This argument 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
+ AST\_REBIN$<$X$>$ routines.
+ If a value of zero is supplied, then the default linear spreading
+ scheme is used (equivalent to supplying the value AST\_\_LINEAR).
+ }
+ \sstsubsection{
+ PARAMS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An optional array 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
+ AST\_REBIN$<$X$>$ routines.
+
+ If no additional parameters are required, this array is not
+ used. A dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ The sum 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 MAXPIX
+ 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 TOL to zero). Although this may degrade
+ performance, accurate results will still be obtained.
+ }
+ \sstsubsection{
+ BADVAL = $<$Xtype$>$ (Given)
+ }{
+ This argument should have the same type as the elements of
+ the IN 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 FLAGS argument,
+ then this value is used to test for bad pixels in the IN
+ (and IN\_VAR) array(s).
+
+ In all cases, this value is also used to flag any output
+ elements in the OUT (and OUT\_VAR) 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 = INTEGER (Given)
+ }{
+ 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( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the output grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the output grid along each dimension.
+
+ Note that LBND\_OUT and UBND\_OUT together define the
+ shape, size and coordinate system of the output grid in the
+ same way as LBND\_IN and UBND\_IN define the shape, size
+ and coordinate system of the input grid.
+ }
+ \sstsubsection{
+ LBND( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ 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( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ 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 LBND and UBND 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 LBND\_IN and UBND\_IN arrays). Regions of
+ the input grid lying outside this region will not be used.
+ }
+ \sstsubsection{
+ OUT( $*$ ) = $<$Xtype$>$ (Given and Returned)
+ }{
+ 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
+ IN 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Given and Returned)
+ }{
+ A
+ array with the same type and size as the
+ OUT
+ array. This
+ array
+ will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set
+ via the FLAGS argument,
+ via the \texttt{"} flags\texttt{"} parameter,
+ 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
+ array
+ will not be used. A
+ dummy (e.g. one-element) array
+ may then be supplied.
+ }
+ \sstsubsection{
+ WEIGHTS( $*$ ) = DOUBLE PRECISION (Given and Returned)
+ }{
+ An array
+ 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
+ FLAGS 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ NUSED = INTEGER$*$8 (Given and Returned)
+ }{
+ 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
+ FLAGS.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstdiytopic{
+ Data Type Codes
+ }{
+ To select the appropriate rebinning function, you should
+ replace $<$X$>$ in the generic function name AST\_REBINSEQ$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_REBIND would be used to process DOUBLE
+ PRECISION data, while AST\_REBINI would be used to process
+ integer data (stored in an INTEGER array), etc.
+
+ Note that, unlike
+ AST\_RESAMPLE$<$X$>$, the AST\_REBINSEQ$<$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 AST\_PAR include file and
+ may be used to provide additional control over the rebinning
+ process. Having selected a set of flags, you should supply the
+ sum of their values via the FLAGS argument:
+
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates
+ that the supplied
+ OUT, OUT\_VAR and WEIGHTS
+ 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
+ OUT and OUT\_VAR
+ 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
+ argument WLIM.
+ 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 BADVAL and propagated to the output array(s).
+ If this flag is not set, all input values are treated literally
+ and the BADVAL 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
+ routine
+ 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. See also AST\_\_PARWGT.
+
+ \sstitem
+ AST\_\_PARWGT: Indicates that a constant weight should be used when
+ pasting each pixel of the supplied input array into the returned
+ arrays. This extra weight value should be inserted at the start of the
+ \texttt{'} PARAMS
+ array (which should consequently be one element longer than specified in
+ the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the description of the
+ AST\_REBIN$<$X$>$ routines).
+ If the AST\_\_VARWGT flag is also specified, the total weight for
+ each pixel is the product of the reciprocal of the pixel variance
+ and the value supplied in the last element of the
+ \texttt{'} PARAMS array.
+
+ \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
+ WEIGHTS and NUSED are ignored.
+ This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR,
+ AST\_\_PARWGT 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.
+ (i.e. AST\_REBINSEQ$<$F$>$ behaves similarly to AST\_RESAMPLE$<$X$>$). This
+ (i.e. AST\_REBINSEQ$<$F$>$ behaves similarly to AST\_RESAMPLE$<$X$>$). 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 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
+ TOL argument
+ 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
+ TOL argument
+ until the difference between adjacent panels is sufficiently small
+ to be insignificant.
+
+ This flag should normally be supplied on each invocation of
+ AST\_REBINSEQ$<$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 BADVAL value in the OUT
+ 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 BADVAL and the AST\_\_USEBAD flag is
+ set via the FLAGS argument.
+
+ In addition, associated output variance estimates (if
+ calculated) may be declared bad and flagged with the BADVAL
+ value in the OUT\_VAR array for similar reasons.
+ }
+}
+\sstroutine{
+ AST\_REMAPFRAME
+}{
+ Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet
+}{
+ \sstdescription{
+ This routine 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 routine.
+ }
+ \sstinvocation{
+ CALL AST\_REMAPFRAME( THIS, IFRAME, MAP, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+ IFRAME argument 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 routine,
+ 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{AST\_PERMAXES}{AST\_PERMAXES} routine may provide a more straightforward method
+ of making the required changes to the FrameSet.
+
+ \sstitem
+ This routine cannot be used to change the number of Frame
+ axes. To achieve this, a new Frame must be added to the FrameSet
+ (\htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}) and the original one removed if necessary
+ (\htmlref{AST\_REMOVEFRAME}{AST\_REMOVEFRAME}).
+
+ \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{
+ AST\_REMOVECOLUMN
+}{
+ Remove a column from a table
+}{
+ \sstdescription{
+ This function removes a specified column from the supplied table.
+ The
+ routine
+ returns without action if the named column does not exist in the
+ \htmlref{Table}{Table} (no error is reported).
+ }
+ \sstinvocation{
+ CALL AST\_REMOVECOLUMN( THIS, NAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The column name. Trailing spaces are ignored (all other spaces
+ are significant). Case is significant.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_REMOVEFRAME
+}{
+ Remove a Frame from a FrameSet
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_REMOVEFRAME( THIS, IFRAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FrameSet.
+ }
+ \sstsubsection{
+ IFRAME = INTEGER (Given)
+ }{
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ IFRAME argument 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{
+ AST\_REMOVEPARAMETER
+}{
+ Remove a global parameter from a table
+}{
+ \sstdescription{
+ This function removes a specified global parameter from the supplied table.
+ The
+ routine
+ returns without action if the named parameter does not exist in the
+ \htmlref{Table}{Table} (no error is reported).
+ }
+ \sstinvocation{
+ CALL AST\_REMOVEPARAMETER( THIS, NAME, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The parameter name. Trailing spaces are ignored (all other spaces
+ are significant). Case is significant.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_REMOVEREGIONS
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_REMOVEREGIONS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the original Mapping.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 replaced 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{
+ AST\_REMOVEREGIONS = INTEGER
+ }{
+ 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{AST\_CLONE}{AST\_CLONE} 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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_REMOVEROW
+}{
+ Remove a row from a table
+}{
+ \sstdescription{
+ This function removes a specified row from the supplied table.
+ The
+ routine
+ returns without action if the row does not exist in the
+ \htmlref{Table}{Table} (no error is reported).
+ }
+ \sstinvocation{
+ CALL AST\_REMOVEROW( THIS, INDEX, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Table.
+ }
+ \sstsubsection{
+ INDEX = INTEGER (Given)
+ }{
+ The index of the row to be removed. The first row has index 1.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_REMOVETABLES
+}{
+ Remove one or more tables from a FitsChan
+}{
+ \sstdescription{
+ This routine
+ removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error
+ is reported if any the tables do not exist).
+ }
+ \sstinvocation{
+ CALL AST\_REMOVETABLES( THIS, KEY, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ KEY = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_RESAMPLE$<$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 AST\_RESAMPLE$<$X$>$ by an appropriate 1- or
+ 2-character type code. For example, if you are resampling data
+ with type REAL, you should use the function AST\_RESAMPLER (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{AST\_REBIN$<$X$>$}{AST\_REBIN$<$X$>$} or \htmlref{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$} family of routines
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_RESAMPLE$<$X$>$( THIS, NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR,
+ INTERP, FINTERP, PARAMS, FLAGS,
+ TOL, MAXPIX, BADVAL,
+ NDIM\_OUT, LBND\_OUT, UBND\_OUT,
+ LBND, UBND, OUT, OUT\_VAR, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ 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 NDIM\_IN
+ below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+ attribute) should match the number of output grid dimensions
+ given by NDIM\_OUT.
+ }
+ \sstsubsection{
+ NDIM\_IN = INTEGER (Given)
+ }{
+ The number of dimensions in the input grid. This should be at
+ least one.
+ }
+ \sstsubsection{
+ LBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND\_IN and UBND\_IN 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. 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( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_RESAMPLER, the type of each array element
+ should be REAL).
+
+ 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ An optional second array with the same size and type as the
+ IN array. If the AST\_\_USEVAR flag is set via the FLAGS
+ argument (below), this array should contain a set of
+ non-negative values which represent estimates of the
+ statistical variance associated with each element of the IN
+ array. Estimates of the variance of the resampled output data
+ will then be calculated.
+
+ If the AST\_\_USEVAR flag is not set, no input variance
+ estimates are required and this array will not be used. A
+ dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ INTERP = INTEGER (Given)
+ }{
+ This argument 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 routine to perform sub-pixel
+ interpolation by means of the FINTERP argument. Again, see
+ the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below for
+ details.
+ }
+ \sstsubsection{
+ FINTERP = SUBROUTINE (Given)
+ }{
+ If the value given for the INTERP argument indicates that you
+ will provide your own routine for sub-pixel interpolation,
+ then the name of that routine should be given here (the name
+ should also appear in a Fortran EXTERNAL statement in the
+ routine which invokes AST\_RESAMPLE$<$X$>$). For details of the
+ interface which the routine should have (several are
+ possible, depending on the value of INTERP), see the
+ \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below.
+
+ If the INTERP argument has any other value, corresponding to
+ one of the pre-defined interpolation schemes, then this
+ routine will not be used and you may supply the null routine
+ AST\_NULL here (note only one underscore). No EXTERNAL
+ statement is required for this routine, so long as the AST\_PAR
+ include file has been used.
+ }
+ \sstsubsection{
+ PARAMS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An optional array 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 routine).
+
+ If no additional parameters are required, this array is not
+ used. A dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ The sum 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 MAXPIX
+ 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 TOL to zero). Although this may degrade
+ performance, accurate results will still be obtained.
+ }
+ \sstsubsection{
+ BADVAL = $<$Xtype$>$ (Given)
+ }{
+ This argument should have the same type as the elements of
+ the IN 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 FLAGS argument,
+ then this value is used to test for bad pixels in the IN
+ (and IN\_VAR) array(s).
+
+ Unless the AST\_\_NOBAD flag is set via the FLAGS argument,
+ this value is also used to flag any output
+ elements in the OUT (and OUT\_VAR) 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 AST\_RESAMPLE$<$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 = INTEGER (Given)
+ }{
+ 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( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the output grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_OUT( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the output grid along each dimension.
+
+ Note that LBND\_OUT and UBND\_OUT together define the
+ shape, size and coordinate system of the output grid in the
+ same way as LBND\_IN and UBND\_IN define the shape, size
+ and coordinate system of the input grid.
+ }
+ \sstsubsection{
+ LBND( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ 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( NDIM\_OUT ) = INTEGER (Given)
+ }{
+ An array
+ 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 LBND and UBND 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 LBND\_OUT and UBND\_OUT arrays). Regions of
+ the output grid lying outside this region will not be
+ modified.
+ }
+ \sstsubsection{
+ OUT( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ 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 IN 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. normal Fortran array storage order).
+ }
+ \sstsubsection{
+ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ An optional array with the same type and size as the OUT
+ array. If the AST\_\_USEVAR flag is set via the FLAGS argument,
+ this array will be used to return variance estimates for the
+ resampled data values.
+
+ 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 the AST\_\_USEVAR flag is not set, no output variance
+ estimates will be calculated and this array will not be
+ used. A dummy (e.g. one-element) array may then be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_RESAMPLE$<$X$>$ = INTEGER
+ }{
+ 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
+ BADVAL and FLAGS arguments.
+ }
+ }
+ \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 AST\_RESAMPLE$<$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 PRECISION
+
+ \sstitem
+ R: REAL
+
+ \sstitem
+ I: INTEGER
+
+ \sstitem
+ UI: INTEGER (treated as unsigned)
+
+ \sstitem
+ S: INTEGER$*$2 (short integer)
+
+ \sstitem
+ US: INTEGER$*$2 (short integer, treated as unsigned)
+
+ \sstitem
+ B: BYTE (treated as signed)
+
+ \sstitem
+ UB: BYTE (treated as unsigned)
+
+ }
+ For example, AST\_RESAMPLED would be used to process DOUBLE
+ PRECISION data, while AST\_RESAMPLES would be used to process
+ short integer data (stored in an INTEGER$*$2 array), etc.
+
+ For compatibility with other Starlink facilities, the codes W
+ and UW are provided as synonyms for S and US respectively (but
+ only in the Fortran interface to AST).
+ }
+ \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 AST\_PAR include
+ file) via the INTERP argument. In these cases, the FINTERP
+ and PARAMS arguments 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 PARAMS 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 PARAMS(1)
+ to indicate that a suitable number of pixels should be calculated
+ automatically.
+
+ In each of these cases, the FINTERP argument 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
+ PARAMS(2)
+ value, which should be at least 0.1 (in addition, setting PARAMS(1)
+ 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 PARAMS(1) 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 PARAMS(2) value, which should be at least 1.0 (in addition,
+ setting PARAMS(1) 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 PARAMS(1)=2, PARAMS(2)=2 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 PARAMS(2) value, which should be at least 1.0 (in addition,
+ setting PARAMS(1) 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 PARAMS(2)
+ value, which should be at least 0.1 (in addition, setting PARAMS(1)
+ 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 PARAMS(2), 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 PARAMS array, which gives
+ the number of pixels in each dimension on either side of the
+ central point. Hence a block of (2 $*$ PARAMS(1))$*$$*$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
+ (USEVAR = .FALSE.) 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(1) may be R/2.
+
+ }
+ Finally, supplying the following values for INTERP allows you to
+ implement your own sub-pixel interpolation scheme by means of
+ your own routine. You should supply the name of this routine via
+ the FINTERP argument:
+
+ \sstitemlist{
+
+ \sstitem
+ AST\_\_UKERN1: In this scheme, you supply a routine to evaluate
+ your own 1-dimensional interpolation kernel, which is then used
+ to perform sub-pixel interpolation (as described above). The
+ routine you supply should have the same interface as the
+ fictitious \htmlref{AST\_UKERN1}{AST\_UKERN1} routine (q.v.). In addition, a value
+ should be given via PARAMS(1) 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 PARAMS array
+ are available to pass values to your interpolation routine.
+
+ \sstitem
+ AST\_\_UINTERP: This is a completely general scheme, in which
+ your interpolation routine 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 AST\_RESAMPLE$<$X$>$ functions play no
+ role in the sub-pixel interpolation process and simply handle
+ the geometrical transformation of coordinates and other
+ housekeeping. The routine you supply should have the same
+ interface as the fictitious \htmlref{AST\_UINTERP}{AST\_UINTERP} routine (q.v.). In this
+ case, the PARAMS argument is not used by AST\_RESAMPLE$<$X$>$, but
+ is available to pass values to your interpolation routine.
+ }
+ }
+ \sstdiytopic{
+ Control Flags
+ }{
+ The following flags are defined in the AST\_PAR include file and
+ may be used to provide additional control over the resampling
+ process. Having selected a set of flags, you should supply the
+ sum of their values via the FLAGS argument:
+
+ \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
+ argument BADVAL. 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 routine 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 BADVAL and propagated to the output array(s).
+ If this flag is not set, all input values are treated literally
+ and the BADVAL value is only used for flagging output array
+ values.
+
+ \sstitem
+ AST\_\_USEVAR: Indicates that variance information should be
+ processed in order to provide estimates of the statistical error
+ associated with the resampled values. If this flag is not set,
+ no variance processing will occur and the IN\_VAR and OUT\_VAR
+ arrays will not be used. (Note that this flag is only available
+ in the Fortran interface to AST.)
+
+ \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
+ TOL argument
+ 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
+ TOL argument
+ 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 BADVAL value in the OUT
+ 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 BADVAL and the AST\_\_USEBAD flag is
+ set via the FLAGS argument.
+ (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 OUT array.
+
+ }
+ In addition, associated output variance estimates (if
+ calculated) may be declared bad and flagged with the BADVAL
+ value in the OUT\_VAR array under any of the following
+ circumstances:
+
+ \sstitemlist{
+
+ \sstitem
+ The associated resampled data value (in the OUT 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
+ BADVAL (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 OUT\_VAR array.
+
+ }
+ If the AST\_\_NOBAD flag is specified via
+ argument FLAGS,
+ then output array elements that would otherwise be set to
+ BADVAL
+ 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{
+ AST\_RESOLVE
+}{
+ Resolve a vector into two orthogonal components
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_RESOLVE( THIS, POINT1, POINT2, POINT3, POINT4, D1, D2,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Frame}{Frame}.
+ }
+ \sstsubsection{
+ POINT1( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute). This marks the end of the basis vector.
+ }
+ \sstsubsection{
+ POINT3( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ An array with one element for each Frame axis
+ (Naxes attribute). This marks the end of the vector to be
+ resolved.
+ }
+ \sstsubsection{
+ POINT4( $*$ ) = DOUBLE PRECISION (Returned)
+ }{
+ An array 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 = DOUBLE PRECISION (Returned)
+ }{
+ 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 = DOUBLE PRECISION (Returned)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Each vector used in this routine is the path of
+ shortest distance between two points, as defined by the
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE} 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{
+ AST\_RETAINFITS
+}{
+ Indicate that the current card in a FitsChan should be retained
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_READ}{AST\_READ}.
+
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_RETAINFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_RegionOutline
+}{
+ Draw the outline of an AST Region
+}{
+ \sstdescription{
+ This function draws an outline around the supplied AST \htmlref{Region}{Region} object.
+ }
+ \sstinvocation{
+ CALL AST\_REGIONOUTLINE( THIS, REGION, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{Plot}{Plot}.
+ }
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_SAME
+}{
+ Test if two AST pointers refer to the same Object
+}{
+ \sstdescription{
+ This function returns a logical result to indicate
+ whether two pointers refer to the same \htmlref{Object}{Object}.
+ }
+ \sstinvocation{
+ RESULT = AST\_SAME( THIS, THAT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the first Object.
+ }
+ \sstsubsection{
+ THAT = INTEGER (Given)
+ }{
+ Pointer to the second Object.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SAME = LOGICAL
+ }{
+ .TRUE. if the two pointers refer to the same Object, otherwise
+ .FALSE.
+ }
+ }
+ \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 .FALSE. will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SELECTORMAP
+}{
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+
+ In practice, SelectorMaps are often used in conjunction with SwitchMaps.
+ }
+ \sstinvocation{
+ RESULT = AST\_SELECTORMAP( NREG, REGS, BADVAL, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NREG = INTEGER (Given)
+ }{
+ The number of supplied Regions.
+ }
+ \sstsubsection{
+ REGS( NREG ) = INTEGER (Given)
+ }{
+ 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SELECTORMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SET
+}{
+ Set attribute values for an Object
+}{
+ \sstdescription{
+ This routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_SET( THIS, SETTINGS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ SETTINGS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing a comma-separated list of
+ attribute settings in the form described above.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ CALL AST\_SET( MAP, \texttt{'} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{'} , STATUS )
+ }{
+ Sets the Report attribute for Object MAP to the value 1 and
+ the Zoom attribute to 25.0.
+ }
+ \sstexamplesubsection{
+ CALL AST\_SET( FRAME, \texttt{'} Label( 1 ) =Offset from cluster axis\texttt{'} , STATUS )
+ }{
+ Sets the Label(1) attribute for Object FRAME to a suitable
+ string.
+ }
+ }
+ \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.
+
+ \sstitem
+ An error will result if an attempt is made to set a value for
+ a read-only attribute.
+ }
+ }
+}
+\sstroutine{
+ AST\_SET$<$X$>$
+}{
+ Set an attribute value for an Object
+}{
+ \sstdescription{
+ This is a family of routines 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 routine name
+ by C, D, I, L or R, to supply a value in Character, Double
+ precision, Integer, Logical or Real 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.
+ }
+ \sstinvocation{
+ CALL AST\_SET$<$X$>$( THIS, ATTRIB, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ ATTRIB = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the name of the attribute whose
+ value is to be set.
+ }
+ \sstsubsection{
+ VALUE = $<$X$>$type (Given)
+ }{
+ The value to be set for the attribute, in the data type corresponding
+ to $<$X$>$.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ These routines apply to all Objects.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ CALL AST\_SETC( PLOT, \texttt{'} \htmlref{Title}{Title}\texttt{'} , CVALUE, STATUS )
+ }{
+ Sets the Title attribute value for Object PLOT to the contents
+ of the character variable CVALUE.
+ }
+ \sstexamplesubsection{
+ CALL AST\_SETL( FRAME, \texttt{'} Preserve\texttt{'} , .TRUE., STATUS );
+ }{
+ Sets the Preserve attribute value for Object FRAME to 1 (true).
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Attribute names are not case sensitive and may be surrounded
+ by white space.
+
+ \sstitem
+ The logical value .FALSE. will translate to a numerical attribute
+ value of zero and logical .TRUE. will translate to one.
+
+ \sstitem
+ An error will result if an attempt is made to set a value for
+ a read-only attribute.
+ }
+ }
+}
+\sstroutine{
+ AST\_SETACTIVEUNIT
+}{
+ Specify how the Unit attribute should be used
+}{
+ \sstdescription{
+ This routine
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT})
+ 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
+ .FALSE.,
+ 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
+ .TRUE.,
+ 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 .TRUE., 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 .TRUE. 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).
+ }
+ \sstinvocation{
+ CALL AST\_SETACTIVEUNIT( THIS, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ VALUE = LOGICAL (Given)
+ }{
+ The new value to use.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{SkyFrame}{SkyFrame}
+ }{
+ The ActiveUnit flag for a SkyFrame is always .FALSE. (any value
+ supplied using this routine is ignored).
+ }
+ \sstsubsection{
+ \htmlref{SpecFrame}{SpecFrame}
+ }{
+ The ActiveUnit flag for a SpecFrame is always .TRUE. (any value
+ supplied using this routine is ignored).
+ }
+ \sstsubsection{
+ \htmlref{FluxFrame}{FluxFrame}
+ }{
+ The ActiveUnit flag for a FluxFrame is always .TRUE. (any value
+ supplied using this routine is ignored).
+ }
+ \sstsubsection{
+ \htmlref{CmpFrame}{CmpFrame}
+ }{
+ The default ActiveUnit flag for a CmpFrame is .TRUE. if both of the
+ component Frames are using active units, and .FALSE. 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{AST\_GET$<$X$>$}{AST\_GET$<$X$>$} and \htmlref{AST\_SET$<$X$>$}{AST\_SET$<$X$>$} routines.
+
+ \sstitem
+ The \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT} routine can be used to retrieve the current
+ value of the ActiveUnit flag.
+ }
+ }
+}
+\sstroutine{
+ AST\_SETFITS$<$X$>$
+}{
+ Store a keyword value in a FitsChan
+}{
+ \sstdescription{
+ This is a family of routines 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 routine 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 - DOUBLE PRECISION(2) (a 2 element array holding the real and
+ imaginary parts of the complex value).
+
+ \sstitem
+ CI - INTEGER(2) (a 2 element array holding the real and imaginary
+ parts of the complex value).
+
+ \sstitem
+ F - DOUBLE PRECISION.
+
+ \sstitem
+ I - INTEGER
+
+ \sstitem
+ L - LOGICAL
+
+ \sstitem
+ S - CHARACTER
+
+ \sstitem
+ CN - CHARACTER
+ }
+ }
+ \sstinvocation{
+ CALL AST\_SETFITS$<$X$>$( THIS, NAME, VALUE, COMMENT, OVERWRITE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 = $<$X$>$type (Given)
+ }{
+ The keyword value to store with the named keyword. The data type
+ of this parameter depends on $<$X$>$ as described above.
+ }
+ \sstsubsection{
+ COMMENT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A string
+ holding a comment to associated with the keyword.
+ If
+ a blank string is supplied, then any comment included in the string
+ supplied for the
+ NAME parameter is used instead. If NAME
+ 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 = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ 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
+ .FALSE.,
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The
+ routine \htmlref{AST\_SETFITSU}{AST\_SETFITSU}
+ can be used to indicate that no value is associated with a keyword.
+
+ \sstitem
+ The
+ routine \htmlref{AST\_SETFITSCM}{AST\_SETFITSCM}
+ 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{AST\_FINDFITS}{AST\_FINDFITS}, and
+ then use one of the AST\_SETFITS$<$X$>$ family to over-write the old value.
+
+ \sstitem
+ If, on exit, there are no cards following the card written by
+ this routine, 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{
+ AST\_SETFITSCM
+}{
+ Store a comment card in a FitsChan
+}{
+ \sstdescription{
+ This
+ routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_SETFITSCM( THIS, COMMENT, OVERWRITE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ COMMENT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A string
+ holding the text of the comment card.
+ If
+ a blank string is supplied, then a totally blank card is produced.
+ }
+ \sstsubsection{
+ OVERWRITE = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ 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
+ .FALSE.,
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_SETFITSU
+}{
+ Store an undefined keyword value in a FitsChan
+}{
+ \sstdescription{
+ This
+ routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_SETFITSU( THIS, NAME, COMMENT, OVERWRITE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A string
+ holding a comment to associated with the keyword.
+ If
+ a blank string is supplied, then any comment included in the string
+ supplied for the
+ NAME parameter is used instead. If NAME
+ 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 = LOGICAL (Given)
+ }{
+ If .TRUE.,
+ 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
+ .FALSE.,
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_SETPUTERR
+}{
+ Register an error handling routine for use by the AST error model
+}{
+ \sstdescription{
+ This function can be used to register an external function to be
+ used to deliver an error message and (optionally) an accompanying
+ status value to the user.
+
+ If this function is not called prior to the first error occuring
+ within AST, then the external error handling function selected at
+ link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use an
+ alternative error handler, call this function before using any other
+ AST functions, specifying the external error handling function to be
+ used. This will register the function for future use.
+ }
+ \sstinvocation{
+ CALL \htmlref{AST\_GRFSET}{AST\_GRFSET}( FUN, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FUN = INTEGER FUNCTION (Given)
+ }{
+ The name of the routine to be used to handle errors (the name
+ should also appear in a Fortran EXTERNAL statement in the
+ routine which invokes AST\_SETPUTERR).
+ Once a routine has been provided, the \texttt{"} null\texttt{"} routine AST\_NULL can
+ be supplied in a subsequent call to astSetPutErr to reset the routine
+ to the corresponding routine selected at link-time. AST\_NULL is
+ defined in the AST\_PAR include file.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstdiytopic{
+ Function Interface
+ }{
+ The supplied external function should deliver the supplied error message
+ and (optionally) the supplied status value to the user or to some
+ underlying error system. It requires the following interface:
+
+ SUBROUTINE PUTERR( STATUS\_VALUE, MESSAGE )
+
+ \sstitemlist{
+
+ \sstitem
+ STATUS\_VALUE = INTEGER (Given) -
+ The error status value.
+
+ \sstitem
+ MESSAGE = CHARACTER $*$ ( $*$ ) (Given) - The error message to be delivered.
+ }
+ }
+}
+\sstroutine{
+ AST\_SETREFPOS
+}{
+ Set the reference position in a specified celestial coordinate system
+}{
+ \sstdescription{
+ This routine
+ 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}.
+ }
+ \sstinvocation{
+ CALL AST\_SETREFPOS( THIS, FRM, LON, LAT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the \htmlref{SpecFrame}{SpecFrame}.
+ }
+ \sstsubsection{
+ FRM = INTEGER (Given)
+ }{
+ Pointer to the SkyFrame which defines the celestial coordinate
+ system in which the longitude and latitude values are supplied.
+ If AST\_\_NULL
+ is supplied, then the supplied longitude and latitude values are
+ assumed to be FK5 J2000 RA and Dec values.
+ }
+ \sstsubsection{
+ LON = DOUBLE PRECISION (Given)
+ }{
+ The longitude of the reference point, in the coordinate system
+ represented by the supplied SkyFrame (radians).
+ }
+ \sstsubsection{
+ LAT = DOUBLE PRECISION (Given)
+ }{
+ The latitude of the reference point, in the coordinate system
+ represented by the supplied SkyFrame (radians).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_SETUNC
+}{
+ 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
+ routine
+ allows it to be changed at any time.
+ }
+ \sstinvocation{
+ CALL AST\_SETUNC( THIS, UNC, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region which is to be assigned a new uncertainty.
+ }
+ \sstsubsection{
+ UNC = INTEGER (Given)
+ }{
+ 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
+ THIS.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_SHIFTMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_SHIFTMAP( NCOORD, SHIFT, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SHIFTMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_SHOW
+}{
+ Display a textual representation of an Object on standard output
+}{
+ \sstdescription{
+ This routine displays a textual description of any AST \htmlref{Object}{Object}
+ on standard output. It is provided primarily as an aid to
+ debugging.
+ }
+ \sstinvocation{
+ CALL AST\_SHOW( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object to be displayed.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+}
+\sstroutine{
+ AST\_SHOWFITS
+}{
+ Display the contents of a FitsChan on standard output
+}{
+ \sstdescription{
+ This routine
+ formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output.
+ }
+ \sstinvocation{
+ CALL AST\_SHOWFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_SHOWMESH
+}{
+ Display a mesh of points covering the surface of a Region
+}{
+ \sstdescription{
+ This routine
+ 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{"} .
+ }
+ \sstinvocation{
+ CALL AST\_SHOWMESH( THIS, FORMAT, TTL, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Region.
+ }
+ \sstsubsection{
+ FORMAT = LOGICAL (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A title to display before displaying the first position.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+}
+\sstroutine{
+ AST\_SIMPLIFY
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_SIMPLIFY( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the original Mapping.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_SIMPLIFY = INTEGER
+ }{
+ 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{AST\_CLONE}{AST\_CLONE} 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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SKYFRAME
+}{
+ 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{AST\_FORMAT}{AST\_FORMAT}.
+ }
+ \sstinvocation{
+ RESULT = AST\_SKYFRAME( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SKYFRAME = INTEGER
+ }{
+ A pointer to the new SkyFrame.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ FRAME = AST\_SKYFRAME( \texttt{'} \texttt{'} , STATUS )
+ }{
+ Creates a SkyFrame to describe the default ICRS celestial
+ coordinate system.
+ }
+ \sstexamplesubsection{
+ FRAME = AST\_SKYFRAME( \texttt{'} System = FK5, Equinox = J2005, Digits = 10\texttt{'} , STATUS )
+ }{
+ 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 = AST\_SKYFRAME( \texttt{'} System = FK4, Equinox = 1955-SEP-2\texttt{'} , STATUS )
+ }{
+ 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 = AST\_SKYFRAME( \texttt{'} System = GAPPT, Epoch = \texttt{'} // DATE, STATUS )
+ }{
+ 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
+ contained in the character variable DATE.
+ }
+ }
+ \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
+ OPTIONS 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{AST\_PERMAXES}{AST\_PERMAXES} if required.
+
+ \sstitem
+ When conversion between two SkyFrames is requested (as when
+ supplying SkyFrames \htmlref{AST\_CONVERT}{AST\_CONVERT}),
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SKYOFFSETMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_SKYOFFSETMAP( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the SkyFrame.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SKYOFFSETMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SLAADD
+}{
+ Add a celestial coordinate conversion to an SlaMap
+}{
+ \sstdescription{
+ This routine 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{AST\_SLAMAP}{AST\_SLAMAP}), it simply
+ performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_SLAADD (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
+ AST\_SLAADD 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.
+ }
+ \sstinvocation{
+ CALL AST\_SLAADD( THIS, CVT, NARG, ARGS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the SlaMap.
+ }
+ \sstsubsection{
+ CVT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{
+ NARG = INTEGER (Given)
+ }{
+ The number of argument values supplied in the
+ ARGS array.
+ }
+ \sstsubsection{
+ ARGS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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
+ if no arguments are needed.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting
+ SlaMap. The simplification process will eliminate any steps
+ which turn out not to be needed.
+
+ \sstitem
+ This routine 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 CVT argument 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 ARGS 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 AST\_SLAADD in ARGS(1).
+
+ 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{
+ AST\_SLAMAP
+}{
+ 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{AST\_SLAADD}{AST\_SLAADD}
+ routine, 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 AST\_SLAADD routine.
+ }
+ \sstinvocation{
+ RESULT = AST\_SLAMAP( FLAGS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This argument is reserved for future use and should currently
+ always be set to zero.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SLAMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SPECADD
+}{
+ Add a spectral coordinate conversion to a SpecMap
+}{
+ \sstdescription{
+ This routine 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{AST\_SPECMAP}{AST\_SPECMAP}), it simply
+ performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_SPECADD (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
+ AST\_SPECADD 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.
+ }
+ \sstinvocation{
+ CALL AST\_SPECADD( THIS, CVT, NARG, ARGS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the SpecMap.
+ }
+ \sstsubsection{
+ CVT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{
+ NARG = INTEGER (Given)
+ }{
+ The number of argument values supplied in the
+ ARGS array.
+ }
+ \sstsubsection{
+ ARGS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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
+ if no arguments are needed.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting
+ SpecMap. The simplification process will eliminate any steps
+ which turn out not to be needed.
+
+ \sstitem
+ This routine 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 CVT argument 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 ARGS 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{
+ AST\_SPECFLUXFRAME
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_SPECFLUXFRAME( FRAME1, FRAME2, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FRAME1 = INTEGER (Given)
+ }{
+ Pointer to the SpecFrame. This will form the first axis in the
+ new SpecFluxFrame.
+ }
+ \sstsubsection{
+ FRAME2 = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SPECFLUXFRAME = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_SPECFRAME
+}{
+ 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
+ }
+ \sstinvocation{
+ RESULT = AST\_SPECFRAME( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SPECFRAME = INTEGER
+ }{
+ A pointer to the new SpecFrame.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ FRAME = AST\_SPECFRAME( \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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 = AST\_SPECFRAME( \texttt{'} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{'} , STATUS )
+ }{
+ 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 \htmlref{AST\_CONVERT}{AST\_CONVERT}),
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SPECMAP
+}{
+ 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{AST\_SPECADD}{AST\_SPECADD} routine,
+ 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 AST\_SPECADD routine.
+
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_SPECMAP( NIN, FLAGS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NIN = INTEGER (Given)
+ }{
+ 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{"}
+ routine.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This argument is reserved for future use and should currently
+ always be set to zero.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SPECMAP = INTEGER
+ }{
+ 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
+ AST\_SPECADD routine 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_SPHMAP
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_SPHMAP( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SPHMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_STCCATALOGENTRYLOCATION
+}{
+ 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
+ }
+ \sstinvocation{
+ RESULT = AST\_STCCATALOGENTRYLOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the encapsulated \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ NCOORDS = INTEGER (Given)
+ }{
+ The length of the COORDS array. Supply zero if COORDS should be
+ ignored.
+ }
+ \sstsubsection{
+ COORDS( NCOORDS ) = INTEGER (Given)
+ }{
+ An array holding NCOORDS AstKeyMap pointers (if NCOORDS
+ 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
+ REGION.
+ 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 REGION.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STCCATALOGENTRYLOCATION = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_STCOBSDATALOCATION
+}{
+ 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
+ }
+ \sstinvocation{
+ RESULT = AST\_STCOBSDATALOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the encapsulated \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ NCOORDS = INTEGER (Given)
+ }{
+ The length of the COORDS array. Supply zero if COORDS should be
+ ignored.
+ }
+ \sstsubsection{
+ COORDS( NCOORDS ) = INTEGER (Given)
+ }{
+ An array holding NCOORDS AstKeyMap pointers (if NCOORDS
+ 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
+ REGION.
+ 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 REGION.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STCOBSDATALOCATION = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_STCRESOURCEPROFILE
+}{
+ 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
+ }
+ \sstinvocation{
+ RESULT = AST\_STCRESOURCEPROFILE( REGION, NCOORDS, COORDS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the encapsulated \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ NCOORDS = INTEGER (Given)
+ }{
+ The length of the COORDS array. Supply zero if COORDS should be
+ ignored.
+ }
+ \sstsubsection{
+ COORDS( NCOORDS ) = INTEGER (Given)
+ }{
+ An array holding NCOORDS AstKeyMap pointers (if NCOORDS
+ 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
+ REGION.
+ 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 REGION.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STCRESOURCEPROFILE = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_STCSCHAN
+}{
+ 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{AST\_WRITE}{AST\_WRITE}) 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{"} routines which connect it to an external data store
+ by reading and writing the resulting text. These routines
+ should perform any conversions needed between external character
+ encodings and the internal ASCII encoding. If no such routines
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_STCSCHAN( SOURCE, SINK, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SOURCE = SUBROUTINE (Given)
+ }{
+ A source routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SourceFile attribute, this routine will be used by
+ the StcsChan to obtain lines of input text. On each
+ invocation, it should read the next input line from some
+ external data store, and then return the resulting text to
+ the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a
+ negative line length when there are no more lines to read.
+ If an error occurs, it should set its own error status
+ argument to an error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SOURCE value,
+ and no value has been set for the SourceFile attribute,
+ the StcsChan will read from standard input instead.
+ }
+ \sstsubsection{
+ SINK = SUBROUTINE (Given)
+ }{
+ A sink routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SinkFile attribute, this routine will be used by
+ the StcsChan to deliver lines of output text. On each
+ invocation, it should obtain the next output line from the
+ AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the
+ resulting text to some external data store. If an error
+ occurs, it should set its own error status argument to an
+ error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SINK value,
+ and no value has been set for the SinkFile attribute,
+ the StcsChan will write to standard output instead.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STCSCHAN = INTEGER
+ }{
+ A pointer to the new StcsChan.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The names of the routines supplied for the SOURCE and SINK
+ arguments should appear in EXTERNAL statements in the Fortran
+ routine which invokes AST\_STCSCHAN. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \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.
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null Object
+ pointer.
+ }
+ }
+}
+\sstroutine{
+ AST\_STCSEARCHLOCATION
+}{
+ 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
+ }
+ \sstinvocation{
+ RESULT = AST\_STCSEARCHLOCATION( REGION, NCOORDS, COORDS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ REGION = INTEGER (Given)
+ }{
+ Pointer to the encapsulated \htmlref{Region}{Region}.
+ }
+ \sstsubsection{
+ NCOORDS = INTEGER (Given)
+ }{
+ The length of the COORDS array. Supply zero if COORDS should be
+ ignored.
+ }
+ \sstsubsection{
+ COORDS( NCOORDS ) = INTEGER (Given)
+ }{
+ An array holding NCOORDS AstKeyMap pointers (if NCOORDS
+ 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
+ REGION.
+ 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 REGION.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STCSEARCHLOCATION = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_STRIPESCAPES
+}{
+ 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{AST\_ESCAPES}{AST\_ESCAPES} routine,
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_STRIPESCAPES( TEXT )
+ }
+ \sstarguments{
+ \sstsubsection{
+ TEXT
+ }{
+ The string to be checked.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_STRIPESCAPES = CHARACTER
+ }{
+ The modified string. If the AST\_ESCAPES routine
+ has been called indicating that escape sequences should not be
+ stripped, then the supplied string is returned without change.
+ }
+ }
+}
+\sstroutine{
+ AST\_SWITCHMAP
+}{
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+ }
+ \sstinvocation{
+ RESULT = AST\_SWITCHMAP( FSMAP, ISMAP, NROUTE, ROUTEMAPS, OPTIONS,
+ STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FSMAP = INTEGER (Given)
+ }{
+ 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.
+ AST\_\_NULL
+ may be supplied, in which case the SwitchMap will have an undefined
+ forward Mapping.
+ }
+ \sstsubsection{
+ ISMAP = INTEGER (Given)
+ }{
+ 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.
+ AST\_\_NULL
+ may be supplied, in which case the SwitchMap will have an undefined
+ inverse Mapping.
+ }
+ \sstsubsection{
+ NROUTE = INTEGER (Given)
+ }{
+ The number of supplied route Mappings.
+ }
+ \sstsubsection{
+ ROUTEMAPS( NROUTE ) = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_SWITCHMAP = INTEGER
+ }{
+ A pointer to the new SwitchMap.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Note that the component Mappings supplied are not copied by
+ AST\_SWITCHMAP (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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_TABLE
+}{
+ 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
+ AST\_MAPGET... and AST\_MAPPUT...
+ 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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}
+ 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{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_TABLE( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TABLE = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_TABLESOURCE
+}{
+ Register a source routine for accessing tables in FITS files
+}{
+ \sstdescription{
+ This routine can be used to register a call-back routine
+ with a \htmlref{FitsChan}{FitsChan}. The registered
+ routine
+ is called when-ever the FitsChan needs to read information from a
+ binary table contained within a FITS file. This occurs if the
+ \htmlref{AST\_READ}{AST\_READ}
+ 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{AST\_PUTTABLES}{AST\_PUTTABLES} or \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}) prior to invoking AST\_READ
+ or by registering a call-back
+ routine using AST\_TABLESOURCE.
+ 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
+ routine
+ to supply the table at the point where it is needed (i.e. within
+ the AST\_READ method).
+ }
+ \sstinvocation{
+ CALL AST\_TABLESOURCE( THIS, TABSOURCE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ TABSOURCE = SUBROUTINE (Given)
+ }{
+ The table source routine 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
+ the usual inherited 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
+ AST\_PUTTABLES or AST\_PUTTABLE
+ 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 (otherwise zero
+ should be returned).
+
+ If TABSOURCE is AST\_NULL,
+ any registered call-back function will be removed.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The name of the routine supplied for the TABSOURCE
+ argument should appear in an EXTERNAL statement in the Fortran
+ routine which invokes AST\_TABLESOURCE. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null \htmlref{Object}{Object}
+ pointer.
+ }
+ }
+}
+\sstroutine{
+ AST\_TEST
+}{
+ Test if an Object attribute value is set
+}{
+ \sstdescription{
+ This function returns a logical result to indicate
+ whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s
+ attributes.
+ }
+ \sstinvocation{
+ RESULT = AST\_TEST( THIS, ATTRIB, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Object.
+ }
+ \sstsubsection{
+ ATTRIB = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the name of the attribute to be
+ tested.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Object
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TEST = LOGICAL
+ }{
+ .TRUE. if a value has previously been explicitly set for the
+ attribute (and hasn\texttt{'} t been cleared), otherwise .FALSE..
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ Attribute names are not case sensitive and may be surrounded
+ by white space.
+
+ \sstitem
+ A value of .FALSE. will be returned if this function is invoked
+ with STATUS set to an error value, or if it should fail for any reason.
+
+ \sstitem
+ A value of .FALSE. will also be returned if this function is used
+ to test a read-only attribute, although no error will result.
+ }
+ }
+}
+\sstroutine{
+ AST\_TESTCELL
+}{
+ Tests if a single HEALPix cell is included in a Moc
+}{
+ \sstdescription{
+ This function returns
+ .TRUE.
+ if the \htmlref{Moc}{Moc} includes the specified cell.
+ }
+ \sstinvocation{
+ RESULT = AST\_TESTCELL( THIS, ORDER, NPIX, PARENT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Moc to be modified.
+ }
+ \sstsubsection{
+ ORDER = INTEGER (Given)
+ }{
+ The HEALPix order of the cell to test.
+ .FALSE.
+ is returned if this is higher than the maximum order allowed in
+ the Moc (as given by its \htmlref{MaxOrder}{MaxOrder} attribute).
+ }
+ \sstsubsection{
+ NPIX = INTEGER$*$8 (Given)
+ }{
+ The \texttt{"} npix\texttt{"} value identifying the cell to test (see the MOC
+ recommendation for more details).
+ }
+ \sstsubsection{
+ PARENT = LOGICAL (Given)
+ }{
+ Indicates the value to return if the tested cell is not included
+ at the specified order, but a parent cell (at a lower order) is
+ included.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TESTCELL = LOGICAL
+ }{
+ .TRUE. if the specified cell is included in the Moc at the
+ specified order, of (if PARENT is non-zero) a parent cell is
+ included in the Moc. .FALSE. otherwise.
+ }
+ }
+}
+\sstroutine{
+ AST\_TESTFITS
+}{
+ 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
+ .TRUE.
+ value is returned. If the keyword is not found, or if it does not
+ have an associated value, a
+ .FALSE.
+ value is returned.
+ }
+ \sstinvocation{
+ RESULT = AST\_TESTFITS( THIS, NAME, THERE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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
+ a single dot \texttt{'} .\texttt{'}
+ is supplied, the current card is tested.
+ }
+ \sstsubsection{
+ THERE = LOGICAL (Returned)
+ }{
+ A value of .TRUE. will be returned if the keyword was found in the
+ header, and .FALSE. 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TESTFITS = LOGICAL
+ }{
+ A value of zero
+ .FALSE.
+ is returned if the keyword was not found in the FitsChan or has
+ no associated value. Otherwise, a value of
+ .TRUE.
+ 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
+ .FALSE.
+ is returned as the function value if an error has already occurred,
+ or if this function should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_TEXT
+}{
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_TEXT( THIS, TEXT, POS, UP, JUST, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Plot.
+ }
+ \sstsubsection{
+ TEXT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character string containing the
+ text to be drawn. Trailing white space is ignored.
+ }
+ \sstsubsection{
+ POS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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( $*$ ) = REAL (Given)
+ }{
+ 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.0,1.0] 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 POS.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_CLIP}{AST\_CLIP}), 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{
+ AST\_TIMEADD
+}{
+ Add a time coordinate conversion to a TimeMap
+}{
+ \sstdescription{
+ This routine 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{AST\_TIMEMAP}{AST\_TIMEMAP}), it simply
+ performs a unit (null) \htmlref{Mapping}{Mapping}. By using AST\_TIMEADD (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
+ AST\_TIMEADD 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.
+ }
+ \sstinvocation{
+ CALL AST\_TIMEADD( THIS, CVT, NARG, ARGS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the TimeMap.
+ }
+ \sstsubsection{
+ CVT = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{
+ NARG = INTEGER (Given)
+ }{
+ The number of argument values supplied in the
+ ARGS array.
+ }
+ \sstsubsection{
+ ARGS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ 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
+ if no arguments are needed.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_SIMPLIFY}{AST\_SIMPLIFY} to simplify the resulting
+ TimeMap. The simplification process will eliminate any steps
+ which turn out not to be needed.
+
+ \sstitem
+ This routine 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 CVT argument 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 ARGS 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,DTAI): Convert a TAI MJD to a UTC MJD.
+
+ \sstitem
+ \texttt{"} UTCTOTAI\texttt{"} (MJDOFF,DTAI): 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,DTAI): Convert a TT MJD to a TDB MJD.
+
+ \sstitem
+ \texttt{"} TDBTOTT\texttt{"} (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): 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
+ AST\_TRANSFORM routine.
+ The axis values supplied and returned by
+ AST\_TRANSFORM
+ 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
+ DTAI: The value of TAI-UTC (the value returned by astDat is used if
+ DTAI is AST\_\_BAD).
+
+ \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{
+ AST\_TIMEFRAME
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_TIMEFRAME( OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TIMEFRAME = INTEGER
+ }{
+ A pointer to the new TimeFrame.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ When conversion between two TimeFrames is requested (as when
+ supplying TimeFrames \htmlref{AST\_CONVERT}{AST\_CONVERT}),
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_TIMEMAP
+}{
+ 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{AST\_TIMEADD}{AST\_TIMEADD}
+ routine, 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 AST\_TIMEADD routine.
+ }
+ \sstinvocation{
+ RESULT = AST\_TIMEMAP( FLAGS, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This argument is reserved for future use and should currently
+ always be set to zero.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine. If no initialisation is required, a blank
+ value may be supplied.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TIMEMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_TRAN1
+}{
+ Transform 1-dimensional coordinates
+}{
+ \sstdescription{
+ This routine applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+ a set of points in one dimension.
+ }
+ \sstinvocation{
+ CALL AST\_TRAN1( THIS, NPOINT, XIN, FORWARD, XOUT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be applied.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Given)
+ }{
+ The number of points to be transformed.
+ }
+ \sstsubsection{
+ XIN( NPOINT ) = DOUBLE PRECISION (Given)
+ }{
+ An array of coordinate values for the input
+ (untransformed) points.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ A .TRUE. value indicates that the Mapping\texttt{'} s forward
+ coordinate transformation is to be applied, while a .FALSE.
+ value indicates that the inverse transformation should be
+ used.
+ }
+ \sstsubsection{
+ XOUT( NPOINT ) = DOUBLE PRECISION (Returned)
+ }{
+ An array into which the
+ coordinates of the output (transformed) points will be written.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin}
+ and \htmlref{Nout}{Nout} attributes.
+ }
+ }
+}
+\sstroutine{
+ AST\_TRAN2
+}{
+ Transform 2-dimensional coordinates
+}{
+ \sstdescription{
+ This routine applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+ a set of points in two dimensions.
+ }
+ \sstinvocation{
+ CALL AST\_TRAN2( THIS, NPOINT, XIN, YIN, FORWARD, XOUT, YOUT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be applied.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Given)
+ }{
+ The number of points to be transformed.
+ }
+ \sstsubsection{
+ XIN( NPOINT ) = DOUBLE PRECISION (Given)
+ }{
+ An array of X-coordinate values for the input
+ (untransformed) points.
+ }
+ \sstsubsection{
+ YIN( NPOINT ) = DOUBLE PRECISION (Given)
+ }{
+ An array of Y-coordinate values for the input
+ (untransformed) points.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ A .TRUE. value indicates that the Mapping\texttt{'} s forward
+ coordinate transformation is to be applied, while a .FALSE.
+ value indicates that the inverse transformation should be
+ used.
+ }
+ \sstsubsection{
+ XOUT( NPOINT ) = DOUBLE PRECISION (Returned)
+ }{
+ An array into which the
+ X-coordinates of the output (transformed) points will be written.
+ }
+ \sstsubsection{
+ YOUT( NPOINT ) = DOUBLE PRECISION (Returned)
+ }{
+ An array into which the
+ Y-coordinates of the output (transformed) points will be written.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin}
+ and \htmlref{Nout}{Nout} attributes.
+ }
+ }
+}
+\sstroutine{
+ AST\_TRANGRID
+}{
+ 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).
+ }
+ \sstinvocation{
+ CALL AST\_TRANGRID( THIS, NCOORD\_IN, LBND, UBND, TOL, MAXPIX,
+ FORWARD, NCOORD\_OUT, OUTDIM, OUT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be applied.
+ }
+ \sstsubsection{
+ NCOORD\_IN = INTEGER (Given)
+ }{
+ 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( NCOORD\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND( NCOORD\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND and UBND 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. 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ 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 MAXPIX
+ 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 TOL to zero). Although this may degrade
+ performance, accurate results will still be obtained.
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ A .TRUE. value indicates that the Mapping\texttt{'} s forward
+ coordinate transformation is to be applied, while a .FALSE.
+ value indicates that the inverse transformation should be
+ used.
+ }
+ \sstsubsection{
+ NCOORD\_OUT = INTEGER (Given)
+ }{
+ 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 NCOORD\_IN.
+ }
+ \sstsubsection{
+ OUTDIM = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the OUT
+ array (which will contain the output coordinates). The value
+ given should not be less than the number of points in the grid.
+ }
+ \sstsubsection{
+ OUT( OUTDIM, NCOORD\_OUT ) = DOUBLE PRECISION (Returned)
+ }{
+ An array into which the coordinates of the output
+ (transformed) points will be written. These will be stored
+ such that the value of coordinate number COORD for output
+ point number POINT will be found in element OUT(POINT,COORD).
+ 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).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If the forward coordinate transformation is being applied, the
+ Mapping supplied must have the value of NCOORD\_IN for its \htmlref{Nin}{Nin}
+ attribute and the value of NCOORD\_OUT for its \htmlref{Nout}{Nout} attribute. If
+ the inverse transformation is being applied, these values should
+ be reversed.
+ }
+ }
+}
+\sstroutine{
+ AST\_TRANMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_TRANMAP( MAP1, MAP2, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ MAP1 = INTEGER (Given)
+ }{
+ Pointer to the first component Mapping, which defines the
+ forward transformation.
+ }
+ \sstsubsection{
+ MAP2 = INTEGER (Given)
+ }{
+ Pointer to the second component Mapping, which defines the
+ inverse transformation.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TRANMAP = INTEGER
+ }{
+ 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
+ AST\_TRANMAP (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{AST\_COPY}{AST\_COPY}.
+
+ \sstitem
+ A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+ function is invoked with STATUS set to an error value, 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{
+ AST\_TRANN
+}{
+ Transform N-dimensional coordinates
+}{
+ \sstdescription{
+ This routine 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).
+ }
+ \sstinvocation{
+ CALL AST\_TRANN( THIS, NPOINT,
+ NCOORD\_IN, INDIM, IN,
+ FORWARD, NCOORD\_OUT, OUTDIM, OUT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Mapping to be applied.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Given)
+ }{
+ The number of points to be transformed.
+ }
+ \sstsubsection{
+ NCOORD\_IN = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the IN
+ 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 NPOINT.
+ }
+ \sstsubsection{
+ IN( INDIM, NCOORD\_IN ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the coordinates of the input
+ (untransformed) points. These should be stored such that the
+ value of coordinate number COORD for input point number POINT
+ is found in element IN(POINT,COORD).
+ }
+ \sstsubsection{
+ FORWARD = LOGICAL (Given)
+ }{
+ A .TRUE. value indicates that the Mapping\texttt{'} s forward
+ coordinate transformation is to be applied, while a .FALSE.
+ value indicates that the inverse transformation should be
+ used.
+ }
+ \sstsubsection{
+ NCOORD\_OUT = INTEGER (Given)
+ }{
+ 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 NCOORD\_IN.
+ }
+ \sstsubsection{
+ OUTDIM = INTEGER (Given)
+ }{
+ The number of elements along the first dimension of the OUT
+ 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 NPOINT.
+ }
+ \sstsubsection{
+ OUT( OUTDIM, NCOORD\_OUT ) = DOUBLE PRECISION (Returned)
+ }{
+ An array into which the coordinates of the output
+ (transformed) points will be written. These will be stored
+ such that the value of coordinate number COORD for output
+ point number POINT will be found in element OUT(POINT,COORD).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ If the forward coordinate transformation is being applied, the
+ Mapping supplied must have the value of NCOORD\_IN for its \htmlref{Nin}{Nin}
+ attribute and the value of NCOORD\_OUT for its \htmlref{Nout}{Nout} attribute. If
+ the inverse transformation is being applied, these values should
+ be reversed.
+ }
+ }
+}
+\sstroutine{
+ AST\_TUNE
+}{
+ 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{AST\_TUNEC}{AST\_TUNEC}.
+ }
+ \sstinvocation{
+ RESULT = AST\_TUNE( NAME, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The name of the tuning parameter (case-insensitive).
+ }
+ \sstsubsection{
+ VALUE = INTEGER (Given)
+ }{
+ The new value for the tuning parameter. If this is AST\_\_TUNULL,
+ the existing current value will be retained.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_TUNE = INTEGER
+ }{
+ be returned if no value has been set for the parameter.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an
+ error value
+ 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{AST\_DELETE}{AST\_DELETE}).
+ 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{
+ AST\_TUNEC
+}{
+ 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{AST\_TUNE}{AST\_TUNE}.
+ }
+ \sstinvocation{
+ CALL AST\_TUNEC( NAME, VALUE, BUFF, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NAME = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ The name of the tuning parameter (case-insensitive).
+ }
+ \sstsubsection{
+ VALUE = CHARACTER $*$ ( ) (Given)
+ }{
+ The new value for the tuning parameter. If this is
+ AST\_\_TUNULLC,
+ the existing current value will be retained.
+ }
+ \sstsubsection{
+ BUFF = CHARACTER $*$ ( ) (Given)
+ }{
+ 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.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ This routine attempts to execute even if STATUS is set to an
+ error value
+ 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{
+ AST\_UINTERP
+}{
+ Perform sub-pixel interpolation on a grid of data
+}{
+ \sstdescription{
+ This is a fictitious routine which does not actually
+ exist. Instead, this description constitutes a template so that
+ you may implement a routine with this interface for yourself
+ (and give it any name you wish). Such a routine
+ may be passed via the FINTERP argument of the \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}
+ functions (q.v.) in order to perform sub-pixel interpolation
+ during resampling of gridded data (you must also set the
+ INTERP argument of AST\_RESAMPLE$<$X$>$ to the value
+ AST\_\_UINTERP). This allows you to use your own interpolation
+ algorithm in addition to those which are pre-defined.
+
+ The routine interpolates an input grid of data (and,
+ optionally, processes associated statistical variance estimates)
+ at a specified set of points.
+ }
+ \sstinvocation{
+ CALL AST\_UINTERP( NDIM\_IN, LBND\_IN, UBND\_IN, IN, IN\_VAR,
+ NPOINT, OFFSET, COORDS, PARAMS, FLAGS, BADVAL,
+ OUT, OUT\_VAR, NBAD, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NDIM\_IN = INTEGER (Given)
+ }{
+ The number of dimensions in the input grid. This will be at
+ least one.
+ }
+ \sstsubsection{
+ LBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the first pixel
+ in the input grid along each dimension.
+ }
+ \sstsubsection{
+ UBND\_IN( NDIM\_IN ) = INTEGER (Given)
+ }{
+ An array
+ containing the coordinates of the centre of the last pixel in
+ the input grid along each dimension.
+
+ Note that LBND\_IN and UBND\_IN together define the shape,
+ size and coordinate system of the input grid in the same
+ way as they do in AST\_RESAMPLE$<$X$>$.
+ }
+ \sstsubsection{
+ IN( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ 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 AST\_RESAMPLE$<$X$>$ via the IN argument.
+ The numerical type of this array should match that of the
+ data being processed.
+ }
+ \sstsubsection{
+ IN\_VAR( $*$ ) = $<$Xtype$>$ (Given)
+ }{
+ An optional second array with the same size and type as the
+ IN array. This will only be given if the AST\_\_USEVAR flag is
+ set via the FLAGS argument (below). If given, it will contain
+ the set of variance values associated with the input data and
+ will be the same array as was passed to AST\_RESAMPLE$<$X$>$ via
+ the IN\_VAR argument.
+
+ If the AST\_\_USEVAR flag is not set, then no variance values
+ are being processed. In this case, this array of variance
+ values may be a dummy (e.g. one-element) array and should not
+ be used.
+ }
+ \sstsubsection{
+ NPOINT = INTEGER (Given)
+ }{
+ The number of points at which the input grid is to be
+ interpolated. This will be at least one.
+ }
+ \sstsubsection{
+ OFFSET( NPOINT ) = INTEGER (Given)
+ }{
+ For each interpolation point, this array will contain the
+ offset from the start of the OUT (and OUT\_VAR) array(s) at
+ which the interpolated value (and its variance, if required)
+ should be stored. For example, the interpolated value for
+ point number POINT should be stored in OUT(1$+$OFFSET(POINT)).
+ }
+ \sstsubsection{
+ COORDS( NPOINT, NDIM\_IN ) = DOUBLE PRECISION (Given)
+ }{
+ A 2-dimensional array containing the coordinates of the
+ points at which interpolation should be performed. These will
+ be stored so that coordinate number COORD for interpolation
+ point number POINT is found in element COORDS(POINT,COORD).
+
+ If any interpolation point has any of its coordinates equal
+ to the value AST\_\_BAD (as defined in the AST\_PAR include
+ file), then the corresponding output data (and variance)
+ should either be set to the value given by BADVAL,
+ or left unchanged, depending on whether the AST\_\_NOBAD flag is
+ specified by FLAGS.
+ }
+ \sstsubsection{
+ PARAMS( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ This will be the same array as was given via the
+ PARAMS argument of AST\_RESAMPLE$<$X$>$. You may use this to
+ pass any additional parameter values required by your
+ interpolation algorithm.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This will be the same value as was given via the FLAGS
+ argument of AST\_RESAMPLE$<$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 AST\_RESAMPLE$<$X$>$).
+ }
+ \sstsubsection{
+ BADVAL = $<$Xtype$>$ (Given)
+ }{
+ This will be the same value as was given for the BADVAL
+ argument of AST\_RESAMPLE$<$X$>$, and will have the same numerical
+ type as the data being processed (i.e. as elements of the IN
+ 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
+ FLAGS argument) and (unless the AST\_\_NOBAD flag is set in
+ FLAGS) for identifying bad output values in the OUT (and
+ OUT\_VAR) array(s).
+ }
+ \sstsubsection{
+ OUT( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ An array with the same numerical type as the IN
+ 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
+ OFFSET array contains all necessary information about where
+ each returned value should be stored.
+
+ In general, not all elements of this array (or the OUT\_VAR
+ array below) may be used in any particular invocation of the
+ routine. Those which are not used should be returned
+ unchanged.
+ }
+ \sstsubsection{
+ OUT\_VAR( $*$ ) = $<$Xtype$>$ (Returned)
+ }{
+ An optional array with the same type and size as the OUT
+ array, into which variance estimates for the resampled values
+ should be returned. This array will only be given if the
+ AST\_\_USEVAR flag is set via the FLAGS argument.
+
+ If given, it is addressed in exactly the same way (via the
+ OFFSET array) as the OUT array. The values returned should be
+ estimates of the statistical variance of the corresponding
+ values in the OUT 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 the AST\_\_USEVAR flag is not set, then variance values are
+ not being processed. In this case, this array may be a dummy
+ (e.g. one-element) array and should not be used.
+ }
+ \sstsubsection{
+ NBAD = INTEGER (Returned)
+ }{
+ This should return the number of interpolation points at
+ which no valid interpolated value could be obtained. The maximum
+ value that should be returned is NPOINT, and the minimum is
+ zero (indicating that all output values were successfully
+ obtained).
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The data type $<$Xtype$>$ indicates the numerical type of the data
+ being processed, as for AST\_RESAMPLE$<$X$>$.
+
+ \sstitem
+ This routine will typically be invoked more than once for each
+ invocation of AST\_RESAMPLE$<$X$>$.
+
+ \sstitem
+ If an error occurs within this routine, it should set the
+ STATUS argument to an error value before returning. This will
+ cause an immediate return from AST\_RESAMPLE$<$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).
+ The AST\_\_UINER error value is defined in the AST\_ERR include file.
+ }
+ }
+}
+\sstroutine{
+ AST\_UKERN1
+}{
+ 1-dimensional sub-pixel interpolation kernel
+}{
+ \sstdescription{
+ This is a fictitious routine which does not actually
+ exist. Instead, this description constitutes a template so that
+ you may implement a routine with this interface for yourself
+ (and give it any name you wish). Such a routine
+ may be passed via the FINTERP argument of the \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$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 INTERP argument of AST\_RESAMPLE$<$X$>$ to the value
+ AST\_\_UKERN1). This allows you to use your own interpolation
+ kernel in addition to those which are pre-defined.
+
+ The routine 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.
+ }
+ \sstinvocation{
+ CALL AST\_UKERN1( OFFSET, PARAMS, FLAGS, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ OFFSET = DOUBLE PRECISION (Given)
+ }{
+ 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( $*$ ) = DOUBLE PRECISION (Given)
+ }{
+ This will be the same array as was given via the
+ PARAMS argument of AST\_RESAMPLE$<$X$>$. You may use this to
+ pass any additional parameter values required by your kernel,
+ but note that PARAMS(1) will already have been used to specify
+ the number of neighbouring pixels which contribute to the
+ interpolated value.
+ }
+ \sstsubsection{
+ FLAGS = INTEGER (Given)
+ }{
+ This will be the same value as was given via the FLAGS
+ argument of AST\_RESAMPLE$<$X$>$. You may test this value to
+ provide additional control over the operation of your
+ routine. 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 AST\_RESAMPLE$<$X$>$).
+ }
+ \sstsubsection{
+ VALUE = DOUBLE PRECISION (Returned)
+ }{
+ The calculated kernel value,
+ which may be positive or negative.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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 routine, it should set the
+ STATUS argument to an error value before returning. This will
+ cause an immediate return from AST\_RESAMPLE$<$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).
+ The AST\_\_UK1ER error value is defined in the AST\_ERR include file.
+ }
+ }
+}
+\sstroutine{
+ AST\_UNFORMAT
+}{
+ 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 precision) 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{AST\_FORMAT}{AST\_FORMAT}.
+ }
+ \sstinvocation{
+ RESULT = AST\_UNFORMAT( THIS, AXIS, STRING, VALUE, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Frame.
+ }
+ \sstsubsection{
+ AXIS = INTEGER (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A 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 = DOUBLE PRECISION (Returned)
+ }{
+ The coordinate value read.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_UNFORMAT = INTEGER
+ }{
+ 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 VALUE argument 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 AST\_FORMAT are correctly interpreted by AST\_UNFORMAT.
+
+ \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
+ AST\_FORMAT 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
+ AST\_FORMAT would produce.
+
+ }
+ This final convention is intended to ensure that values formatted
+ by AST\_FORMAT which contain less than three fields will be
+ correctly interpreted if read back using AST\_UNFORMAT, 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{
+ AST\_UNITMAP
+}{
+ 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
+ routine) but you do not want it to have any effect.
+ }
+ \sstinvocation{
+ RESULT = AST\_UNITMAP( NCOORD, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ The number of input and output coordinates (these numbers are
+ necessarily the same).
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_UNITMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, or if it
+ should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_UNITNORMMAP
+}{
+ 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.
+ If the norm is 0, then the output of the forward transformation is AST\_\_BAD
+ for each component of the unit vector and 0 for the norm (the final value).
+
+ 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.
+ If the provided norm is 0 then the other input values are ignored,
+ and the output vector is the centre.
+
+ Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre;
+ the norm is 5, so the output is [0.8, 0.6, 5].
+
+ 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
+ }
+ }
+ \sstinvocation{
+ RESULT = AST\_UNITNORMMAP( NCOORD, CENTRE, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_UNITNORMMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_VERSION
+}{
+ Return the version of the AST library being used
+}{
+ \sstdescription{
+ This function
+ 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)
+ }
+ \sstinvocation{
+ RESULT = AST\_VERSION()
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{Object}{Object}
+ }{
+ This routine applies to all Objects.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_VERSION = INTEGER
+ }{
+ The major version, minor version and release numbers for the AST
+ library, encoded as a single integer.
+ }
+ }
+}
+\sstroutine{
+ AST\_WARNINGS
+}{
+ 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{AST\_READ}{AST\_READ} or \htmlref{AST\_WRITE}{AST\_WRITE}
+ function on the \htmlref{Channel}{Channel}. If no warnings were issued, a
+ AST\_\_NULL
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_WARNINGS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Channel.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{
+ AST\_WARNINGS = INTEGER
+ }{
+ A pointer to the KeyMap holding the warning messages, or
+ AST\_\_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
+ AST\_\_NULL will be returned if this function is invoked with STATUS
+ set to an error value,
+ or if it should fail for any reason.
+ }
+ }
+}
+\sstroutine{
+ AST\_WCSMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_WCSMAP( NCOORD, TYPE, LONAX, LATAX, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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 = INTEGER (Given)
+ }{
+ The type of FITS-WCS projection to apply. This should be
+ given as a symbolic 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 = INTEGER (Given)
+ }{
+ The index of the longitude axis. This should lie in the range
+ 1 to NCOORD.
+ }
+ \sstsubsection{
+ LATAX = INTEGER (Given)
+ }{
+ The index of the latitude axis. This should lie in the range
+ 1 to NCOORD and be distinct from LONAX.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+
+ 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{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_WCSMAP = INTEGER
+ }{
+ A pointer to the new WcsMap.
+ }
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ WCSMAP = AST\_WCSMAP( 2, AST\_\_MER, 1, 2, \texttt{'} \texttt{'} , STATUS )
+ }{
+ 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 = AST\_WCSMAP( 3, AST\_\_COE, 2, 3, \texttt{'} PV3\_1=40.0\texttt{'} , STATUS )
+ }{
+ 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{AST\_INVERT}{AST\_INVERT} 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 OPTIONS 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 STATUS set to an error value, 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{
+ AST\_WINMAP
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_WINMAP( NCOORD, INA, INB, OUTA, OUTB, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the
+ coordinates of corner A of the window in the input coordinate
+ system.
+ }
+ \sstsubsection{
+ INB( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the
+ coordinates of corner B of the window in the input coordinate
+ system.
+ }
+ \sstsubsection{
+ OUTA( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the
+ coordinates of corner A of the window in the output coordinate
+ system.
+ }
+ \sstsubsection{
+ OUTB( NCOORD ) = DOUBLE PRECISION (Given)
+ }{
+ An array containing the
+ coordinates of corner B of the window in the output coordinate
+ system.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_WINMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{
+ AST\_WRITE
+}{
+ 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_WRITE( THIS, OBJECT, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the Channel.
+ }
+ \sstsubsection{
+ OBJECT = INTEGER (Given)
+ }{
+ Pointer to the Object which is to be written.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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
+ AST\_WRITE
+ can help to produce a successful write.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_WRITE = INTEGER
+ }{
+ The number of Objects written to the Channel by this
+ invocation of AST\_WRITE (normally, this will be one).
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ A value of zero will be returned if this function is invoked
+ with STATUS set to an error value, 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{
+ AST\_WRITEFITS
+}{
+ Write out all cards in a FitsChan to the sink function
+}{
+ \sstdescription{
+ This routine
+ 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.
+ }
+ \sstinvocation{
+ CALL AST\_WRITEFITS( THIS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ THIS = INTEGER (Given)
+ }{
+ Pointer to the FitsChan.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \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{AST\_EMPTYFITS}{AST\_EMPTYFITS}.
+
+ \sstitem
+ This method attempt to execute even if an error has occurred
+ previously.
+ }
+ }
+}
+\sstroutine{
+ AST\_XMLCHAN
+}{
+ 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{AST\_WRITE}{AST\_WRITE}) 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{"} routines 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.
+ }
+ \sstinvocation{
+ RESULT = AST\_XMLCHAN( SOURCE, SINK, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ SOURCE = SUBROUTINE (Given)
+ }{
+ A source routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SourceFile attribute, this routine will be used by
+ the XmlChan to obtain lines of input text. On each
+ invocation, it should read the next input line from some
+ external data store, and then return the resulting text to
+ the AST library by calling \htmlref{AST\_PUTLINE}{AST\_PUTLINE}. It should supply a
+ negative line length when there are no more lines to read.
+ If an error occurs, it should set its own error status
+ argument to an error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SOURCE value,
+ and no value has been set for the SourceFile attribute,
+ the XmlChan will read from standard input instead.
+ }
+ \sstsubsection{
+ SINK = SUBROUTINE (Given)
+ }{
+ A sink routine, which is a subroutine which takes a single
+ integer error status argument. If no value has been set
+ for the SinkFile attribute, this routine will be used by
+ the XmlChan to deliver lines of output text. On each
+ invocation, it should obtain the next output line from the
+ AST library by calling \htmlref{AST\_GETLINE}{AST\_GETLINE}, and then deliver the
+ resulting text to some external data store. If an error
+ occurs, it should set its own error status argument to an
+ error value before returning.
+
+ If the null routine AST\_NULL is suppied as the SINK value,
+ and no value has been set for the SinkFile attribute,
+ the XmlChan will write to standard output instead.
+ }
+ \sstsubsection{
+ OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_XMLCHAN = INTEGER
+ }{
+ A pointer to the new XmlChan.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The names of the routines supplied for the SOURCE and SINK
+ arguments should appear in EXTERNAL statements in the Fortran
+ routine which invokes AST\_XMLCHAN. However, this is not generally
+ necessary for the null routine AST\_NULL (so long as the AST\_PAR
+ include file has been used).
+
+ \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.
+
+ \sstitem
+ Note that the null routine AST\_NULL (one underscore) is
+ different to AST\_\_NULL (two underscores), which is the null Object
+ pointer.
+ }
+ }
+}
+\sstroutine{
+ AST\_ZOOMMAP
+}{
+ 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).
+ }
+ \sstinvocation{
+ RESULT = AST\_ZOOMMAP( NCOORD, ZOOM, OPTIONS, STATUS )
+ }
+ \sstarguments{
+ \sstsubsection{
+ NCOORD = INTEGER (Given)
+ }{
+ 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 = DOUBLE PRECISION (Given)
+ }{
+ 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 = CHARACTER $*$ ( $*$ ) (Given)
+ }{
+ A character 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{AST\_SET}{AST\_SET} routine.
+ }
+ \sstsubsection{
+ STATUS = INTEGER (Given and Returned)
+ }{
+ The global status.
+ }
+ }
+ \sstreturnedvalue{
+ \sstsubsection{
+ AST\_ZOOMMAP = INTEGER
+ }{
+ 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 STATUS set to an error value, 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{AST\_GRID}{AST\_GRID} routine) 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 the 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 need to 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}.
+ 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
+ AST\_FINDFRAME and AST\_CONVERT
+ 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 AST\_FINDFRAME or AST\_CONVERT
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) 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 AST\_FindFrame or AST\_CONVERT 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) 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 astFindFrame or astConvert 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}) 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 AST\_FindFrame or AST\_CONVERT 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 attribute 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{AST\_READ}{AST\_READ}, 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 AST\_READ, 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 AST\_READ, 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 AST\_READ, 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 AST\_READ, 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 AST\_READ, 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{AST\_FORMAT}{AST\_FORMAT}) 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{AST\_INVERT}{AST\_INVERT} routine 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{AST\_GRID}{AST\_GRID} routine) by determining
+ whether a border is drawn around regions corresponding to the
+ valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{AST\_BORDER}{AST\_BORDER}).
+
+ 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{AST\_GRID}{AST\_GRID} 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 routines that
+ access the contents of the FitsChan, such as \htmlref{AST\_DELFITS}{AST\_DELFITS},
+ \htmlref{AST\_FINDFITS}{AST\_FINDFITS} and \htmlref{AST\_PUTFITS}{AST\_PUTFITS}.
+
+ 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{AST\_CLEAR}{AST\_CLEAR}) 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{AST\_READ}{AST\_READ}.
+ 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{AST\_CLIP}{AST\_CLIP} routine
+ 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{AST\_CLIP}{AST\_CLIP} routine) 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
+ AST\_CLIP 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.
+ }
+ \sstsubsection{
+ \htmlref{Moc}{Moc}
+ }{
+ The Moc class ignored this attribute, and the behaviour for
+ boundary points is undefined (i.e. they may be inside or
+ outside the Region, depending on the position being tested and
+ the nature of the Moc).
+ }
+ }
+}
+\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}.
+ 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 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
+ INTEGER$*$2),
+ AST\_\_BYTETYPE (for
+ bytes),
+ 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{AST\_MAPPUTU}{AST\_MAPPUTU}).
+ }
+ \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{AST\_INVERT}{AST\_INVERT} routine 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{AST\_FORMAT}{AST\_FORMAT}). 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{AST\_INVERT}{AST\_INVERT}), 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{
+ Dtai
+}{
+ The TAI-UTC correction
+}{
+ \sstdescription{
+ This attribute specifies the difference between TAI and UTC (i.e.
+ the number of leap seconds) at the moment corresponding to the
+ \htmlref{Frame}{Frame}\texttt{'} s \htmlref{Epoch}{Epoch} value. The default value of AST\_\_BAD causes the
+ number of leap seconds to be determined from an internal look-up
+ table, which is kept up-to-date manually by the AST development team.
+ Therefore it is only necessary to assign a value to this attribute
+ if the version of AST in use is so old that it does not include all
+ leap seconds that occurred prior to the time represented by the
+ Frame\texttt{'} s Epoch value.
+ }
+ \sstattributetype{
+ Floating point.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Frame
+ }{
+ All Frames have this 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_WRITE}{AST\_WRITE} and \htmlref{AST\_READ}{AST\_READ} routines 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 AST\_READ), 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 AST\_WRITE is used to store a FrameSet using DSS encoding,
+ an attempt is first made to simplify the FrameSet to see if it
+ conforms to the DSS model. Specifically, the current Frame must
+ be a 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 AST\_WRITE 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 AST\_READ), the FitsChan
+ concerned must initially be positioned at the first card (its
+ Card attribute must equal 1) and the result of the read, if
+ successful, will always be a pointer to a FrameSet. The base
+ Frame of this FrameSet represents FITS-WCS pixel coordinates,
+ and the current Frame represents the physical coordinate system
+ described by the FITS-WCS primary axis descriptions. If
+ secondary axis descriptions are also present, then the FrameSet
+ may contain additional (non-current) Frames which represent
+ these. Such a read is always destructive and causes the FITS
+ header cards required for the construction of the FrameSet to be
+ removed from the FitsChan, which is then left positioned at the
+ \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 AST\_WRITE is used to store a FrameSet using FITS-WCS
+ encoding, an attempt is first made to simplify the FrameSet to
+ see if it conforms to the FITS-WCS model. If this simplification
+ process succeeds (as it often should, as the model is reasonably
+ flexible), a description of the FrameSet is written to the
+ FitsChan using appropriate FITS header cards. The base Frame of
+ the FrameSet is used to form the FITS-WCS pixel coordinate
+ system and the current Frame gives the physical coordinate
+ system to be described by the FITS-WCS primary axis
+ descriptions. Any additional Frames in the FrameSet may be used
+ to construct secondary axis descriptions, where appropriate.
+
+ A successful write operation will over-write any existing
+ FITS-WCS encoded data in the FitsChan, but will not affect other
+ (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS
+ encoded Object has previously occurred, then an attempt will be
+ made to store the FITS header cards back in their original
+ locations. Otherwise, the new cards will be inserted following
+ any other FITS-WCS related header cards present or, failing
+ that, in front of the current card (as given by the Card
+ attribute).
+
+ If an attempt to simplify a FrameSet to conform to the FITS-WCS
+ model fails (or if the Object supplied is not a FrameSet), then
+ no data will be written to the FitsChan and AST\_WRITE will
+ return zero. No error will result.
+ }
+ \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
+ AST\_READ), FITS header cards are read, starting at the current
+ card (as determined by the Card attribute), until the start of
+ the next Object description is found. This description is then
+ read and converted into an AST Object, for which a pointer is
+ returned. Such a read is always destructive and causes all the
+ FITS header cards involved in the Object description to be
+ removed from the FitsChan, which is left positioned at the
+ following card.
+
+ The Object returned may be of any class, depending on the
+ description that was read, and other AST routines may be used to
+ validate it (for example, by examining its \htmlref{Class}{Class} or \htmlref{ID}{ID} attribute
+ using AST\_GETC). If further NATIVE encoded Object descriptions
+ exist in the FitsChan, subsequent calls to AST\_READ will return
+ the Objects they describe in sequence (and destroy their
+ descriptions) until no more remain between the current card and
+ the \texttt{"} end-of-file\texttt{"} .
+
+ When AST\_WRITE is used to write an Object using NATIVE encoding,
+ a description of the Object is inserted immediately before the
+ current card (as determined by the Card attribute). Multiple
+ Object descriptions may be written in this way and are stored
+ separately (and sequentially if the Card attribute is not
+ modified between the writes). A write operation using the NATIVE
+ encoding does not over-write previously written Object
+ descriptions. Note, however, that subsequent behaviour is
+ undefined if an Object description is written inside a
+ previously-written description, so this should be avoided.
+
+ When an Object is written to a FitsChan using NATIVE encoding,
+ AST\_WRITE should (barring errors) always transfer data and
+ return a value of 1.
+ }
+}
+\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 change 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{AST\_GRID}{AST\_GRID} and (for the \htmlref{Plot}{Plot} class) \htmlref{AST\_TEXT}{AST\_TEXT} routines,
+ 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
+ AST\_GRID routine.
+
+ 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{AST\_ESCAPES}{AST\_ESCAPES} 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{AST\_WRITE}{AST\_WRITE}
+ 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 is double precision.
+ 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{AST\_FINDFITS}{AST\_FINDFITS} or by the action of the FitsChan\texttt{'} s sink routine
+ when it is finally deleted.
+ }
+ \sstattributetype{
+ Integer.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ FitsChan
+ }{
+ All FitsChans have this attribute.
+ }
+ }
+}
+\sstroutine{
+ FitsTol
+}{
+ Maximum non-linearity allowed when exporting to FITS-WCS
+}{
+ \sstdescription{
+ This attribute is used when attempting to write a \htmlref{FrameSet}{FrameSet} to a
+ \htmlref{FitsChan}{FitsChan} using a foreign encoding. It specifies the maximum
+ departure from linearity allowed on any axis within the mapping
+ from pixel coordinates to Intermediate World Coordinates. It is
+ expressed in units of pixels. If an axis of the \htmlref{Mapping}{Mapping} is found
+ to deviate from linearity by more than this amount, the write
+ operation fails. If the linearity test succeeds, a linear
+ approximation to the mapping is used to determine the FITS keyword
+ values to be placed in the FitsChan.
+
+ The default value is one tenth of a pixel.
+ }
+ \sstattributetype{
+ Floating point.
+ }
+ \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{AST\_FORMAT}{AST\_FORMAT} 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).
+ }
+ \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.
+
+ \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{AST\_GRID}{AST\_GRID} routine) 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 routines registered through AST\_GRFSET?
+}{
+ \sstdescription{
+ This attribute selects the routines which are used to draw graphics by
+ the \htmlref{Plot}{Plot} class. If it is zero, then the routines in the graphics
+ interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script).
+ Otherwise, routines registered using \htmlref{AST\_GRFSET}{AST\_GRFSET} are used. In this
+ case, if a routine is needed which has not been registered,
+ then the routine 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{AST\_READ}{AST\_READ}, 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_WRITE}{AST\_WRITE}) and
+ are later retrieved (using \htmlref{AST\_READ}{AST\_READ}). 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{AST\_SHOW}{AST\_SHOW} 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 AST\_WRITE routine.
+ }
+ }
+}
+\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{AST\_WRITE}{AST\_WRITE} 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.
+
+ Note, the default value of zero is unlikely to be appropriate when
+ an StcsChan is used within Fortran code. In this case, Indent
+ should usually be set non-zero, and the StcsLength attribute set to
+ the size of the CHARACTER variable used to
+ receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function.
+ This avoids the possibility of long lines being truncated invisibly
+ within AST\_GETLINE.
+ }
+ \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 routine
+ 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 routine. 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{AST\_SIMPLIFY}{AST\_SIMPLIFY})
+ 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{AST\_INVERT}{AST\_INVERT} routine.
+ }
+ \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{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}. 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
+ astLinearApprox function.
+ \htmlref{AST\_LINEARAPPROX}{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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ 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
+ AST\_SIMPLIFY
+ 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 original 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.
+
+ Note, the term \texttt{"} inverse transformation\texttt{"} here refers to the inverse
+ transformation of the original PolyMap, ignoring any subsequent
+ inversions. Also, \texttt{"} input\texttt{"} and \texttt{"} output\texttt{"} refer to the inputs and
+ outputs of the original PolyMap.
+
+ The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that
+ control the behaviour of the inverse approximation method.
+
+ The iterative inverse returns AST\_\_BAD axis values at positions
+ for which the inverse transformation is undefined. For instance,
+ if the forward transformation is y = x$*$x, the iterative inverse
+ will return x = AST\_\_BAD at y = -1. If the inverse transformation
+ is multiply defined, the position returned by the iterative inverse
+ will be the position of the solution that is closest to the
+ supplied position. For instance, using the above example, y = x$*$x,
+ the iterative inverse will return x = $+$2 at y = 4, because x = $+$2
+ is the closest solution to 4 (the other solution is x = -2).
+ }
+ \sstattributetype{
+ Integer (boolean).
+ }
+ \sstapplicability{
+ \sstsubsection{
+ PolyMap
+ }{
+ All PolyMaps have this attribute.
+ }
+ \sstsubsection{
+ \htmlref{ChebyMap}{ChebyMap}
+ }{
+ The ChebyMap class does not currently provide an option for an
+ iterative inverse, and so the IterInverse value is always zero.
+ Setting or clearing the IterInverse attribute of a ChebyMap has
+ no effect.
+ }
+ }
+ \sstnotes{
+ \sstitemlist{
+
+ \sstitem
+ The transformation replaced by the iterative algorithm is the
+ transformation from the original PolyMap output space to the
+ original PolyMap input space (i.e. the input and output spaces as
+ defined by the arguments of the PolyMap constructor). This is still
+ the case even if the PolyMap has subsequently been inverted. In
+ other words if a PolyMap is created and then inverted, setting
+ the IterInverse to a non-zero value will replace the forward
+ transformation of the inverted PolyMap (i.e. the inverse
+ transformation of the original PolyMap). It is not possible to
+ replace the other transformation (i.e. from the original PolyMap
+ input space to the original PolyMap output space) with an iterative
+ algorithm.
+
+ \sstitem
+ If a PolyMap that has an iterative inverse transformation is
+ subsequently inverted, the inverted PolyMap will have an iterative
+ forward transformation.
+
+ \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{AST\_READ}{AST\_READ}.
+ 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
+ AST\_MAPGET...
+ 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
+ .FALSE.
+ 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{AST\_GRID}{AST\_GRID} routine) 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 AST\_GRID 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_GRID}{AST\_GRID} routine) 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
+ .TRUE.,
+ 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
+ (.FALSE.)
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{
+ MaxOrder
+}{
+ The highest HEALPix order used in the MOC
+}{
+ \sstdescription{
+ This attribute gives the best resolution of the MOC expressed as a
+ HEALPix order in the range zero to 27 (this class does not support
+ orders greater than 27). It\texttt{'} s value can only be set once (for
+ instance as an option when the \htmlref{Moc}{Moc} constructor is invoked). An
+ error will be reported if a subsequent attempt to set or clear the
+ attribute is made. If no value is supplied for MaxOrder before the
+ first area of sky is added to the empty Moc, then a default value
+ will be selected and set, depending on the method used to add the
+ first area to the Moc:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ADDCELL}{AST\_ADDCELL}: the order of the specified cell.
+
+ \sstitem
+ \htmlref{AST\_ADDREGION}{AST\_ADDREGION}: if the added \htmlref{Region}{Region} is a Moc, then the Moc\texttt{'} s MaxOrder
+ value is used, Otherwise the value used corresponds to
+ the resolution closest to 0.1\% of the linear size of
+ the Region being added (determined using method
+ AST\_GETREGIONDISC).
+
+ \sstitem
+ \htmlref{AST\_ADDPIXELMASK$<$X$>$}{AST\_ADDPIXELMASK$<$X$>$}: the smallest order that results in the cells in
+ the Moc being no larger than the size of the pixels in the centre of
+ the pixel mask.
+
+ \sstitem
+ \htmlref{AST\_ADDMOCDATA}{AST\_ADDMOCDATA}: the largest order present in the supplied normalised
+ MOC data array.
+
+ \sstitem
+ AST\_ADDMOCString: the largest order present in the supplied MOC.
+
+ }
+ A default value of -1 will be returned for the MaxOrder attribute
+ prior to its value being set.
+
+ The \htmlref{MaxRes}{MaxRes} attribute is equivalent to MaxOrder but expresses the
+ resolution as a number of arc-seconds rather than as a HEALPix order.
+
+ Increasing the HEALPix order by one roughly halves the resolution of the
+ Moc. For instance, a value of 18 corresponds to a resolution of about
+ 0.8 arc-second, and 19 corresponds to about 0.4 arc-seconds.
+ }
+ \sstattributetype{
+ Integer.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MaxRes
+}{
+ The best resolution of the MOC
+}{
+ \sstdescription{
+ This attribute is an alternative to the \htmlref{MaxOrder}{MaxOrder} attribute and gives
+ the best resolution of the MOC expressed as a number of arc-seconds.
+ It can be set only when the \htmlref{Moc}{Moc} is constructed - an error is
+ reported if any subsequent attempt is made to set or clear the value
+ of MaxRes. See attribute MaxOrder for more details.
+
+ A default value of zero will be returned for the MaxRes attribute
+ prior to its value (or the value of MaxOrder) being set.
+ }
+ \sstattributetype{
+ Floating point, read-only.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\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{AST\_GETREGIONMESH}{AST\_GETREGIONMESH}
+ 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{Moc}{Moc}
+ }{
+ The MeshSize attribute is ignored when forming a mesh covering
+ the boundary of a Moc. Instead, the mesh will include a point
+ for the exterior corners of every HEALPix cell (at the order
+ specified by attribute \htmlref{MaxOrder}{MaxOrder}) that touches the boundary. Note,
+ this applies only to meshes covering the boundary of the Moc -
+ the MeshSize attribute is used as normal when forming a mesh
+ covering the area of the Moc.
+ }
+ \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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{
+ MinOrder
+}{
+ The lowest HEALPix order used in the MOC
+}{
+ \sstdescription{
+ This attribute controls the size of the largest hole or island that
+ could be missed when adding Regions or pixel masks into a \htmlref{Moc}{Moc} using
+ methods \htmlref{AST\_ADDREGION}{AST\_ADDREGION} or AST\_\_ADDPIXELMASK.
+ It gives the resolution of the initial grid used to identify areas
+ that are inside or outside the \htmlref{Region}{Region} or pixel mask, expressed as a
+ HEALPix order in the range zero to 27 (this class does not support
+ orders greater than 27). Unselected areas (i.e. bounded \texttt{"} holes\texttt{"} or
+ or \texttt{"} islands\texttt{"} in the selection) that are smaller than one cell of this
+ initial grid may be missed (i.e. such holes may be \texttt{"} filled in\texttt{"} and
+ islands omitted in the resulting Moc).
+
+ The default value is (\htmlref{MaxOrder}{MaxOrder}-4), with a lower limit of zero. For
+ instance, if MaxOrder is 16 (a resolution of 3.2 arc-seconds), then
+ MinOrder will be 12, meaning that bounded holes within selected areas
+ may be filled in if the hole is smaller than 51 arc-seconds. Increase
+ the value of this attribute to ensures that only holes smaller than
+ this value can be missed. Note, doing so will increase the time spent
+ creating the Moc.
+
+ To ensure no pixels are missed, set MinOrder to some very large
+ value (larger than 27). If MinOrder is set greater than MaxOrder, the
+ value of MaxOrder will be used whenever MinOrder is required.
+
+ The \htmlref{MinRes}{MinRes} attribute is equivalent to MinOrder but expresses the
+ resolution as a number of arc-seconds rather than as a HEALPix order.
+ Any change made to MinOrder will cause a corresponding change in the
+ MinRes attribute.
+ }
+ \sstattributetype{
+ Integer.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MinRes
+}{
+ The worst resolution of the MOC
+}{
+ \sstdescription{
+ This attribute gives the poorest resolution of the MOC expressed as
+ a number of arc-seconds. When a new value is set for MinRes, the
+ \htmlref{MinOrder}{MinOrder} attribute will be set to the order that gives a resolution
+ closest to the requested resolution. When the current value of
+ MinRes is requested, the resolution corresponding to the current
+ value of MinOrder will be returned. When MinRes is tested or
+ cleared, the MinOrder attribute will be tested or cleared.
+ }
+ \sstattributetype{
+ Floating point.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{Moc}{Moc}
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{
+ MocArea
+}{
+ The area covered by the Moc, in square arc-minutes
+}{
+ \sstdescription{
+ This read-only attribute gives the area covered by the \htmlref{Moc}{Moc}, in
+ square arc-minutes.
+ }
+ \sstattributetype{
+ Floating point, read-only.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MocFormat
+}{
+ Format for encoding Mocs as text
+}{
+ \sstdescription{
+ This attribute specifies the format to use when AST \htmlref{Moc}{Moc}
+ Objects are converted to text by a \htmlref{MocChan}{MocChan}. There are currently two
+ ways (conventions) by which MOCs may be represented in the form of
+ text and the MocFormat attribute is used to specify which of these
+ should be used:
+
+ \sstitemlist{
+
+ \sstitem
+ \texttt{"} JSON\texttt{"} : Encodes a Moc \htmlref{Object}{Object} as a JSON string using the JSON
+ serialisation described in the MOC recommendation (version 1.1).
+
+ \sstitem
+ \texttt{"} STRING\texttt{"} : Encodes a Moc Object as using the string serialisation
+ described in the MOC recommendation (version 1.1).
+
+ }
+ The value assigned to the MocFormat does not affect the behaviour
+ of the
+ \htmlref{AST\_READ}{AST\_READ}
+ method, which automatically identifies the format used by the
+ external text and sets the MocFormat attribute to the
+ corresponding value.
+
+ The \htmlref{AST\_WRITE}{AST\_WRITE}
+ method will create the external text using the format
+ specified by the current value of the MocFormat attribute.
+
+ The initial default value of the attribute is \texttt{"} UNKNOWN\texttt{"} .
+ }
+ \sstattributetype{
+ String.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ MocChan
+ }{
+ All MocChans have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MocLength
+}{
+ The table length used to describe a Moc in FITS
+}{
+ \sstdescription{
+ This read-only attribute gives the length of the number of rows
+ needed to describe the \htmlref{Moc}{Moc} in a FITS binary table. This is the
+ number of cells in the normalised Moc.
+ }
+ \sstattributetype{
+ Integer, read-only.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MocLineLen
+}{
+ 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{MocChan}{MocChan} 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). The default value is 80.
+
+ Note, the default value of 80 may not be appropriate when a MocChan
+ is used within Fortran code. In this case, MocLineLen should usually
+ be set to the size of the CHARACTER variable used to receive the
+ text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function. This avoids
+ the possibility of long lines being truncated invisibly within
+ AST\_GETLINE.
+ }
+ \sstattributetype{
+ Integer.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ MocChan
+ }{
+ All MocChans have this attribute.
+ }
+ }
+}
+\sstroutine{
+ MocType
+}{
+ The data type used to describe a Moc in FITS
+}{
+ \sstdescription{
+ This read-only attribute gives the data type to be used when
+ writing out the \htmlref{Moc}{Moc} to a FITS binary table. The attribute takes the
+ value 4 or 8. The binary table should contain a single column of
+ signed integer values in which each integer has 4 or 8 bytes, as
+ indicated by the value of this attribute.
+ }
+ \sstattributetype{
+ Integer, read-only.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ Moc
+ }{
+ All Mocs have this attribute.
+ }
+ }
+}
+\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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN} and \htmlref{AST\_REMOVECOLUMN}{AST\_REMOVECOLUMN}
+ 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{AST\_NORM}{AST\_NORM}.
+
+ 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{AST\_NEGATE}{AST\_NEGATE} routine.
+
+ 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 attribute 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{AST\_TEXT}{AST\_TEXT} and \htmlref{AST\_MARK}{AST\_MARK} 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{AST\_ADDPARAMETER}{AST\_ADDPARAMETER} and \htmlref{AST\_REMOVEPARAMETER}{AST\_REMOVEPARAMETER}
+ 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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{
+ Floating point.
+ }
+ \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{AST\_WCSMAP}{AST\_WCSMAP} 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 OPTIONS argument of \htmlref{AST\_WCSMAP}{AST\_WCSMAP} (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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{AST\_CLONE}{AST\_CLONE}
+ 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, this
+ scheme has now been added to the registry of FITS conventions
+ (http://fits.gsfc.nasa.gov/registry/tpvwcs.html) and headers
+ that use this convention are created by the SCAMP utility
+ (http://www.astromatic.net/software/scamp) and the Dark Energy
+ Camera at NOAO.
+
+ 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{AST\_FINDFRAME}{AST\_FINDFRAME}) 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_CLONE}{AST\_CLONE}, \htmlref{AST\_ANNUL}{AST\_ANNUL} or \htmlref{AST\_END}{AST\_END} 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{AST\_FINDFRAME}{AST\_FINDFRAME} or \htmlref{AST\_CONVERT}{AST\_CONVERT}
+ 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{AST\_SETREFPOS}{AST\_SETREFPOS} and \htmlref{AST\_GETREFPOS}{AST\_GETREFPOS} may be used to access the value 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{AST\_FORMAT}{AST\_FORMAT} 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{AST\_WRITE}{AST\_WRITE} routine.
+ }
+ }
+}
+\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.
+ }
+ \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{AST\_GRID}{AST\_GRID} routine) 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
+ GRAPHBOX argument when \htmlref{AST\_PLOT3D}{AST\_PLOT3D}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}).
+
+ 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 FWD and
+ INV arguments 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}).
+
+ 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 FWD and
+ INV arguments 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ 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{AST\_WRITE}{AST\_WRITE}
+ 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
+ AST\_WRITE
+ 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{AST\_COPY}{AST\_COPY} or \htmlref{AST\_SHOW}{AST\_SHOW})
+ 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{
+ SipOK
+}{
+ Use Spitzer Space Telescope keywords to define distortion?
+}{
+ \sstdescription{
+ This attribute is a boolean value which specifies whether to include
+ support for the \texttt{"} SIP\texttt{"} scheme, which can be used to add distortion to
+ basic FITS-WCS projections. This scheme was first defined by the
+ Spitzer Space Telescope and is described in the following document:
+ http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
+ The default for SipOK is 1.
+
+ When using
+ \htmlref{AST\_READ}{AST\_READ}
+ to read a FITS-WCS encoded header, a suitable \htmlref{PolyMap}{PolyMap} will always be
+ included in the returned \htmlref{FrameSet}{FrameSet} if the header contains SIP
+ keywords, regardless of the value of the SipOK attribute. The PolyMap
+ will be immediately before the \htmlref{MatrixMap}{MatrixMap} that corresponds to the FITS-WCS
+ PC or CD matrix.
+
+ When using
+ \htmlref{AST\_WRITE}{AST\_WRITE}
+ to write a FrameSet to a FITS-WCS encoded header, suitable SIP
+ keywords will be included in the header if the FrameSet contains a
+ PolyMap immediately before the MatrixMap that corresponds to the
+ FITS-WCS PC or CD matrix, but only if the SipOK attribute is non-zero.
+ If the FrameSet contains a PolyMap but SipOK is zero, then an attempt
+ will be made to write out the FrameSet without SIP keywords using a
+ linear approximation to the pixel-to-IWC mapping. If this fails
+ because the \htmlref{Mapping}{Mapping} exceeds the linearity requirement specified by
+ attribute \htmlref{FitsTol}{FitsTol},
+ AST\_WRITE
+ will return zero, indicating that the FrameSet could not be written
+ out. Note, SIP headers can only be produced for axes that form part
+ of a \htmlref{SkyFrame}{SkyFrame}.
+
+ Note, the SIP distortion scheme is independent of the TPV/TPN
+ distortion schemes (see attribute \htmlref{PolyTan}{PolyTan}). A FITS-WCS header could
+ in principle, contain keywords for both schemes although this is unlikely.
+ }
+ \sstattributetype{
+ Integer (boolean).
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{FitsChan}{FitsChan}
+ }{
+ All FitsChans have this attribute.
+ }
+ }
+}
+\sstroutine{
+ SipReplace
+}{
+ Replace SIP inverse transformation?
+}{
+ \sstdescription{
+ This attribute is a boolean value which specifies how SIP keywords
+ should be handled when reading a FITS-WCS encoded header using the
+ \htmlref{AST\_READ}{AST\_READ}
+ function. See
+ http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
+ for more information about SIP headers. If SipReplace is non-zero,
+ then any SIP keywords describing the inverse transformation (i.e. from
+ WCS to pixel coordinates) are ignored. Instead a new inverse
+ transformation is found by performing a fit to the forward
+ transformation. The SipReplace attribute can be set to zero to prevent
+ this happening. If SipReplace is zero, any SIP keywords describing the
+ inverse transformation are used as supplied, rather than being
+ replaced using a new fit. The default value is 1.
+ }
+ \sstattributetype{
+ Integer (boolean).
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{FitsChan}{FitsChan}
+ }{
+ All FitsChans have this attribute.
+ }
+ }
+}
+\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{AST\_CONVERT}{AST\_CONVERT} or \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME} 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 to 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{AST\_CONVERT}{AST\_CONVERT} or \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}).
+ 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{AST\_MAPKEY}{AST\_MAPKEY}
+ 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{AST\_READ}{AST\_READ}
+ 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
+ AST\_READ
+ 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{AST\_COPY}{AST\_COPY} or \htmlref{AST\_SHOW}{AST\_SHOW})
+ 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{AST\_READ}{AST\_READ}
+ 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
+ AST\_READ.
+ 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
+ AST\_READ.
+ If more than one of these attributes is set non-zero, then the
+ actual \htmlref{Object}{Object} returned by
+ AST\_READ
+ 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
+ AST\_READ
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ 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{AST\_READ}{AST\_READ}
+ 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
+ AST\_READ.
+ 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
+ AST\_READ.
+ If more than one of these attributes is set non-zero, then the
+ actual \htmlref{Object}{Object} returned by
+ AST\_READ
+ 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
+ AST\_READ
+ 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
+ (AST\_\_NULL)
+ will be returned by
+ AST\_READ
+ 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.
+
+ Note, the default value of zero is unlikely to be appropriate when
+ an StcsChan is used within Fortran code. In this case, StcsLength
+ should usually be set to the size of the CHARACTER variable used to
+ receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function.
+ In addition, the Indent attribute should be set non-zero. This
+ avoids the possibility of long lines being truncated invisibly
+ within AST\_GETLINE.
+ }
+ \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{AST\_READ}{AST\_READ}
+ 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
+ AST\_READ.
+ 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
+ AST\_READ.
+ If more than one of these attributes is set non-zero, then the
+ actual \htmlref{Object}{Object} returned by
+ AST\_READ
+ 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
+ AST\_READ
+ 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
+ inherited STATUS variable being set to an error value.
+ 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{AST\_WARNINGS}{AST\_WARNINGS}
+ 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 .TRUE.
+ 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{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine 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 .TRUE.
+ 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 AST\_SETACTIVEUNIT routine 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{AST\_WRITE}{AST\_WRITE}
+ method will return zero if the write operation would required the
+ use of the -TAB algorithm, and the
+ \htmlref{AST\_READ}{AST\_READ}
+ method will return
+ AST\_\_NULL
+ 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 AST\_WRITE
+ 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{AST\_GETTABLES}{AST\_GETTABLES}
+ method, and the data (and headers) within it copied into a new
+ FITS binary table extension. See
+ AST\_GETTABLES
+ 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 AST\_READ
+ 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{AST\_PUTTABLES}{AST\_PUTTABLES} or \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}) before invoking the AST\_READ method.
+ Secondly, if the application does not know which FITS binary tables
+ will be needed by
+ AST\_READ,
+ then it can register a call-back function with the FitsChan using
+ method
+ \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE}.
+ This call-back function will be called from within
+ AST\_READ
+ 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
+ AST\_READ. Note, currently AST\_READ
+ can only handle -TAB headers that describe 1-dimensional (i.e.
+ separable) axes.
+ }
+ \sstattributetype{
+ Integer.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ FitsChan
+ }{
+ All FitsChans have this attribute.
+ }
+ }
+}
+\sstroutine{
+ TextGapType
+}{
+ Controls the interpretation of attributes TextLabGap and TitleGap
+}{
+ \sstdescription{
+ This attribute controls how the values supplied for attributes
+ TextLabGap and \htmlref{TitleGap}{TitleGap} are used. If the TextGapType value is
+ \texttt{"} box\texttt{"} (the default), then the gaps are measured from the nearest
+ edge of the bounding box enclosing all other parts of the annotated
+ grid (excluding other descriptive labels). If the TextGapType value
+ is \texttt{"} plot\texttt{"} , then the gaps are measured from the nearest edge of the
+ plotting area.
+
+ Note, this attribute only affects the position from which the gaps
+ are measured - the size of the gap should always be given as a
+ fraction of the minimum dimension of the plotting area.
+ }
+ \sstattributetype{
+ String.
+ }
+ \sstapplicability{
+ \sstsubsection{
+ \htmlref{Plot}{Plot}
+ }{
+ All Plots 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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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 a reference point specified by the \htmlref{TextGapType}{TextGapType}
+ attribute (by default, 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 depends on the
+ value of attribute TextGapType: if TextGapType is \texttt{"} box\texttt{"} , the
+ default is $+$0.01, otherwise the default is $+$0.07.
+ }
+ \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{AST\_GRID}{AST\_GRID} routine) 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{AST\_GRID}{AST\_GRID} routine) 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 a reference point specified by the \htmlref{TextGapType}{TextGapType} attribute (by
+ default, the top edge of a box enclosing all 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 the 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{AST\_GRID}{AST\_GRID} 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{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT} routine 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{AST\_FORMAT}{AST\_FORMAT} 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
+ AST\_FORMAT.
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}) 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{AST\_CLONE}{AST\_CLONE}
+ 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
+ AST\_GETC
+ is unaffected by the UseDefs attribute - default values will always
+ be returned if no value has been set. Application code should use the
+ \htmlref{AST\_TEST}{AST\_TEST}
+ 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{AST\_REMAPFRAME}{AST\_REMAPFRAME}
+ 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{AST\_ADDFRAME}{AST\_ADDFRAME} method. By default, the Mapping supplied to \htmlref{AST\_ADDVARIANT}{AST\_ADDVARIANT}
+ is assigned a name equal to the Domain name of the Frame. To assign a
+ different name to it, the
+ AST\_ADDVARIANT
+ method should then be called specifying the required name and a NULL
+ Mapping. The
+ AST\_ADDVARIANT
+ 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{AST\_MIRRORVARIANTS}{AST\_MIRRORVARIANTS} routine
+ 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
+ .TRUE.
+ if the current Frame contains any variant Mappings, and
+ .FALSE.
+ 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
+ AST\_REMAPFRAME
+ method, the currently selected variant Mapping is used by
+ AST\_REMAPFRAME
+ 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{AST\_FINDFITS}{AST\_FINDFITS}) after the call to \htmlref{AST\_READ}{AST\_READ} or \htmlref{AST\_WRITE}{AST\_WRITE} 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 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{AST\_WARNINGS}{AST\_WARNINGS}
+ 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{AST\_WCSMAP}{AST\_WCSMAP} 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{AST\_WCSMAP}{AST\_WCSMAP} and cannot subsequently be
+ changed.
+
+ The values used are represented by symbolic constants 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{AST\_WRITE}{AST\_WRITE} routine 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{AST\_READ}{AST\_READ}.
+ 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.
+
+ Note, the default value of zero is unlikely to be appropriate when
+ an XmlChan is used within Fortran code. In this case, XmlLength
+ should usually be set to the size of the CHARACTER variable used to
+ receive the text returned by \htmlref{AST\_GETLINE}{AST\_GETLINE} within the sink function.
+ This avoids the possibility of long lines being truncated invisibly
+ within AST\_GETLINE.
+ }
+ \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\_PAR.
+ 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{AST\_INVERT}{AST\_INVERT}),
+ 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{AST\_CLONE}{AST\_CLONE}
+ 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{AST\_WRITE}{AST\_WRITE}).
+ }
+ \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{AST\_BOX}{AST\_BOX}
+ }
+ \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 routines 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{"} routines 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{AST\_CHANNEL}{AST\_CHANNEL}
+ }
+ \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 routines applicable to all Objects, the
+ following routines may also be applied to all Channels:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_WARNINGS}{AST\_WARNINGS}: Return warnings from the previous read or write
+
+ \sstitem
+ \htmlref{AST\_READ}{AST\_READ}: Read an Object from a Channel
+
+ \sstitem
+ \htmlref{AST\_WRITE}{AST\_WRITE}: Write an Object to a Channel
+ }
+ }
+}
+\sstroutine{
+ ChebyMap
+}{
+ Map coordinates using Chebyshev polynomial functions
+}{
+ \sstdescription{
+ A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
+ transformation. Each output coordinate is a linear combination of
+ Chebyshev polynomials of the first kind, of order zero up to a
+ specified maximum order, evaluated at the input coordinates. The
+ coefficients to be used in the linear combination are specified
+ separately for each output coordinate.
+
+ For a 1-dimensional ChebyMap, the forward transformation is defined
+ as follows:
+
+ f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
+
+ where:
+ \sstitemlist{
+
+ \sstitem
+ Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
+
+ \sstitem
+ T0(x\texttt{'} ) = 1
+
+ \sstitem
+ T1(x\texttt{'} ) = x\texttt{'}
+
+ \sstitem
+ Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
+
+ \sstitem
+ x\texttt{'} is the inpux axis value, x, offset and scaled to the range
+ [-1, 1] as x ranges over a specified bounding box, given when the
+ ChebyMap is created. The input positions, x, supplied to the
+ forward transformation must fall within the bounding box - bad
+ axis values (AST\_\_BAD) are generated for points outside the
+ bounding box.
+
+ }
+ For an N-dimensional ChebyMap, the forward transformation is a
+ generalisation of the above form. Each output axis value is the sum
+ of NCOEFF
+ terms, where each term is the product of a single coefficient
+ value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"} is the
+ normalised value of the i\texttt{'} th input axis value.
+
+ The forward and inverse transformations are defined independantly
+ by separate sets of coefficients, supplied when the ChebyMap is
+ created. If no coefficients are supplied to define the inverse
+ transformation, the
+ \htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}
+ method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
+ inverse transformation. The inverse transformation so generated
+ will be a Chebyshev polynomial with coefficients chosen to minimise
+ the residuals left by a round trip (forward transformation followed
+ by inverse transformation).
+ }
+ \sstconstructor{
+ \htmlref{AST\_CHEBYMAP}{AST\_CHEBYMAP}
+ }
+ \sstdiytopic{
+ Inheritance
+ }{
+ The ChebyMap class inherits from the PolyMap class.
+ }
+ \sstdiytopic{
+ Attributes
+ }{
+ The ChebyMap class does not define any new attributes beyond those
+ which are applicable to all PolyMaps.
+ }
+ \sstdiytopic{
+ Functions
+ }{
+ In addition to those routines applicable to all PolyMap, the
+ following routines may also be applied to all ChebyMaps:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_CHEBYDOMAIN}{AST\_CHEBYDOMAIN}: Get the bounds of the domain of the ChebyMap
+ }
+ }
+}
+\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{AST\_CIRCLE}{AST\_CIRCLE}
+ }
+ \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 routines applicable to all Regions, the
+ following routines may also be applied to all Circles:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_CIRCLEPARS}{AST\_CIRCLEPARS}: 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{AST\_CMPFRAME}{AST\_CMPFRAME}
+ }
+ \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 routines 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{AST\_CMPMAP}{AST\_CMPMAP}
+ }
+ \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 routines 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{AST\_CONVERT}{AST\_CONVERT}
+ 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
+ AST\_CONVERT
+ 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{AST\_CMPREGION}{AST\_CMPREGION}
+ }
+ \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 routines 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{AST\_DSBSPECFRAME}{AST\_DSBSPECFRAME}
+ }
+ \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 routines 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{AST\_READ}{AST\_READ}) 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 routines 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{AST\_ELLIPSE}{AST\_ELLIPSE}
+ }
+ \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 routines applicable to all Regions, the
+ following routines may also be applied to all Ellipses:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ELLIPSEPARS}{AST\_ELLIPSEPARS}: 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{AST\_WRITE}{AST\_WRITE}) 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{AST\_FINDFITS}{AST\_FINDFITS}), new
+ cards may be inserted (\htmlref{AST\_PUTFITS}{AST\_PUTFITS}, \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}, \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}) and
+ existing ones may be deleted (\htmlref{AST\_DELFITS}{AST\_DELFITS}), extracted
+ (\htmlref{AST\_GETFITS$<$X$>$}{AST\_GETFITS$<$X$>$}) or changed (AST\_SETFITS$<$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 AST\_PUTFITS, AST\_PUTCARDS, AST\_WRITE
+ 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 AST\_FINDFITS or \htmlref{AST\_READ}{AST\_READ}).
+
+ 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 AST\_READ and AST\_WRITE, when used with
+ a FitsChan, depends on the encoding in use. In general, however,
+ all successful use of AST\_READ 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{AST\_RETAINFITS}{AST\_RETAINFITS} routine).
+ An unsuccessful call of
+ AST\_READ
+ (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 AST\_WRITE 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{AST\_FITSCHAN}{AST\_FITSCHAN}
+ }
+ \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{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection?
+
+ \sstitem
+ \htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
+
+ \sstitem
+ \htmlref{SipOK}{SipOK}: Use Spitzer Space Telescope keywords to define distortion?
+
+ \sstitem
+ \htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
+
+ \sstitem
+ \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"} algorithm be recognised?
+
+ \sstitem
+ \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions
+ }
+ }
+ \sstdiytopic{
+ Functions
+ }{
+ In addition to those routines applicable to all Channels, the
+ following routines may also be applied to all FitsChans:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_DELFITS}{AST\_DELFITS}: Delete the current FITS card in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_EMPTYFITS}{AST\_EMPTYFITS}: Delete all cards in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_FINDFITS}{AST\_FINDFITS}: Find a FITS card in a FitsChan by keyword
+
+ \sstitem
+ \htmlref{AST\_GETFITS$<$X$>$}{AST\_GETFITS$<$X$>$}: Get a keyword value from a FitsChan
+
+ \sstitem
+ \htmlref{AST\_GETTABLES}{AST\_GETTABLES}: Retrieve any FitsTables from a FitsChan
+
+ \sstitem
+ \htmlref{AST\_PURGEWCS}{AST\_PURGEWCS}: Delete all WCS-related cards in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}: Stores a set of FITS header card in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_PUTFITS}{AST\_PUTFITS}: Store a FITS header card in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_PUTTABLE}{AST\_PUTTABLE}: Store a single FitsTables in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_PUTTABLES}{AST\_PUTTABLES}: Store multiple FitsTables in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_READFITS}{AST\_READFITS}: Read cards in through the source function
+
+ \sstitem
+ \htmlref{AST\_REMOVETABLES}{AST\_REMOVETABLES}: Remove one or more FitsTables from a FitsChan
+
+ \sstitem
+ \htmlref{AST\_RETAINFITS}{AST\_RETAINFITS}: Ensure current card is retained in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_SETFITS$<$X$>$}{AST\_SETFITS$<$X$>$}: Store a new keyword value in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_TABLESOURCE}{AST\_TABLESOURCE}: Register a source function for FITS table access
+
+ \sstitem
+ \htmlref{AST\_TESTFITS}{AST\_TESTFITS}: Test if a keyword has a defined value in a FitsChan
+
+ \sstitem
+ \htmlref{AST\_WRITEFITS}{AST\_WRITEFITS}: Write all cards out to the sink function
+ }
+ }
+}
+\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{AST\_FITSTABLE}{AST\_FITSTABLE}
+ }
+ \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 routines applicable to all Tables, the
+ following routines may also be applied to all FitsTables:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_COLUMNNULL}{AST\_COLUMNNULL}: Get/set the null value for a column of a FitsTable
+
+ \sstitem
+ \htmlref{AST\_COLUMNSIZE}{AST\_COLUMNSIZE}: Get number of bytes needed to hold a full column of data
+
+ \sstitem
+ \htmlref{AST\_GETCOLUMNDATA}{AST\_GETCOLUMNDATA}: Retrieve all the data values stored in a column
+
+ \sstitem
+ AST\_GETTABLEHEADER: Get the FITS headers from a FitsTable
+
+ \sstitem
+ \htmlref{AST\_PUTCOLUMNDATA}{AST\_PUTCOLUMNDATA}: Store data values in a column
+
+ \sstitem
+ \htmlref{AST\_PUTTABLEHEADER}{AST\_PUTTABLEHEADER}: 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{AST\_FLUXFRAME}{AST\_FLUXFRAME}
+ }
+ \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 routines 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{AST\_FRAME}{AST\_FRAME}
+ }
+ \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{Dtai}{Dtai}: Difference between the TAI and UTC timescale
+
+ \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 routines applicable to all Mappings, the
+ following routines may also be applied to all Frames:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ANGLE}{AST\_ANGLE}: Find the angle subtended by two points at a third point
+
+ \sstitem
+ \htmlref{AST\_AXANGLE}{AST\_AXANGLE}: Find the angle from an axis, to a line through two points
+
+ \sstitem
+ \htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE}: Calculate the distance between two axis values
+
+ \sstitem
+ \htmlref{AST\_AXNORM}{AST\_AXNORM}: Normalises an array of axis values
+
+ \sstitem
+ \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET}: Calculate an offset along an axis
+
+ \sstitem
+ \htmlref{AST\_CONVERT}{AST\_CONVERT}: Determine how to convert between two coordinate systems
+
+ \sstitem
+ \htmlref{AST\_DISTANCE}{AST\_DISTANCE}: Calculate the distance between two points in a Frame
+
+ \sstitem
+ \htmlref{AST\_FINDFRAME}{AST\_FINDFRAME}: Find a coordinate system with specified characteristics
+
+ \sstitem
+ \htmlref{AST\_FORMAT}{AST\_FORMAT}: Format a coordinate value for a Frame axis
+
+ \sstitem
+ \htmlref{AST\_GETACTIVEUNIT}{AST\_GETACTIVEUNIT}: Determines how the Unit attribute will be used
+
+ \sstitem
+ \htmlref{AST\_INTERSECT}{AST\_INTERSECT}: Find the intersection between two geodesic curves
+
+ \sstitem
+ \htmlref{AST\_MATCHAXES}{AST\_MATCHAXES}: Find any corresponding axes in two Frames
+
+ \sstitem
+ \htmlref{AST\_NORM}{AST\_NORM}: Normalise a set of Frame coordinates
+
+ \sstitem
+ \htmlref{AST\_OFFSET}{AST\_OFFSET}: Calculate an offset along a geodesic curve
+
+ \sstitem
+ \htmlref{AST\_OFFSET2}{AST\_OFFSET2}: Calculate an offset along a geodesic curve in a 2D Frame
+
+ \sstitem
+ \htmlref{AST\_PERMAXES}{AST\_PERMAXES}: Permute the order of a Frame\texttt{'} s axes
+
+ \sstitem
+ \htmlref{AST\_PICKAXES}{AST\_PICKAXES}: Create a new Frame by picking axes from an existing one
+
+ \sstitem
+ \htmlref{AST\_RESOLVE}{AST\_RESOLVE}: Resolve a vector into two orthogonal components
+
+ \sstitem
+ \htmlref{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT}: Specify how the Unit attribute should be used
+
+ \sstitem
+ \htmlref{AST\_UNFORMAT}{AST\_UNFORMAT}: 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{AST\_INVERT}{AST\_INVERT}), 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 masking effects produced by any Regions included
+ in the path between the Frames.
+ }
+ \sstconstructor{
+ \htmlref{AST\_FRAMESET}{AST\_FRAMESET}
+ }
+ \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 stored 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 routines applicable to all Frames, the
+ following routines may also be applied to all FrameSets:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}: Add a Frame to a FrameSet to define a new coordinate
+ system
+
+ \sstitem
+ \htmlref{AST\_ADDVARIANT}{AST\_ADDVARIANT}: Add a variant Mapping to the current Frame
+
+ \sstitem
+ \htmlref{AST\_GETFRAME}{AST\_GETFRAME}: Obtain a pointer to a specified Frame in a FrameSet
+
+ \sstitem
+ \htmlref{AST\_GETMAPPING}{AST\_GETMAPPING}: Obtain a Mapping between two Frames in a FrameSet
+
+ \sstitem
+ \htmlref{AST\_MIRRORVARIANTS}{AST\_MIRRORVARIANTS}: Make the current Frame mirror variant Mappings in another Frame
+
+ \sstitem
+ \htmlref{AST\_REMAPFRAME}{AST\_REMAPFRAME}: Modify a Frame\texttt{'} s relationship to the other Frames in a
+ FrameSet
+
+ \sstitem
+ \htmlref{AST\_REMOVEFRAME}{AST\_REMOVEFRAME}: 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{AST\_GRISMMAP}{AST\_GRISMMAP}
+ }
+ \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 routines 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{AST\_INTERVAL}{AST\_INTERVAL}
+ }
+ \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 routines beyond those
+ which are applicable to all Regions.
+ }
+}
+\sstroutine{
+ IntraMap
+}{
+ Map points using a private transformation routine
+}{
+ \sstdescription{
+ The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which
+ encapsulates a privately-defined coordinate transformation
+ routine (e.g. written in Fortran) 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{AST\_INTRAREG}{AST\_INTRAREG} before creating an IntraMap.
+ }
+ \sstconstructor{
+ \htmlref{AST\_INTRAMAP}{AST\_INTRAMAP} (also see AST\_INTRAREG)
+ }
+ \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 routines 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),
+ 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{AST\_KEYMAP}{AST\_KEYMAP}
+ }
+ \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 routines applicable to all Objects, the
+ following routines may also be applied to all KeyMaps:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_MAPDEFINED}{AST\_MAPDEFINED}: Does a KeyMap contain a defined value for a key?
+
+ \sstitem
+ \htmlref{AST\_MAPGETC}{AST\_MAPGETC}: Get a scalar or vector entry as a single string.
+
+ \sstitem
+ \htmlref{AST\_MAPGET0$<$X$>$}{AST\_MAPGET0$<$X$>$}: Get a named scalar entry from a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPGET1$<$X$>$}{AST\_MAPGET1$<$X$>$}: Get a named vector entry from a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPGETELEM$<$X$>$}{AST\_MAPGETELEM$<$X$>$}: Get an element of a named vector entry from a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPHASKEY}{AST\_MAPHASKEY}: Does the KeyMap contain a named entry?
+
+ \sstitem
+ \htmlref{AST\_MAPKEY}{AST\_MAPKEY}: Return the key name at a given index in the KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPLENC}{AST\_MAPLENC}: Get the length of a named character entry in a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPLENGTH}{AST\_MAPLENGTH}: Get the length of a named entry in a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPCOPY}{AST\_MAPCOPY}: Copy entries from one KeyMap into another
+
+ \sstitem
+ \htmlref{AST\_MAPPUT0$<$X$>$}{AST\_MAPPUT0$<$X$>$}: Add a new scalar entry to a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPPUT1$<$X$>$}{AST\_MAPPUT1$<$X$>$}: Add a new vector entry to a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPPUTELEM$<$X$>$}{AST\_MAPPUTELEM$<$X$>$}: Puts a value into a vector entry in a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}: Add a new entry to a KeyMap with an undefined value
+
+ \sstitem
+ \htmlref{AST\_MAPREMOVE}{AST\_MAPREMOVE}: Removed a named entry from a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPRENAME}{AST\_MAPRENAME}: Rename an existing entry in a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPSIZE}{AST\_MAPSIZE}: Get the number of entries in a KeyMap
+
+ \sstitem
+ \htmlref{AST\_MAPTYPE}{AST\_MAPTYPE}: 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{AST\_LUTMAP}{AST\_LUTMAP}
+ }
+ \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 routines 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 routines applicable to all Objects, the
+ following routines may also be applied to all Mappings:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_DECOMPOSE}{AST\_DECOMPOSE}: Decompose a Mapping into two component Mappings
+
+ \sstitem
+ \htmlref{AST\_TRANGRID}{AST\_TRANGRID}: Transform a grid of positions
+
+ \sstitem
+ \htmlref{AST\_INVERT}{AST\_INVERT}: Invert a Mapping
+
+ \sstitem
+ \htmlref{AST\_LINEARAPPROX}{AST\_LINEARAPPROX}: Calculate a linear approximation to a Mapping
+
+ \sstitem
+ \htmlref{AST\_QUADAPPROX}{AST\_QUADAPPROX}: Calculate a quadratic approximation to a 2D Mapping
+
+ \sstitem
+ \htmlref{AST\_MAPBOX}{AST\_MAPBOX}: Find a bounding box for a Mapping
+
+ \sstitem
+ \htmlref{AST\_MAPSPLIT}{AST\_MAPSPLIT}: Split a Mapping up into parallel component Mappings
+
+ \sstitem
+ \htmlref{AST\_RATE}{AST\_RATE}: Calculate the rate of change of a Mapping output
+
+ \sstitem
+ \htmlref{AST\_REBIN$<$X$>$}{AST\_REBIN$<$X$>$}: Rebin a region of a data grid
+
+ \sstitem
+ \htmlref{AST\_REBINSEQ$<$X$>$}{AST\_REBINSEQ$<$X$>$}: Rebin a region of a sequence of data grids
+
+ \sstitem
+ \htmlref{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS}: Remove any Regions from a Mapping
+
+ \sstitem
+ \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$X$>$}: Resample a region of a data grid
+
+ \sstitem
+ \htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}: Simplify a Mapping
+
+ \sstitem
+ \htmlref{AST\_TRAN1}{AST\_TRAN1}: Transform 1-dimensional coordinates
+
+ \sstitem
+ \htmlref{AST\_TRAN2}{AST\_TRAN2}: Transform 2-dimensional coordinates
+
+ \sstitem
+ \htmlref{AST\_TRANN}{AST\_TRANN}: Transform N-dimensional coordinates
+ }
+ }
+}
+\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 Fortran. 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{AST\_MATHMAP}{AST\_MATHMAP}
+ }
+ \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 routines 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{AST\_MATRIXMAP}{AST\_MATRIXMAP}
+ }
+ \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 routines beyond those
+ which are applicable to all Mappings.
+ }
+}
+\sstroutine{
+ Moc
+}{
+ An arbitrary region of the sky expressed as a collection of HEALPix
+ cells
+}{
+ \sstdescription{
+ The Moc class uses the IVOA MOC (Multi-Order Coverage) recommendation
+ to describe a region on the sky. The region is made up of an
+ arbitrary collection of cells from the HEALPix sky tessellation,
+ and thus may represent any area on the sky, subject to the
+ constraint that the edges of the area correspond to edges of the
+ HEALPix cells. See the MOC recommendation for further information
+ (http://www.ivoa.net/documents/MOC/).
+
+ The Moc class describes an arbitrary collection of cells on the sky,
+ whereas other subclasses of \htmlref{Region}{Region} describe exact geometric shapes
+ in any arbitrary domain. This results in some differences between
+ Mocs and other types of Region, the main one being that Mocs have
+ no associated uncertainty.
+
+ The MOC recommendation requires that a MOC always describes a sky
+ area using the ICRS coordinate system. However, the Moc class, like
+ other subclasses of Region, allows its attributes to be changed so
+ that it represents the equivalent area in any celestial coordinate
+ system that can be mapped to ICRS. See attribute \htmlref{Adaptive}{Adaptive}.
+
+ In practice, to use this class an empty Moc object (i.e. a Moc
+ describing a null area of the sky) should first be created using the
+ \htmlref{AST\_MOC}{AST\_MOC}
+ constructor. Areas of the sky should then be added into the empty
+ Moc using one or more of the class methods.
+
+ If it is required to write a Moc out to a FITS binary table, the
+ data value and headers to put in the table can be obtained using
+ methods
+ \htmlref{AST\_GETMOCDATA}{AST\_GETMOCDATA} and \htmlref{AST\_GETMOCHEADER}{AST\_GETMOCHEADER}.
+ The MOC described by an existing FITS binary table can be added
+ into a Moc object using the
+ \htmlref{AST\_ADDMOCDATA}{AST\_ADDMOCDATA} method.
+
+ Note, this class is limited to MOCs for which the number of cells
+ in the normalised MOC can be represented in a four byte signed integer.
+ }
+ \sstconstructor{
+ AST\_MOC
+ }
+ \sstdiytopic{
+ Inheritance
+ }{
+ The Moc class inherits from the Region class.
+ }
+ \sstdiytopic{
+ Attributes
+ }{
+ In addition to those attributes common to all Regions, every
+ Moc also has the following attributes:
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{MaxOrder}{MaxOrder}: the highest HEALPix order used in the MOC
+
+ \sstitem
+ \htmlref{MaxRes}{MaxRes}: the best resolution of the MOC, in arc-seconds
+
+ \sstitem
+ \htmlref{MinOrder}{MinOrder}: the lowest HEALPix order used in the MOC
+
+ \sstitem
+ \htmlref{MinRes}{MinRes}: the worst resolution of the MOC, in arc-seconds
+
+ \sstitem
+ \htmlref{MocArea}{MocArea}: the area of the MOC
+
+ \sstitem
+ \htmlref{MocLength}{MocLength}: the table length used to describe a MOC in FITS
+
+ \sstitem
+ \htmlref{MocType}{MocType}: the data type used to describe a MOC in FITS
+ }
+ }
+ \sstdiytopic{
+ Functions
+ }{
+ In addition to those routines applicable to all Regions, the
+ following routines may also be applied to all Mocs:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ADDCELL}{AST\_ADDCELL}: Adds a single HEALPix cell into an existing Moc
+
+ \sstitem
+ ADT\_ADDMOCDATA: Adds a FITS binary table into an existing Moc
+
+ \sstitem
+ ADT\_ADDMOCSTRING: Adds a JSON or string-encoded MOC into an existing Moc
+
+ \sstitem
+ \htmlref{AST\_ADDPIXELMASK$<$X$>$}{AST\_ADDPIXELMASK$<$X$>$}: Adds a pixel mask to an existing Moc
+
+ \sstitem
+ \htmlref{AST\_ADDREGION}{AST\_ADDREGION}: Adds a Region to an existing Moc
+
+ \sstitem
+ \htmlref{AST\_GETCELL}{AST\_GETCELL}: Identify the next cell included in a Moc
+
+ \sstitem
+ \htmlref{AST\_GETMOCDATA}{AST\_GETMOCDATA}: Get the FITS binary table data describing a Moc
+
+ \sstitem
+ \htmlref{AST\_GETMOCHEADER}{AST\_GETMOCHEADER}: Get the FITS binary table headers describing a Moc
+
+ \sstitem
+ \htmlref{AST\_GETMOCSTRING}{AST\_GETMOCSTRING}: Get the JSON or string-encoded form of a Moc
+
+ \sstitem
+ \htmlref{AST\_TESTCELL}{AST\_TESTCELL}: Test if a single HEALPix cell is included in a Moc
+ }
+ }
+}
+\sstroutine{
+ MocChan
+}{
+ I/O Channel for textual representations of Mocs
+}{
+ \sstdescription{
+ A MocChan is a specialised form of \htmlref{Channel}{Channel} which supports the
+ reading and writing of AST \htmlref{Moc}{Moc} objects as text, using the
+ conventions of the JSON and string encodings described in
+ the IVOA\texttt{'} s MOC recommendation, version 1.1. Writing a Moc
+ to a MocChan (using
+ \htmlref{AST\_WRITE}{AST\_WRITE}) will, if the Moc is suitable, generate a
+ textual description of that Moc, and reading from a MocChan will
+ create a new Moc from its textual description. See the Moc class
+ for further information.
+
+ Normally, when you use a MocChan, you should provide \texttt{"} source\texttt{"}
+ and \texttt{"} sink\texttt{"} routines which connect it to an external data store
+ by reading and writing the resulting text. These routines
+ should perform any conversions needed between external character
+ encodings and the internal ASCII encoding. If no such routines
+ are supplied, a Channel will read from standard input and write
+ to standard output.
+
+ Alternatively, a MocChan 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{AST\_MOCCHAN}{AST\_MOCCHAN}
+ }
+ \sstdiytopic{
+ Inheritance
+ }{
+ The MocChan class inherits from the Channel class.
+ }
+ \sstdiytopic{
+ Attributes
+ }{
+ In addition to those attributes common to all Channels, every
+ MocChan also has the following attributes:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{MocFormat}{MocFormat}: Whether to use JSON or string format
+
+ \sstitem
+ \htmlref{MocLineLen}{MocLineLen}: Controls output buffer length
+ }
+ }
+ \sstdiytopic{
+ Functions
+ }{
+ The MocChan class does not define any new routines beyond those
+ which are applicable to all Channels.
+ }
+}
+\sstroutine{
+ NormMap
+}{
+ Normalise coordinates using a supplied Frame
+}{
+ \sstdescription{
+ The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate
+ values using the
+ \htmlref{AST\_NORM}{AST\_NORM} routine
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+ function will replace neighbouring pairs of forward and inverse
+ NormMaps by a single \htmlref{UnitMap}{UnitMap} (so long as the Frames encapsulated by
+ the two NormMaps are equal - i.e. have the same class and the same
+ attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
+ a NormMap, the CmpMap will still cancel with its own inverse.
+ }
+ \sstconstructor{
+ \htmlref{AST\_NORMMAP}{AST\_NORMMAP}
+ }
+ \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 routines 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{AST\_NULLREGION}{AST\_NULLREGION}
+ }
+ \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 routines 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 routines may be applied to all Objects:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ANNUL}{AST\_ANNUL}: Annul a pointer to an Object
+
+ \sstitem
+ \htmlref{AST\_BEGIN}{AST\_BEGIN}: Begin a new AST context
+
+ \sstitem
+ \htmlref{AST\_CLEAR}{AST\_CLEAR}: Clear attribute values for an Object
+
+ \sstitem
+ \htmlref{AST\_CLONE}{AST\_CLONE}: Clone a pointer to an Object
+
+ \sstitem
+ \htmlref{AST\_COPY}{AST\_COPY}: Copy an Object
+
+ \sstitem
+ \htmlref{AST\_DELETE}{AST\_DELETE}: Delete an Object
+
+ \sstitem
+ \htmlref{AST\_END}{AST\_END}: End an AST context
+
+ \sstitem
+ \htmlref{AST\_ESCAPES}{AST\_ESCAPES}: Control whether graphical escape sequences are removed
+
+ \sstitem
+ \htmlref{AST\_EXEMPT}{AST\_EXEMPT}: Exempt an Object pointer from AST context handling
+
+ \sstitem
+ \htmlref{AST\_EXPORT}{AST\_EXPORT}: Export an Object pointer to an outer context
+
+ \sstitem
+ \htmlref{AST\_GET$<$X$>$}{AST\_GET$<$X$>$}: Get an attribute value for an Object
+
+ \sstitem
+ \htmlref{AST\_HASATTRIBUTE}{AST\_HASATTRIBUTE}: Test if an Object has a named attribute
+
+ \sstitem
+ \htmlref{AST\_IMPORT}{AST\_IMPORT}: Import an Object pointer to the current context
+
+ \sstitem
+ \htmlref{AST\_ISA$<$CLASS$>$}{AST\_ISA$<$CLASS$>$}: Test class membership
+
+ \sstitem
+ \htmlref{AST\_SAME}{AST\_SAME}: Do two AST pointers refer to the same Object?
+
+ \sstitem
+ \htmlref{AST\_SET}{AST\_SET}: Set attribute values for an Object
+
+ \sstitem
+ \htmlref{AST\_SET$<$X$>$}{AST\_SET$<$X$>$}: Set an attribute value for an Object
+
+ \sstitem
+ \htmlref{AST\_SHOW}{AST\_SHOW}: Display a textual representation of an Object on standard
+ output
+
+ \sstitem
+ \htmlref{AST\_TEST}{AST\_TEST}: Test if an attribute value is set for an Object
+
+ \sstitem
+ \htmlref{AST\_TUNE}{AST\_TUNE}: Set or get an integer AST tuning parameter
+
+ \sstitem
+ \htmlref{AST\_TUNEC}{AST\_TUNEC}: Set or get a character AST tuning parameter
+
+ \sstitem
+ \htmlref{AST\_VERSION}{AST\_VERSION}: 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{AST\_PCDMAP}{AST\_PCDMAP}
+ }
+ \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 routines 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{AST\_PERMMAP}{AST\_PERMMAP}
+ }
+ \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 routines 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{AST\_CURVE}{AST\_CURVE}, \htmlref{AST\_GENCURVE}{AST\_GENCURVE} and \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}). A Plot also provides facilities
+ for drawing markers or symbols (\htmlref{AST\_MARK}{AST\_MARK}), text (\htmlref{AST\_TEXT}{AST\_TEXT}) and grid
+ lines (\htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}). It is also possible to draw curvilinear axes
+ with optional coordinate grids (\htmlref{AST\_GRID}{AST\_GRID}).
+ A range of Plot attributes is available to allow precise control
+ over the appearance of graphical output produced by these
+ routines.
+
+ 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{AST\_CLIP}{AST\_CLIP}) 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{AST\_PLOT}{AST\_PLOT}
+ }
+ \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{TextGapType}{TextGapType}: Controls interpretation of TextLabGap and \htmlref{TitleGap}{TitleGap}
+
+ \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 routines applicable to all FrameSets, the
+ following routines may also be applied to all Plots:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_BBUF}{AST\_BBUF}: Begin a new graphical buffering context
+
+ \sstitem
+ \htmlref{AST\_BORDER}{AST\_BORDER}: Draw a border around valid regions of a Plot
+
+ \sstitem
+ \htmlref{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}: Returns a bounding box for previously drawn graphics
+
+ \sstitem
+ \htmlref{AST\_CLIP}{AST\_CLIP}: Set up or remove clipping for a Plot
+
+ \sstitem
+ \htmlref{AST\_CURVE}{AST\_CURVE}: Draw a geodesic curve
+
+ \sstitem
+ \htmlref{AST\_EBUF}{AST\_EBUF}: End the current graphical buffering context
+
+ \sstitem
+ \htmlref{AST\_GENCURVE}{AST\_GENCURVE}: Draw a generalized curve
+
+ \sstitem
+ \htmlref{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT}: Get the graphics context for a Plot
+
+ \sstitem
+ \htmlref{AST\_GRFPOP}{AST\_GRFPOP}: Retrieve previously saved graphics functions
+
+ \sstitem
+ \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH}: Save the current graphics functions
+
+ \sstitem
+ \htmlref{AST\_GRFSET}{AST\_GRFSET}: Register a graphics routine for use by the Plot class
+
+ \sstitem
+ \htmlref{AST\_GRID}{AST\_GRID}: Draw a set of labelled coordinate axes
+
+ \sstitem
+ \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}: Draw a grid line (or axis) for a Plot
+
+ \sstitem
+ \htmlref{AST\_MARK}{AST\_MARK}: Draw a set of markers for a Plot
+
+ \sstitem
+ \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}: Draw a series of connected geodesic curves
+
+ \sstitem
+ AST\_REGIONOUTLINE: Draw the outline of an AST \htmlref{Region}{Region}
+
+ \sstitem
+ \htmlref{AST\_TEXT}{AST\_TEXT}: 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 AST\_GRID
+
+ \sstitem
+ Axis1: Axis line drawn through tick marks on axis 1 using AST\_GRID
+
+ \sstitem
+ Axis2: Axis line drawn through tick marks on axis 2 using AST\_GRID
+
+ \sstitem
+ Border: The Plot border drawn using AST\_BORDER, AST\_GRID or AST\_REGIONOUTLINE
+
+ \sstitem
+ Curves: Geodesic curves drawn using AST\_CURVE, AST\_GENCURVE or AST\_POLYCURVE
+
+ \sstitem
+ Grid: Grid lines drawn using AST\_GRIDLINE or AST\_GRID
+
+ \sstitem
+ Grid1: Grid lines which cross axis 1, drawn using AST\_GRIDLINE or AST\_GRID
+
+ \sstitem
+ Grid2: Grid lines which cross axis 2, drawn using AST\_GRIDLINE or AST\_GRID
+
+ \sstitem
+ Markers: Graphical markers (symbols) drawn using AST\_MARK
+
+ \sstitem
+ NumLab: Numerical axis labels drawn using AST\_GRID
+
+ \sstitem
+ NumLab1: Numerical labels for axis 1 drawn using AST\_GRID
+
+ \sstitem
+ NumLab2: Numerical labels for axis 2 drawn using AST\_GRID
+
+ \sstitem
+ Strings: Text strings drawn using AST\_TEXT
+
+ \sstitem
+ TextLab: Descriptive axis labels drawn using AST\_GRID
+
+ \sstitem
+ TextLab1: Descriptive label for axis 1 drawn using AST\_GRID
+
+ \sstitem
+ TextLab2: Descriptive label for axis 2 drawn using AST\_GRID
+
+ \sstitem
+ Ticks: Tick marks (both major and minor) drawn using AST\_GRID
+
+ \sstitem
+ Ticks1: Tick marks (both major and minor) for axis 1 drawn using AST\_GRID
+
+ \sstitem
+ Ticks2: Tick marks (both major and minor) for axis 2 drawn using AST\_GRID
+
+ \sstitem
+ \htmlref{Title}{Title}: The Plot title drawn using AST\_GRID
+ }
+ }
+}
+\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
+ astClip function.
+ \htmlref{AST\_CLIP}{AST\_CLIP} routine.
+ Nor does it support the specification of graphics primitive functions
+ at run-time using the
+ \htmlref{AST\_GRFSET}{AST\_GRFSET}, \htmlref{AST\_GRFPOP}{AST\_GRFPOP}, \htmlref{AST\_GRFPUSH}{AST\_GRFPUSH}, and \htmlref{AST\_GETGRFCONTEXT}{AST\_GETGRFCONTEXT} routines.
+ }
+ \sstconstructor{
+ \htmlref{AST\_PLOT3D}{AST\_PLOT3D}
+ }
+ \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 routines 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{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}, AST\_CLIP, \htmlref{AST\_CURVE}{AST\_CURVE}, \htmlref{AST\_GENCURVE}{AST\_GENCURVE},
+ AST\_GETGRFCONTEXT, AST\_GRFPOP, AST\_GRFPUSH, AST\_GRFSET,
+ \htmlref{AST\_GRIDLINE}{AST\_GRIDLINE}, \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}.
+ }
+ }
+}
+\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{AST\_POINTLIST}{AST\_POINTLIST}
+ }
+ \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 routines 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, the default behaviour is to use
+ an iterative method to evaluate the inverse based only on the forward
+ transformation (see attribute \htmlref{IterInverse}{IterInverse}).
+ }
+ \sstconstructor{
+ \htmlref{AST\_POLYMAP}{AST\_POLYMAP}
+ }
+ \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 routines applicable to all Objects, the
+ following routines may also be applied to all Mappings:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_POLYCOEFFS}{AST\_POLYCOEFFS}: Retrieve the coefficients of a PolyMap transformation
+
+ \sstitem
+ \htmlref{AST\_POLYTRAN}{AST\_POLYTRAN}: 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{AST\_POLYGON}{AST\_POLYGON}
+ }
+ \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 routines applicable to all Regions, the
+ following routines may also be applied to all Polygons:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_DOWNSIZE}{AST\_DOWNSIZE}: Reduce the number of vertices in a Polygon.
+
+ \sstitem
+ \htmlref{AST\_CONVEX$<$X$>$}{AST\_CONVEX$<$X$>$}: Create a Polygon giving the convex hull of a pixel array
+
+ \sstitem
+ \htmlref{AST\_OUTLINE$<$X$>$}{AST\_OUTLINE$<$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{AST\_PRISM}{AST\_PRISM}
+ }
+ \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 routines 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{AST\_RATEMAP}{AST\_RATEMAP}
+ }
+ \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 routines 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{AST\_FORMAT}{AST\_FORMAT} routine
+ 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
+ AST\_TRAN$<$X$>$ routines
+ 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{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS}
+ 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{AST\_SIMPLIFY}{AST\_SIMPLIFY} routine
+ 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 routines applicable to all Frames, the
+ following routines may also be applied to all Regions:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_GETREGIONBOUNDS}{AST\_GETREGIONBOUNDS}: Get the bounds of a box containing a Region
+
+ \sstitem
+ \htmlref{AST\_GETREGIONFRAME}{AST\_GETREGIONFRAME}: Get a copy of the Frame represent by a Region
+
+ \sstitem
+ \htmlref{AST\_GETREGIONFRAMESET}{AST\_GETREGIONFRAMESET}: Get a copy of the Frameset encapsulated by a Region
+
+ \sstitem
+ \htmlref{AST\_GETREGIONMESH}{AST\_GETREGIONMESH}: Get a mesh of points covering a Region
+
+ \sstitem
+ \htmlref{AST\_GETREGIONPOINTS}{AST\_GETREGIONPOINTS}: Get the positions that define a Region
+
+ \sstitem
+ AST\_GETREGIONDISC: Get the bounds of disc containing a Region
+
+ \sstitem
+ \htmlref{AST\_GETUNC}{AST\_GETUNC}: Obtain uncertainty information from a Region
+
+ \sstitem
+ \htmlref{AST\_MAPREGION}{AST\_MAPREGION}: Transform a Region into a new coordinate system
+
+ \sstitem
+ \htmlref{AST\_NEGATE}{AST\_NEGATE}: Toggle the value of the Negated attribute
+
+ \sstitem
+ \htmlref{AST\_OVERLAP}{AST\_OVERLAP}: Determines the nature of the overlap between two Regions
+
+ \sstitem
+ \htmlref{AST\_MASK$<$X$>$}{AST\_MASK$<$X$>$}: Mask a region of a data grid
+
+ \sstitem
+ \htmlref{AST\_SETUNC}{AST\_SETUNC}: Associate a new uncertainty with a Region
+
+ \sstitem
+ \htmlref{AST\_SHOWMESH}{AST\_SHOWMESH}: 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+
+ In practice, SelectorMaps are often used in conjunction with SwitchMaps.
+ }
+ \sstconstructor{
+ \htmlref{AST\_SELECTORMAP}{AST\_SELECTORMAP}
+ }
+ \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 routines 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{AST\_SHIFTMAP}{AST\_SHIFTMAP}
+ }
+ \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 routines 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{AST\_WRITE}{AST\_WRITE}).
+ }
+ \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{AST\_FORMAT}{AST\_FORMAT}.
+ 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{AST\_SKYFRAME}{AST\_SKYFRAME}
+ }
+ \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
+ routines
+ applicable to all Frames, the following
+ routines
+ may also be applied to all SkyFrames:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_SKYOFFSETMAP}{AST\_SKYOFFSETMAP}: 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{AST\_SLAADD}{AST\_SLAADD}
+ routine, 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 AST\_SLAADD routine.
+ }
+ \sstconstructor{
+ \htmlref{AST\_SLAMAP}{AST\_SLAMAP} (also see AST\_SLAADD)
+ }
+ \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 routines applicable to all Mappings, the
+ following routine may also be applied to all SlaMaps:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_SLAADD}{AST\_SLAADD}: 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{AST\_SPECFLUXFRAME}{AST\_SPECFLUXFRAME}
+ }
+ \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 routines 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{AST\_SPECFRAME}{AST\_SPECFRAME}
+ }
+ \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 routines applicable to all Frames, the
+ following routines may also be applied to all SpecFrames:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_SETREFPOS}{AST\_SETREFPOS}: Set reference position in any celestial system
+
+ \sstitem
+ \htmlref{AST\_GETREFPOS}{AST\_GETREFPOS}: 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{AST\_SPECADD}{AST\_SPECADD}
+ routine, 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 AST\_SPECADD routine.
+ }
+ \sstconstructor{
+ \htmlref{AST\_SPECMAP}{AST\_SPECMAP} (also see AST\_SPECADD)
+ }
+ \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 routines applicable to all Mappings, the
+ following routine may also be applied to all SpecMaps:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_SPECADD}{AST\_SPECADD}: 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{AST\_SPHMAP}{AST\_SPHMAP}
+ }
+ \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 routines 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{
+ AST\_STC
+ }
+ \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 routines applicable to all Regions, the
+ following routines may also be applied to all Stc\texttt{'} s:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_GETSTCREGION}{AST\_GETSTCREGION}: Get a pointer to the encapsulated Region
+
+ \sstitem
+ \htmlref{AST\_GETSTCCOORD}{AST\_GETSTCCOORD}: Get information about an AstroCoords element
+
+ \sstitem
+ \htmlref{AST\_GETSTCNCOORD}{AST\_GETSTCNCOORD}: 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{AST\_STCCATALOGENTRYLOCATION}{AST\_STCCATALOGENTRYLOCATION}
+ }
+ \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 routines 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{AST\_STCOBSDATALOCATION}{AST\_STCOBSDATALOCATION}
+ }
+ \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 routines 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{AST\_STCRESOURCEPROFILE}{AST\_STCRESOURCEPROFILE}
+ }
+ \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 routines 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{AST\_STCSEARCHLOCATION}{AST\_STCSEARCHLOCATION}
+ }
+ \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 routines 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{AST\_WRITE}{AST\_WRITE}) 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{AST\_READ}{AST\_READ},
+ 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
+ AST\_READ.
+
+ When an STC-S description is created from an AST Object using
+ AST\_WRITE,
+ 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
+ AST\_WRITE
+ 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
+ AST\_READ and AST\_WRITE
+ functions work together so that any Object returned by
+ AST\_READ can immediately be re-written using AST\_WRITE.
+
+ Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"}
+ and \texttt{"} sink\texttt{"} routines which connect it to an external data store
+ by reading and writing the resulting text. These routines
+ should perform any conversions needed between external character
+ encodings and the internal ASCII encoding. If no such routines
+ 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{AST\_STCSCHAN}{AST\_STCSCHAN}
+ }
+ \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 routines 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+ }
+ \sstconstructor{
+ \htmlref{AST\_SWITCHMAP}{AST\_SWITCHMAP}
+ }
+ \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 routines 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
+ AST\_MAPGET... and AST\_MAPPUT...
+ 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{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}
+ 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{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}
+ 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{AST\_TABLE}{AST\_TABLE}
+ }
+ \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 routines applicable to all KeyMaps, the
+ following routines may also be applied to all Tables:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_ADDCOLUMN}{AST\_ADDCOLUMN}: Add a new column definition to a Table
+
+ \sstitem
+ \htmlref{AST\_ADDPARAMETER}{AST\_ADDPARAMETER}: Add a new global parameter definition to a Table
+
+ \sstitem
+ \htmlref{AST\_COLUMNNAME}{AST\_COLUMNNAME}: Return the name of the column with a given index
+
+ \sstitem
+ \htmlref{AST\_COLUMNSHAPE}{AST\_COLUMNSHAPE}: Return the shape of the values in a named column
+
+ \sstitem
+ \htmlref{AST\_HASCOLUMN}{AST\_HASCOLUMN}: Checks if a column exists in a Table
+
+ \sstitem
+ \htmlref{AST\_HASPARAMETER}{AST\_HASPARAMETER}: Checks if a global parameter exists in a Table
+
+ \sstitem
+ \htmlref{AST\_PARAMETERNAME}{AST\_PARAMETERNAME}: Return the name of the parameter with a given index
+
+ \sstitem
+ \htmlref{AST\_PURGEROWS}{AST\_PURGEROWS}: Remove all empty rows from a Table
+
+ \sstitem
+ \htmlref{AST\_REMOVECOLUMN}{AST\_REMOVECOLUMN}: Remove a column from a Table
+
+ \sstitem
+ \htmlref{AST\_REMOVEPARAMETER}{AST\_REMOVEPARAMETER}: Remove a global parameter from a Table
+
+ \sstitem
+ \htmlref{AST\_REMOVEROW}{AST\_REMOVEROW}: 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{AST\_TIMEFRAME}{AST\_TIMEFRAME}
+ }
+ \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 routines applicable to all Frames, the
+ following routines may also be applied to all TimeFrames:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_CURRENTTIME}{AST\_CURRENTTIME}: 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{AST\_TIMEADD}{AST\_TIMEADD}
+ routine, 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 AST\_TIMEADD routine.
+ }
+ \sstconstructor{
+ \htmlref{AST\_TIMEMAP}{AST\_TIMEMAP} (also see AST\_TIMEADD)
+ }
+ \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 routines applicable to all Mappings, the
+ following routine may also be applied to all TimeMaps:
+
+ \sstitemlist{
+
+ \sstitem
+ \htmlref{AST\_TIMEADD}{AST\_TIMEADD}: 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{AST\_TRANMAP}{AST\_TRANMAP}
+ }
+ \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 routines 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
+ routine) 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{AST\_UNITMAP}{AST\_UNITMAP}
+ }
+ \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 routines 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.
+ If the norm is 0, then the output of the forward transformation is AST\_\_BAD
+ for each component of the unit vector and 0 for the norm (the final value).
+
+ 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.
+ If the provided norm is 0 then the other input values are ignored,
+ and the output vector is the centre.
+
+ Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre;
+ the norm is 5, so the output is [0.8, 0.6, 5].
+
+ 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{AST\_UNITNORMMAP}{AST\_UNITNORMMAP}
+ }
+ \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 routines 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{AST\_WCSMAP}{AST\_WCSMAP}
+ }
+ \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 routines 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{AST\_WINMAP}{AST\_WINMAP}
+ }
+ \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 routines 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{AST\_WRITE}{AST\_WRITE}) 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{"} routines which connect it to an external data store
+ by reading and writing the resulting XML text. These routines
+ should perform any conversions needed between external character
+ encodings and the internal ASCII encoding. If no such routines
+ 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{AST\_XMLCHAN}{AST\_XMLCHAN}
+ }
+ \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 routines 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{AST\_ZOOMMAP}{AST\_ZOOMMAP}
+ }
+ \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 routines 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{
+ f77 program.f -L/star/lib `ast\_link [switches]` -o program
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ f77 display.f -L/star/lib `ast\_link -pgplot` -o display
+ }{
+ Compiles and links a Fortran program called ``display\texttt{'} \texttt{'} which uses
+ the standard version of PGPLOT for graphical output.
+ }
+ \sstexamplesubsection{
+ f77 plotit.f -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit
+ }{
+ Compiles and links a Fortran 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{
+ f77 plotit.f -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit
+ }{
+ Compiles and links a Fortran 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.f -L/star/lib `ast\_link\_adam [switches]`
+ }
+ \sstexamples{
+ \sstexamplesubsection{
+ alink display.f -L/star/lib `ast\_link\_adam -pgplot`
+ }{
+ Compiles and links an ADAM Fortran program called ``display\texttt{'} \texttt{'} which
+ uses the standard version of PGPLOT for graphical output.
+ }
+ \sstexamplesubsection{
+ alink plotit.f -L. -L/star/lib `ast\_link\_adam -grf` -lgrf
+ }{
+ Compiles and links an ADAM Fortran 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{
+ alink plotit.f -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf
+ }{
+ Compiles and links an ADAM Fortran 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
+ ``-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
+
+
+\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{AST\_READ}{AST\_READ}
+function) from a FitsChan containing a header which conforms to these
+conventions. However, only those FrameSets which are compatible with the
+FITS-WCS model can be \emph{written} to a FitsChan using the
+\htmlref{AST\_WRITE}{AST\_WRITE}
+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 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{AST\_UNFORMAT}{AST\_UNFORMAT} 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{AST\_FORMAT}{AST\_FORMAT}. 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 routine \htmlref{AST\_MAPBOX}{AST\_MAPBOX} 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 routine
+(\emph{e.g.}\ written in Fortran) 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+
+\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 A problem has been fixed which could result when using \htmlref{AST\_READ}{AST\_READ}
+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 AST\_SIMPLIFY.
+
+\item A bug has been fixed which could cause the AST\_\_BAD parameter
+to have an incorrect value on some platforms.
+
+\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 routine, \htmlref{AST\_POLYCURVE}{AST\_POLYCURVE}, has been introduced to allow more
+efficient plotting of multiple geodesic curves
+(\secref{ss:plottinggeodesics}).
+
+\item A new set of functions, \htmlref{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$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 routine \htmlref{AST\_MAPBOX}{AST\_MAPBOX} 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{AST\_FINDFITS}{AST\_FINDFITS} now ignores trailing spaces in its keyword template.
+
+\item \htmlref{AST\_PUTFITS}{AST\_PUTFITS} 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{AST\_SIMPLIFY}{AST\_SIMPLIFY}.
+
+\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{AST\_CONVERT}{AST\_CONVERT}
+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{AST\_RESAMPLE$<$X$>$}{AST\_RESAMPLE$<$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 astRead).
+%c-
+%f+
+%file (using \htmlref{AST\_READ}{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 Fortran.
+
+\item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation routines
+used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{AST\_INTRAREG}{AST\_INTRAREG}) now
+require a THIS pointer as their first argument. \textbf{Existing
+implementations will not continue to work correctly with this version
+of AST unless this argument 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 routines 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 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 \htmlref{AST\_RESAMPLE$<$X$>$}{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{AST\_ANGLE}{AST\_ANGLE}
+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{AST\_OFFSET2}{AST\_OFFSET2}
+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{AST\_AXDISTANCE}{AST\_AXDISTANCE}
+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{AST\_AXOFFSET}{AST\_AXOFFSET}
+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{AST\_GENCURVE}{AST\_GENCURVE}
+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{AST\_GRFSET}{AST\_GRFSET}
+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{AST\_GRFPUSH}{AST\_GRFPUSH} and \htmlref{AST\_GRFPOP}{AST\_GRFPOP}
+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
+routines (\htmlref{AST\_ANGLE}{AST\_ANGLE}, \htmlref{AST\_AXANGLE}{AST\_AXANGLE}, \htmlref{AST\_RESOLVE}{AST\_RESOLVE}, \htmlref{AST\_OFFSET2}{AST\_OFFSET2}, \htmlref{AST\_AXOFFSET}{AST\_AXOFFSET},
+\htmlref{AST\_AXDISTANCE}{AST\_AXDISTANCE})
+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
+AST\_BEAR routine has been replaced by AST\_AXANGLE.
+
+\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 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
+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
+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{AST\_READ}{AST\_READ}
+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{AST\_SET}{AST\_SET},
+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{AST\_BOUNDINGBOX}{AST\_BOUNDINGBOX}
+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
+AST\_BOUNDINGBOX
+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{AST\_WRITE}{AST\_WRITE} 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 AST\_WRITE
+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{AST\_GRID}{AST\_GRID} routine 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{AST\_SHOW}{AST\_SHOW} routine.
+\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{AST\_WRITE}{AST\_WRITE} routine
+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
+AST\_WRITE routine
+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
+AST\_FINDRAME or \htmlref{AST\_CONVERT}{AST\_CONVERT}
+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{AST\_SETACTIVEUNIT}{AST\_SETACTIVEUNIT}
+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{AST\_FINDFRAME}{AST\_FINDFRAME} and AST\_CONVERT.
+
+
+\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{AST\_VERSION}{AST\_VERSION})
+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{AST\_RATE}{AST\_RATE}
+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{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+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
+routine \htmlref{AST\_PUTCARDS}{AST\_PUTCARDS}
+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
+AST\_PUTCARDS routine.
+
+\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 astEscapes has been added which is used
+to control and enquire whether astGetC and 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.
+
+\item The names of the installed AST include files have been changed to
+upper case.
+
+\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{AST\_LINEARAPPROX}{AST\_LINEARAPPROX})
+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{AST\_RATE}{AST\_RATE}
+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
+(AST\_SETFITS<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\_PAR. These specify kernels for AST\_RESAMPLE and AST\_REBIN
+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
+routine \htmlref{AST\_MAPSPLIT}{AST\_MAPSPLIT}
+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{AST\_RETAINFITS}{AST\_RETAINFITS}
+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{AST\_TUNE}{AST\_TUNE}
+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{AST\_TRANGRID}{AST\_TRANGRID}
+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{AST\_CONVERT}{AST\_CONVERT}
+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
+AST\_GETFITSS
+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{AST\_FINDFRAME}{AST\_FINDFRAME}
+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
+AST\_FINDFRAME,
+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
+AST\_FINDFRAME.
+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{AST\_CONVERT}{AST\_CONVERT}.
+
+\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
+AST\_CONVERT.
+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{AST\_WRITE}{AST\_WRITE}
+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{AST\_PURGEWCS}{AST\_PURGEWCS}
+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{AST\_GRFSET}{AST\_GRFSET} routine.
+\item Functions registered with the Plot class using
+AST\_GRFSET
+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
+AST\_GRFSET
+TO BE MODIFIED TO INCLUDE THE NEW PARAMETER.
+\item The
+AST\_REBINSEQ routines
+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
+AST\_REBINSEQ.
+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
+routine \htmlref{AST\_SHOWMESH}{AST\_SHOWMESH}
+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 astLock and 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{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 Improvements have been made to the way that Prisms are simplified
+when
+\htmlref{AST\_SIMPLIFY}{AST\_SIMPLIFY}
+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,
+AST\_POINTS,
+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
+AST\_XMLWARNINGS
+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{AST\_WARNINGS}{AST\_WARNINGS}
+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
+AST\_WARNINGS
+function.
+
+\item A new function called
+AST\_INTERCEPT
+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 \htmlref{Object}{Object} was
+supplied as an argument to a constructor.
+
+\item The
+\htmlref{AST\_PICKAXES}{AST\_PICKAXES}
+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{AST\_TESTFITS}{AST\_TESTFITS}
+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
+AST\_TESTFITS
+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{AST\_SETFITSCM}{AST\_SETFITSCM}
+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{AST\_REMOVEREGIONS}{AST\_REMOVEREGIONS}
+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{AST\_DOWNSIZE}{AST\_DOWNSIZE}
+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
+AST\_OUTLINE
+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
+AST\_MAPGETELEM<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
+AST\_MAPGET...
+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{AST\_FINDFRAME}{AST\_FINDFRAME} and \htmlref{AST\_CONVERT}{AST\_CONVERT}
+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 Added method
+\htmlref{AST\_MATCHAXES}{AST\_MATCHAXES}
+to the Frame class. This method allows corresponding axes within two
+Frames to be identified.
+
+\item The
+\htmlref{AST\_ADDFRAME}{AST\_ADDFRAME}
+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 \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A
+new method called
+\htmlref{AST\_MAPPUTU}{AST\_MAPPUTU}
+will store an entry with undefined value in a keymap. Methods that
+retrieve values from a KeyMap
+(AST\_MAPGET0<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{AST\_MAPCOPY}{AST\_MAPCOPY}
+that copies entries from one KeyMap to another KeyMap.
+
+\item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If
+.TRUE.,
+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
+.FALSE.
+
+\item The \htmlref{Object}{Object} class has a new method called astHasAttribute/\htmlref{AST\_HASATTRIBUTE}{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
+AST\_REBIN(SEQ)
+methods that could cause flux to be lost from the edges of the supplied array.
+
+\item A bug has been fixed in the
+AST\_REBIN(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{AST\_QUADAPPROX}{AST\_QUADAPPROX},
+produces a quadratic least-squares fit to a 2D Mapping.
+
+\item A new Mapping method,
+\htmlref{AST\_SKYOFFSETMAP}{AST\_SKYOFFSETMAP},
+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{AST\_WRITE}{AST\_WRITE}.
+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
+AST\_MAPPUTELEM<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{AST\_SET}{AST\_SET} routine
+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 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{AST\_MAPKEY}{AST\_MAPKEY}
+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.
+INTEGER*2)
+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
+BYTE.
+
+\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
+AST\_MAPPUTELEM<X>
+functions has been fixed.
+
+\item A new method called
+\htmlref{AST\_MAPRENAME}{AST\_MAPRENAME}
+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{AST\_WRITE}{AST\_WRITE}
+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
+AST\_WRITE or \htmlref{AST\_READ}{AST\_READ}
+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 routines \htmlref{AST\_BBUF}{AST\_BBUF} and \htmlref{AST\_EBUF}{AST\_EBUF}
+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
+routines AST\_BBUF and AST\_EBUF
+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{AST\_GETREGIONMESH}{AST\_GETREGIONMESH}
+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{AST\_FINDFRAME}{AST\_FINDFRAME}
+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{AST\_POLYTRAN}{AST\_POLYTRAN}
+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 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{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{AST\_WRITEFITS}{AST\_WRITEFITS}
+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
+AST\_GETFITS<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{AST\_READFITS}{AST\_READFITS}
+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 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
+routine \htmlref{AST\_TUNEC}{AST\_TUNEC}.
+
+\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
+AST\_REBINSEQ<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{AST\_ADDFRAME}{AST\_ADDFRAME} routine
+that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet}
+when the AST\_\_ALLFRAMES flag is supplied for the
+IFRAME argument.
+
+\item The
+\htmlref{AST\_RATE}{AST\_RATE} function
+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{AST\_MAPDEFINED}{AST\_MAPDEFINED}
+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 AST\_REBINSEQ<X> family of routines has
+been changed in order to allow a greater number of pixels to be pasted
+into the output array. The NUSED parameter is now an INTEGER*8 variable,
+instead of an INTEGER. 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 astSimplify function.
+f \htmlref{AST\_SIMPLIFY}{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,
+AST\_CONVEX,
+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 astWrite
+ can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}.
+\item Supported added for FITS XPH (polar HEALPIX) projection.
+\item The AST\_REBIN and AST\_REBINSEQ family of functions now include support
+ for arrays with \_BYTE (byte) and and \_UBYTE (unsigned byte) data types.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.0.2}
+The changes that occurred in the AST library between versions V8.0.1 and
+V8.0.2 only affect the C interface. The Fortran interface remains the
+same as V8.0.1.
+
+\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
+AST\_REBIN, AST\_REBINSEQ, AST\_RESAMPLE and \htmlref{AST\_TRANGRID}{AST\_TRANGRID}.
+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 Trailing spaces supplied within attribute setting strings are now ignored.
+\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{AST\_ADDFRAME}{AST\_ADDFRAME} method has been changed slightly. Previously, AST\_ADDFRAME
+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
+AST\_REGIONOUTLINE
+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
+routine ``\htmlref{AST\_WARNINGS}{AST\_WARNINGS}''.
+
+\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{Changes Introduced in V8.3}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.2.0 and V8.3.0:
+
+\begin{enumerate}
+
+\item A new method called \htmlref{AST\_AXNORM}{AST\_AXNORM}
+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 Fortran include file AST\_PAR that caused constants
+related to $\pi$ to be defined as single rather than double precision.
+
+\item A bug has been fixed in the astGetRegionBounds method that could
+cause the wrong bounds to be returned for regions spanning a longitude =
+zero singularity.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.4}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.3.0 and V8.4.0:
+
+\begin{enumerate}
+
+\item The PAL library files included in the AST distribution have been updated
+to PAL version 0.9.7.
+
+\item Multiple identical NormMaps in series will now be simplified to a
+single \htmlref{NormMap}{NormMap}.
+
+\item A NormMap that encapsulates a basic \htmlref{Frame}{Frame} will now be simplified to a
+\htmlref{UnitMap}{UnitMap}.
+
+\item The \htmlref{AST\_TIMEADD}{AST\_TIMEADD}
+method of the \htmlref{TimeMap}{TimeMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item The \htmlref{AST\_SLAADD}{AST\_SLAADD}
+method of the \htmlref{SlaMap}{SlaMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item The \htmlref{AST\_SPECADD}{AST\_SPECADD}
+method of the \htmlref{SpecMap}{SpecMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item Multiple identical NormMaps in series will now be simplified to a
+single NormMap.
+
+\item A NormMap that encapsulates a basic Frame will now be simplified to a
+UnitMap.
+
+\item If the
+\htmlref{AST\_MAPREGION}{AST\_MAPREGION}
+method is used to map a \htmlref{Region}{Region} into a new Frame that has fewer axes than
+the original Region, and if the inverse transformation of the supplied
+\htmlref{Mapping}{Mapping} does not specify a value for the missing axes, then those axes
+are removed entirely from the Region. Previously they were retained, but
+automatically supplied with bad values. This affects the number of mesh
+points per axes for such Regions, and so affects the accuracy of overlap
+determination.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.5}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.4.0 and V8.5.1:
+
+\begin{enumerate}
+
+\item - A new class of \htmlref{Mapping}{Mapping} called \htmlref{ChebyMap}{ChebyMap} has been added. This is a
+Mapping that implements Chebyshev polynomial transformations.
+
+\item A bug has been fixed in the \htmlref{PolyMap}{PolyMap} class that caused incorrect values
+to be returned for the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes if the PolyMap
+has been inverted.
+
+\item The \htmlref{KeyMap}{KeyMap} class has a new method called
+\htmlref{AST\_MAPGETC}{AST\_MAPGETC}
+which returns a named entry as a single string. If the entry is a vector
+the returned string is a comma-separated list of its elements, enclosed
+in parentheses.
+
+\item If the
+routine that delivers error messages to the user (AST\_PUTERR)
+is re-implemented, the new version can now be registered at run-time using
+the new
+\htmlref{AST\_SETPUTERR}{AST\_SETPUTERR} routine.
+Previously, the new version needed to be linked into the application at
+build time.
+
+
+\item The \htmlref{Frame}{Frame} class now has a new attribute caled DTAI, which can be used
+to specify the number of leap seconds at the moment represented by the
+Frame's \htmlref{Epoch}{Epoch} attribute. By default, the internal look-up table of leap
+seconds contained within AST is used. The DTAI attribute allows old
+versions of AST, which may not include the most recent leap seconds, to
+be used with new data.
+
+\item The \htmlref{TimeMap}{TimeMap} class has been changed so that some conversions now require
+a ``\htmlref{Dtai}{Dtai}'' value (\emph{i.e.} the number of leap seconds) to be supplied by the
+caller. If AST\_\_BAD is supplied for ``Dtai'', the internal look-up table of
+leap seconds contained withn AST will be used. The conversions affected
+are those between TAI and UTC, and those between TT and TDB.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.6.2}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.5.1 and V8.6.2:
+
+\begin{enumerate}
+
+\item The astRebinSeq<X> functions accepts a new flag, AST\_\_PARWGT, which
+allows the initial weight to be given for the data being pasted into the
+output arrays (the initial weight to use should be include in the "params"
+array). This initial weight defaults to 1.0 if the AST\_\_PARWGT flag is not
+given.
+
+\item The behaviour of the astLinearApprox method of the \htmlref{Mapping}{Mapping} class has
+been changed in cases where the Mapping being approximated generates bad
+(AST\_\_BAD) values for one or more of its outputs. Previously, any such
+Mapping would be deemed non-linear and no fit would be returned. Now, a
+fit is returned, provided the other outputs of the Mapping are linear,
+but the fit contains AST\_\_BAD values for the coefficients describing the
+bad Mapping output.
+
+\item The astWrite method of the \htmlref{FitsChan}{FitsChan} class can now create FITS-WCS headers
+that include keyords describing focal plane distortion using the
+conventions of the Spitzer SIP scheme. This is however only possible if
+the \htmlref{SipOK}{SipOK} attribute of the FitsChan is set to a non-zero value (which is
+the default), and the \htmlref{FrameSet}{FrameSet} being written out contains an appropriate
+\htmlref{PolyMap}{PolyMap} that conforms to the requirements of the SIP convention.
+
+\item A new function call astCreatedAt is now available that returns the
+function name, file path and line number at which an AST object was first
+created. Note, there is no Fortran equivalent to this new C function.
+
+\item The number of digits used to format floating point values has been
+increased in order to avoid loss of precision when converting from binary
+to string and back to binary. This could cause very small changes in numerical
+values returned by AST functions.
+
+\item If a FrameSet is supplied as the ``map'' argument to astAddFrame, it now
+extracts and stores the base->current Mapping from the supplied FrameSet.
+Previously, the entire FrameSet was stored as the Mapping.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.6.3}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.6.2 and V8.6.3:
+
+\begin{enumerate}
+
+\item Small memory leaks in \htmlref{Region}{Region} and \htmlref{FitsChan}{FitsChan} classes have been fixed.
+
+\item A bug that could cause an internal buffer overrun within the FitsChan
+class when writing out a FITS-WCS spectral axis with the ``-LOG'' algorithm
+has been fixed.
+
+\item The test that a \htmlref{Mapping}{Mapping} conforms to the requirements of the SIP FITS
+distortion scheme has been improved.
+
+\item The astRebinSeq method of the Mapping class can now use a different
+weight when pasting each separate input data array into the output mosaic.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.7.0}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.6.3 and V8.7.0:
+
+\begin{enumerate}
+
+\item The \htmlref{Region}{Region} class has a new method called astGetRegionDisc, which
+returns the centre and radius of a disc that just encloses a
+2-dimensional Region.
+
+\item A new subclass of Region called ``\htmlref{Moc}{Moc}'' has been added. A Moc
+describes an arbitrary region of the sky in the form of a set of HEALPix
+cells.
+
+\item The \htmlref{Bounded}{Bounded} attribute defined by the Region class is now always
+non-zero for Regions defined within a \htmlref{SkyFrame}{SkyFrame}, regardless of whether the
+Region has been negated. Previously, it was non-zero only if the Region
+had not been negated. Note, this change only affects Regions defined
+within SkyFrames.
+
+\end{enumerate}
+
+\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
+Introduced in V8.7.1}
+The following describes the most significant changes which have
+occurred in the AST library between versions V8.7.0 and V8.7.1 (the
+current version):
+
+\begin{enumerate}
+
+\item The \htmlref{Moc}{Moc} class now supports version 1.1 of the the MOC recommendation.
+This includes new support for string and JSON encoded MOCs. See methods
+astGetMocString and astAddMocString in the Moc class, and also the new
+\htmlref{MocChan}{MocChan} class.
+
+\item The \htmlref{FitsChan}{FitsChan} class will now read FITS-WCS headers that have
+alternate axis descriptions but no primary axis descriptions.
+
+\end{enumerate}
+
+Programs which are statically linked will need to be re-linked in
+order to take advantage of these new facilities.
+
+\end{document}