diff options
Diffstat (limited to 'ast/sun211.tex')
-rw-r--r-- | ast/sun211.tex | 52853 |
1 files changed, 52853 insertions, 0 deletions
diff --git a/ast/sun211.tex b/ast/sun211.tex new file mode 100644 index 0000000..bae94eb --- /dev/null +++ b/ast/sun211.tex @@ -0,0 +1,52853 @@ +\documentclass[twoside,11pt]{starlink} + +% ? Specify used packages +% ? End of specify used packages + +% ----------------------------------------------------------------------------- +% ? Document identification +% Fixed part +\stardoccategory {Starlink User Note} +\stardocinitials {SUN} +\stardocsource {sun\stardocnumber} + +% Variable part - replace [xxx] as appropriate. +\stardocnumber {211.27} +\stardocauthors {R.F. Warren-Smith \& D.S. Berry} +\stardocdate {26th October 2016} +\stardoctitle {AST\linebreak% + A Library for Handling\linebreak% + World Coordinate Systems\linebreak% + in Astronomy} +\stardoccopyright {Copyright (C) 2014 Science \& Technology Facilities Council} +\stardocversion {V8.3} +\stardocmanual {Programmer's Guide\\(C Version)} +\startitlepic{ + \includegraphics[width=0.25\textwidth]{sun211_figures/fronta}~~~~~\hfill + \includegraphics[width=0.25\textwidth]{sun211_figures/frontb}~~~~~\hfill + \includegraphics[width=0.25\textwidth]{sun211_figures/frontc} +} +\stardocabstract { +The AST library provides a comprehensive range of facilities for +attaching world coordinate systems to astronomical data, for +retrieving and interpreting that information in a variety of formats, +including FITS-WCS, and for generating graphical output based on it. + +This programmer's manual should be of interest to anyone writing +astronomical applications which need to manipulate coordinate system +data, especially celestial or spectral coordinate systems. AST is portable and +environment-independent. +} +% ? End of document identification +% ----------------------------------------------------------------------------- +% ? Document specific \providecommand or \newenvironment commands. + +\providecommand{\appref}[1]{Appendix~\ref{#1}} +\providecommand{\secref}[1]{\S\ref{#1}} + +\providecommand{\fitskey}[3]{{#1}&{#2}&{#3}\\} + +% Use {\tt ... } as \texttt{...} does not work if there are new lines in #1 +\providecommand{\sstsynopsis}[1]{\sstdiytopic{Synopsis}{\tt #1}} + +% Format the constructor section. +\providecommand{\sstconstructor}[1]{\sstdiytopic{Constructor Function}{#1}} + +% ? End of document specific commands +% ----------------------------------------------------------------------------- +% \htmlref{Title}{Title} Page. +% =========== +\begin{document} +\scfrontmatter + +\begin{center} +\emph{This is the C version of this document.\\ + For the Fortran version, please see \xref{SUN/210}{sun210}{}.} +\end{center} + +% Main text of document. +\vspace{7mm} +\section{Introduction} + +Welcome to the AST library. If you are writing software for astronomy +and need to use celestial coordinates (\emph{e.g.}\ RA and Dec), spectral +coordinates (\emph{e.g.}\ wavelength, frequency, \emph{etc.}), or +other coordinate system information, then this library should be of +interest. It provides solutions for most of the problems you will meet +and allows you to write robust and flexible software. It is able to read +and write WCS information in a variety of formats, including +\htmladdnormallink{FITS-WCS}{http://fits.gsfc.nasa.gov/fits_wcs.html}. + +%\subsection{TBW---What is a World Coordinate \htmlref{System}{System}?} + +\subsection{What Problems Does AST Tackle?} + +Here are some of the main problems you may face when handling world +coordinate system (WCS) information and the solutions that AST +provides: + +\begin{description} +\item[1. The Variety of Coordinate Systems]\mbox{}\\ +Astronomers use a wide range of differing coordinate systems to describe +positions within a variety of physical domains. For instance, there are a +large number of celestial coordinate systems in use within astronomy to +describe positions on the sky. Understanding these, and knowing how to +convert coordinates between them, can require considerable expertise. It +can also be difficult to decide which of them your software should support. +The same applies to coordinate systems describing other domains, such as +position within an electro-magnetic spectrum. + +\textbf{Solution.} AST has built-in knowledge of many coordinate systems +and allows you to convert freely between them without specialist +knowledge. This avoids the need to embed details of specific +coordinate systems in your software. You also benefit automatically +when new coordinate systems are added to AST. + +\item[2. Storing and Retrieving WCS Information]\mbox{}\\ +Storing coordinate system information in astronomical datasets and +retrieving it later can present a considerable challenge. Typically, +it requires knowledge of rather complex conventions +(\emph{e.g.}\ FITS) which are low-level, often mis-interpreted and may +be subject to change. Exchanging information with other software +systems is further complicated by the number of different conventions +in use. + +\textbf{Solution.} AST combines a unifying high-level description of WCS +information with the ability to save and restore this using a variety +of formats. Details of the formats, which include FITS, are handled +internally by AST. This frees you from the need to understand them or +embed the details in your software. Again, you benefit automatically +when new formats are added to AST. + +\item[3. Generating Graphical Output]\mbox{}\\ +Producing graphical displays involving curvilinear coordinate systems, +such as celestial coordinate grids, can be complicated. Particular +difficulties arise when handling large areas of sky, the polar regions +and discontinuous (\emph{e.g.}\ segmented) sky projections. Even just +numbering and labelling curvilinear axes is rarely straightforward. + +\textbf{Solution.} AST provides plotting facilities especially designed +for use with curvilinear coordinate systems. These include the +plotting of axes and complete labelled coordinate grids. A large +number of options are provided for tailoring the output to your +specific needs. Three dimensional coordinate grids can also be produced. + +\item[4. Aligning Data from Different Sources]\mbox{}\\ +One of the main uses of coordinate systems is to facilitate the +inter-comparison of data from different sources. A typical use might +be to plot (say) radio contours over an optical image. In practice, +however, different celestial coordinate systems may have been used, +making accurate alignment far from simple. + +\textbf{Solution} AST provides a one-step method of aligning datasets, +searching for all possible intermediate coordinate systems. This +makes it simple to directly inter-relate the pixel coordinates of +different datasets. + +\item[5. Handling Different Types of Coordinate \htmlref{System}{System}]\mbox{}\\ +Not all coordinate systems used in astronomy are celestial ones, so if +you are writing general-purpose software such as (say) a display tool, +you may also need to handle axes representing wavelength, distance, +time or whatever else comes along. Obviously, you would prefer not to +handle each one as a special case. + +\textbf{Solution} AST uses the same flexible high-level model to +describe all types of coordinate system. This allows you to write +software that handles different kinds of coordinate axis without +introducing special cases. +\end{description} + +\subsection{Other Design Objectives} + +As well as its scientific objectives, the AST library's design +includes a number of technical criteria intended to make it applicable +to as wide a range of projects as possible. The main considerations +are described here: + +\begin{enumerate} +\item {\bf{Minimum Software Dependencies.}} +The AST library depends on no other other software\footnote{It comes with +bundled copies of the ERFA and +\xref{Starlink PAL libraries}{sun268}{} which are built +at the same time as the other AST internal libraries. Alternatively, external +PAL and ERFA libraries may be used by specifying the ``\texttt{--with-external\_pal}'' option when configuring AST}. + +\item {\bf{Environment Independence.}} +AST is designed so that it can operate in a variety of ``programming +environments'' and is not tied to any particular one. To allow this, +it uses simple, flexible interfaces to obtain the following services: + +\begin{itemize} +\item {\bf{Data Storage.}} Data I/O operations are based on text +and/or FITS headers. This makes it easy to interface to a wide variety +of astronomical data formats in a machine-independent way. + +\item {\bf{Graphics.}} Graphical output is produced \emph{via} a +simple generic graphics interface, which may easily be re-implemented +over different graphics systems. AST provides a default implementation +based on the widely-used PGPLOT graphics system +(\xref{SUN/15}{sun15}{}). + +\item {\bf{Error Handling.}} Error messages are written to standard +error by default, but go through a simple generic interface similar to +that used for graphics (above). This permits error message delivery +\emph{via} other routes when necessary (\emph{e.g.} in a graphical +interface). +\end{itemize} + +\item {\bf{Multiple Language Support.}} +AST has been designed to be called from more than one language. +Both C and Fortran interfaces are available (see +\xref{SUN/210}{sun210}{} for the Fortran version) +and use from C$++$ is also straightforward if the C interface is +included using: + +\begin{small} +\begin{terminalv} +extern "C" { +#include "ast.h" +} +\end{terminalv} +\end{small} + +A JNI interface (known as ``JNIAST'' - see +\url{http://www.starlink.ac.uk/jniast/}) has also been developed by Starlink +which allows AST to be used from Java. + +\item {\bf{\htmlref{Object}{Object} Oriented Design.}} +AST uses ``object oriented'' techniques internally in order to provide +a flexible and easily-extended programming model. A fairly +traditional calling interface is provided, however, so that the +library's facilities are easily accessible to programmers using +C and Fortran. + +\item {\bf{Portability.}} +AST is implemented entirely in ANSI standard C and, when called +\emph{via} its C interface, makes no explicit use of any +machine-dependent facilities. + +The Fortran interface is, unavoidably, machine dependent. However, the +potential for problems has been minimised by encapsulating the +interface layer in a compact set of C macros which facilitate its +transfer to other platforms. No Fortran compiler is needed to build +the library. + +Currently, AST is supported by Starlink on PC~Linux, Sun~Solaris and +Tru64~Unix (formerly DEC~UNIX) platforms. +\end{enumerate} + +\subsection{What Does ``AST'' Stand For?} + +The library name ``AST'' stands for ``ASTrometry Library''. The name +arose when it was thought that knowledge of ``astrometry'' +(\emph{i.e.}\ celestial coordinate systems) would form the bulk of the +library. In fact, it turns out that astrometry forms only a minor +component, but the name AST has stuck. + +\cleardoublepage +\section{Overview of AST Concepts} + +This section presents a brief overview of AST concepts. It is intended +as a basic orientation course before you move on to the more technical +considerations in subsequent sections. + +\subsection{\label{ss:mappingoverview}Relationships Between Coordinate Systems} + +The relationships between coordinate systems are represented in AST by +Objects called Mappings. A \htmlref{Mapping}{Mapping} does not represent a coordinate +system itself, but merely the process by which you move from one +coordinate system to another related one. + + A convenient picture of a Mapping is as a ``black box'' + (Figure~\ref{fig:mapping}) into which you can feed sets of + coordinates. + \begin{figure}[bhtp] + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/mapping} + \caption{A Mapping viewed as a ``black box'' for transforming coordinates.} + \label{fig:mapping} + \end{center} + \end{figure} + +For each set you feed in, the Mapping returns a corresponding set of +transformed coordinates. Since each set of coordinates represents a +point in a coordinate space, the Mapping acts to inter-relate +corresponding positions in the two spaces, although what these spaces +represent is unspecified. Notice that a Mapping need not have the +same number of input and output coordinates. That is, the two +coordinate spaces which it inter-relates need not have the same number +of dimensions. + +In many cases, the transformation can, in principle, be performed in +either direction: either from the \emph{input} coordinate space to the +\emph{output}, or \emph{vice versa}. The first of these is termed the +\emph{forward} transformation and the other the \emph{inverse} +transformation. + + +\textbf{Further reading:} For a more complete discussion of Mappings, +see~\secref{ss:mappings}. + +\subsection{\label{ss:mappingselection}Mappings Available} + +The basic concept of a \htmlref{Mapping}{Mapping} (\secref{ss:mappingoverview}) is rather +generic and obviously it is necessary to have specific Mappings that +implement specific relationships between coordinate systems. AST +provides a range of these, to perform transformations such as the +following and, where appropriate, their inverses: + +\begin{itemize} +\item Conversions between various celestial coordinate systems (the +\htmlref{SlaMap}{SlaMap}). + +\item Conversions between various spectral coordinate systems (the +\htmlref{SpecMap}{SpecMap} and \htmlref{GrismMap}{GrismMap}). + +\item Conversions between various time systems (the \htmlref{TimeMap}{TimeMap}). + +\item Conversion between 2-dimensional spherical celestial coordinates +(longitude and latitude) and a 3-dimensional vectorial positions (the \htmlref{SphMap}{SphMap}). + +\item Various projections of the celestial sphere on to 2-dimensional +coordinate spaces---\emph{i.e.}\ map projections (the \htmlref{DssMap}{DssMap} and \htmlref{WcsMap}{WcsMap}). + +\item Permutation, introduction and elimination of coordinates (the +\htmlref{PermMap}{PermMap}). + +\item Various linear coordinate transformations (the \htmlref{MatrixMap}{MatrixMap}, \htmlref{WinMap}{WinMap}, +\htmlref{ShiftMap}{ShiftMap} and \htmlref{ZoomMap}{ZoomMap}). + +\item General N-dimensional polynomial transformations (the \htmlref{PolyMap}{PolyMap}). + +\item Lookup tables (the \htmlref{LutMap}{LutMap}). + +\item General-purpose transformations expressed using arithmetic +operations and functions similar to those available in C (the +\htmlref{MathMap}{MathMap}). + +\item Transformations for internal use within a program, based on +private transformation functions which you write yourself in C (the +\htmlref{IntraMap}{IntraMap}). +\end{itemize} + +\textbf{Further reading:} For a more complete description of each of the +Mappings mentioned above, see its entry in +\appref{ss:classdescriptions}. In addition, see the discussion of the +PermMap in \secref{ss:permmapexample}, the \htmlref{UnitMap}{UnitMap} in +\secref{ss:unitmapexample} and the IntraMap in +\secref{ss:intramaps}. The ZoomMap is used as an example throughout +\secref{ss:primer}. + +\subsection{\label{ss:cmpmapoverview}Compound Mappings} + +The Mappings described in \secref{ss:mappingselection} provide a set +of basic building blocks from which more complex Mappings may be +constructed. The key to doing this is a type of \htmlref{Mapping}{Mapping} called a +\htmlref{CmpMap}{CmpMap}, or compound Mapping. A CmpMap's role is, in principle, very +simple: it allows any other pair of Mappings to be joined together +into a single entity which behaves as if it were a single Mapping. A +CmpMap is therefore a container for another pair of Mappings. + + A pair of Mappings may be combined using a CmpMap in either of two + ways. The first of these, \emph{in series}, is illustrated in + Figure~\ref{fig:seriescmpmap}. + \begin{figure} + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/series} + \caption[A CmpMap composed of two component Mappings joined in series]{A CmpMap (compound Mapping) composed of two component + Mappings joined in series. The output coordinates of the first Mapping + feed into the input coordinates of the second one, so that the whole + entity behaves like a single Mapping.} + \label{fig:seriescmpmap} + \end{center} + \end{figure} + + + Here, the transformations implemented by each component Mapping are + performed one after the other, with the output from the first Mapping + feeding into the second. The second way, \emph{in parallel}, is shown in + Figure~\ref{fig:parallelcmpmap}. + \begin{figure} + \begin{center} + \includegraphics[width=0.5\textwidth]{sun211_figures/parallel} + \caption[A CmpMap composed of two Mappings joined in parallel.]{A CmpMap composed of two Mappings joined in parallel. Each + component Mapping acts on a complementary subset of the input and + output coordinates.} + \label{fig:parallelcmpmap} + \end{center} + \end{figure} + +In this case, each Mapping acts on a complementary subset of the +input and output coordinates.\footnote{A pair of Mappings can be combined +in a third way using a \htmlref{TranMap}{TranMap}. A TranMap allows the forward +transformation of one Mapping to be combined with the inverse +transformation of another to produce a single Mapping.} + + The CmpMap forms the key to building arbitrarily complex Mappings + because it is itself a form of Mapping. This means that a CmpMap may + contain other CmpMaps as components + (\emph{e.g.}\ Figure~\ref{fig:complexcmpmap}). This nesting of CmpMaps + can be repeated indefinitely, so that complex Mappings may be built in + a hierarchical manner out of simper ones. + \begin{figure} + \begin{center} + \includegraphics[width=0.65\textwidth]{sun211_figures/complex} + \caption[CmpMaps may be nested in order to + construct complex Mappings out of simpler building blocks.]{CmpMaps + (compound Mappings) may be nested in order to + construct complex Mappings out of simpler building blocks.} + \label{fig:complexcmpmap} + \end{center} + \end{figure} + This gives AST great flexibility in the coordinate transformations it + can describe. + +\textbf{Further reading:} For a more complete description of CmpMaps, +see \secref{ss:cmpmaps}. Also see the CmpMap entry in +\appref{ss:classdescriptions}. + +\subsection{Representing Coordinate Systems} + + While Mappings (\secref{ss:mappingoverview}) represent the + relationships between coordinate systems in AST, the coordinate + systems themselves are represented by Objects called Frames + (Figure~\ref{fig:frames}). + \begin{figure} + \begin{center} + \includegraphics[width=0.55\textwidth]{sun211_figures/frames} + \caption[Representing coordinate systems as Frames.]{(a) A basic Frame is used to represent a Cartesian coordinate + system, here 2-dimensional. (b) A \htmlref{SkyFrame}{SkyFrame} represents a (spherical) + celestial coordinate system. (c) The axis order of any \htmlref{Frame}{Frame} may be + permuted to match the coordinate space it describes.} + \label{fig:frames} + \end{center} + \end{figure} + +A Frame is similar in concept to the frame you might draw around a +graph. It contains information about the labels which appear on the +axes, the axis units, a title, knowledge of how to format the +coordinate values on each axis, \emph{etc.} An AST Frame is not, +however, restricted to two dimensions and may have any number of axes. + +A basic Frame may be used to represent a Cartesian coordinate system +by setting values for its \emph{attributes} (all AST Objects have +values associated with them called attributes, which may be set and +enquired). Usually, this would involve setting appropriate axis +labels and units, for example. Functions are provided for use with +Frames to perform operations such as formatting coordinate values as +text, calculating distances between points, interchanging axes, +\emph{etc.} + +There are several more specialised forms of Frame, which provide the +additional functionality required when handling coordinates within some +specific physical domain. This ranges from tasks such as formatting axis +values, to complex tasks such as determining the transformation between +any pair of related coordinate systems. For instance, the SkyFrame +(Figure~\ref{fig:frames}b,c), represents celestial coordinate systems, +the \htmlref{SpecFrame}{SpecFrame} represents spectral coordinate systems, and the \htmlref{TimeFrame}{TimeFrame} +represents time coordinate systems. All these provide a wide range of +different systems for describing positions within their associated physical +domain, and these may be selected by setting appropriate attributes. + + As with compound Mappings (\secref{ss:cmpmapoverview}), it is possible + to merge two Frames together to form a compound Frame, or \htmlref{CmpFrame}{CmpFrame}, in + which both sets of axes are combined. One could, for example, have + celestial coordinates on two axes and an unrelated coordinate + (wavelength, perhaps) on a third (Figure~\ref{fig:cmpframe}). + Knowledge of the relationships between the axes is preserved + internally by the process of constructing the CmpFrame which + represents them. + \begin{figure} + \begin{center} + \includegraphics[width=0.4\textwidth]{sun211_figures/cmpframe} + \caption[A CmpFrame (compound Frame) formed by combining two simpler + Frames.]{A CmpFrame (compound Frame) formed by combining two simpler + Frames. Note how the special relationship which exists between the RA + and Dec axes is preserved within this data structure. As with compound + Mappings (Figure~\ref{fig:complexcmpmap}), CmpFrames may be nested in + order to build more complex Frames.} + \label{fig:cmpframe} + \end{center} + \end{figure} + +\textbf{Further reading:} For a more complete description of Frames see +\secref{ss:frames}, for SkyFrames see \secref{ss:skyframes} and for +SpecFrames see \secref{ss:specframes}. Also see the Frame, SkyFrame, +SpecFrame, TimeFrame and CmpFrame entries in \appref{ss:classdescriptions}. + +\subsection{Networks of Coordinate Systems} + + Mappings and Frames may be connected together to form networks called + FrameSets, which are used to represent sets of inter-related + coordinate systems (Figure~\ref{fig:frameset}). + \begin{figure} + \begin{center} + \includegraphics[width=0.65\textwidth]{sun211_figures/frameset} + \caption[A FrameSet is a network of Frames.]{A FrameSet is a network of Frames inter-connected by Mappings + such that there is exactly one conversion path, \emph{via} Mappings, + between any pair of Frames.} + \label{fig:frameset} + \end{center} + \end{figure} + + +A \htmlref{FrameSet}{FrameSet} may be extended by adding a new \htmlref{Frame}{Frame} to it, together with +an associated \htmlref{Mapping}{Mapping} which relates the new coordinate system to one +which is already present. This process ensures that there is always +exactly one path, \emph{via} Mappings, between any pair of Frames. A +function is provided for identifying this path and returning the +complete Mapping. + +One of the Frames in a FrameSet is termed its \emph{base} Frame. This +underlies the FrameSet's purpose, which is to calibrate datasets and +other entities by attaching coordinate systems to them. In this +context, the base Frame represents the ``native'' coordinate system +(for example, the pixel coordinates of an image). Similarly, one +Frame is termed the \emph{current} Frame and represents the +``currently-selected'' coordinates. It might, typically, be a +celestial or spectral coordinate system and would be used during +interactions with +a user, as when plotting axes on a graph or producing a table of +results. Other Frames within the FrameSet represent a library of +alternative coordinate systems which a software user can select by +making them current. + +\textbf{Further reading:} For a more complete description of +FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. Also +see the FrameSet entry in \appref{ss:classdescriptions}. + +\subsection{Input/Output Facilities} + +AST allows you to convert any kind of \htmlref{Object}{Object} into a stream of text +which contains a full description of that Object. This text may be +written out by one program and read back in by another, thus allowing +the original Object to be reconstructed. + +The filter which converts Objects into text and back again is itself a +kind of Object, called a \htmlref{Channel}{Channel}. A Channel provides a number of +options for controlling the information content of the text, such as +the addition of comments for human interpretation. It is also +possible to intercept the text being processed by a Channel so that it +may be redirected to/from any chosen external data store, such as a +text file, an astronomical dataset, or a network connection. + +The text format used by the basic Channel class is peculiar to the AST +library - no other software will understand it. However, more specialised +forms of Channel are provided which use text formats more widely +understood. + +To further facilitate the storage of coordinate system information in +astronomical datasets, a more specialised form of Channel called a +\htmlref{FitsChan}{FitsChan} is provided. Instead of using free-format text, a FitsChan +converts AST Objects to and from FITS header cards. It also allows the +information to be encoded in the FITS cards in a number of ways +(called \emph{encodings}), so that WCS information from a variety of +sources can be handled. + +Another sub-class of Channel, called \htmlref{XmlChan}{XmlChan}, is a specialised form of +Channel that stores the text in the form of XML markup. Currently, two +markup formats are provided by the XmlChan class, one is closely related +to the text format produced by the basic Channel class (currently, no +schema or DTD is available describing this format). The other is a subset +of an early draft of the IVOA Space-Time-Coordinates XML (STC-X) schema +(V1.20) described at +\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html +}\footnote{XML documents which use only the subset of the STC schema +supported by AST can be read by the XmlChan class to produce +corresponding AST objects (subclasses of the \htmlref{Stc}{Stc} class). However, the +reverse is not possible. That is, AST objects can not currently be +written out in the form of STC documents.}. The version of STC-X that has +been adopted by the IVOA differs in several significant respects from +V1.20, and therefore this XmlChan format is of historical interest only. + +Finally, the \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing +IVOA STC-S region descriptions. STC-S (see +\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string +syntax that allows simple specification of STC metadata. AST supports a +subset of the STC-S specification, allowing an STC-S description of a +region within an AST-supported astronomical coordinate system to be converted +into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. + +\textbf{Further reading:} For a more complete description of Channels +see \secref{ss:channels} and for FitsChans see \secref{ss:nativefits} +and \secref{ss:foreignfits}. Also see the Channel and FitsChan entries +in \appref{ss:classdescriptions} and the \htmlref{Encoding}{Encoding} entry in +\appref{ss:attributedescriptions}. + +\subsection{Producing Graphical Output} + +Two dimensional graphical output is supported by a specialised form of +\htmlref{FrameSet}{FrameSet} called +a \htmlref{Plot}{Plot}, whose base \htmlref{Frame}{Frame} corresponds with the native coordinates of +the underlying graphics system. Plotting operations are specified in +\emph{physical coordinates} which correspond with the Plot's current +Frame. Typically, this might be a celestial coordinate system. + +Three dimensional plotting is also supported, via the \htmlref{Plot3D}{Plot3D} class - +sub-class of Plot. + +Operations, such as drawing lines, are automatically transformed from +physical to graphical coordinates before plotting, using an adaptive +algorithm which ensures smooth curves (because the transformation is +usually non-linear). ``Missing'' coordinates (\emph{e.g.}\ graphical +coordinates which do not project on to the celestial sphere), +discontinuities and generalised clipping are all consistently handled. +It is possible, for example, to plot in equatorial coordinates and +clip in galactic coordinates. The usual plotting operations are +provided (text, markers), but a geodesic curve replaces the primitive +straight line element. There is also a separate function for drawing +axis lines, since these are normally not geodesics. + +In addition to drawing coordinate grids over an area of the sky, another +common use of the Plot class is to produce line plots such as flux +against wavelength, displacement again time, \emph{etc}. For these +situations the current Frame of the Plot would be a compound Frame +(\htmlref{CmpFrame}{CmpFrame}) containing a pair of 1-dimensional Frames - the first +representing the X axis quantity (wavelength, time, etc), and the second +representing the Y axis quantity (flux, displacement, etc). The Plot +class includes an option for axes to be plotted logarithmically. + + Perhaps the most useful graphics function available is for drawing + fully annotated coordinate grids (\emph{e.g.}\ Figure~\ref{fig:gridplot}). + \begin{figure} + \begin{center} + \includegraphics[width=0.6\textwidth]{sun211_figures/gridplot_bw} + \caption[A labelled coordinate grid for an all-sky zenithal equal area + projection in ecliptic coordinates.]{A labelled coordinate grid for an all-sky zenithal equal area + projection in ecliptic coordinates. This was composed and drawn + \emph{via} a Plot using a + single function call.} + \label{fig:gridplot} + \end{center} + \end{figure} + +This uses a general algorithm which does not depend on knowledge of +the coordinates being represented, so can also handle +programmer-defined coordinate systems. Grids for all-sky projections, +including polar regions, can be drawn and most aspects of the output +(colour, line style, \emph{etc.}) can be adjusted by setting +appropriate Plot attributes. + +\textbf{Further reading:} For a more complete description of +Plots and how to produce graphical output, see \secref{ss:plots}. Also +see the Plot entry in \appref{ss:classdescriptions}. + +\cleardoublepage +\section{\label{ss:howto}How To\ldots} + +For those of you with a plane to catch, this section provides some +instant templates and recipes for performing the most +commonly-required operations using AST, but without going into +detail. The examples given (sort of) follow on from each other, so you +should be able to construct a variety of programs by piecing them +together. Note that some of them appear longer than they actually +are, because we have included plenty of comments and a few options +that you probably won't need. + +If any of this material has you completely baffled, then you may want +to read the introduction to AST programming concepts in +\secref{ss:primer} first. Otherwise, references to more detailed +reading are given after each example, just in case they don't quite do +what you want. + +\subsection{\ldots Obtain and Install AST} +The AST library is available both as a stand-alone package and also as +part of the Starlink Software Collection\footnote{The Starlink Software +Collection can be downloaded from +\url{http://www.starlink.ac.uk/Download/}.}. If your site has the Starlink +Software Collection installed then AST should already be available. + +If not, you can download the AST library by itself from +\url{http://www.starlink.ac.uk/ast/}. + +\subsection{\ldots Structure an AST Program} + +An AST program normally has the following structure: + +\begin{small} +\begin{terminalv} +/* Include the interface to the AST library. */ +#include "ast.h" + +/* Main program (or could be any function). */ +main () { + <normal C declarations and statements> + +/* Enclose the parts which use AST between the astBegin and astEnd macros. */ + astBegin; + <C statements which use AST> + astEnd; + + <maybe more C statements> +} +\end{terminalv} +\end{small} + +The use of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} is optional, but has the effect of +tidying up after you have finished using AST, so is normally +recommended. For more details of this, see \secref{ss:contexts}. For +details of how to access the ``ast.h'' header file, see +\secref{ss:accessingheaderfile}. + +\subsection{\label{ss:howtobuild}\ldots Build an AST Program} + +To build a simple AST program that doesn't use graphics, use: + +\begin{small} +\begin{terminalv} +cc program.c -L/star/lib -I/star/include `ast_link` -o program +\end{terminalv} +\end{small} + +To build a program which uses PGPLOT for graphics, use: + +\begin{small} +\begin{terminalv} +cc program.c -L/star/lib `ast_link -pgplot` -o program +\end{terminalv} +\end{small} + +For more details about accessing the ``ast.h'' header file, see +\secref{ss:accessingheaderfile}. For more +details about linking programs, see \secref{ss:linking} and the +description of the ``\htmlref{ast\_link}{ast\_link}'' command in +\appref{ss:commanddescriptions}. + +\subsection{\label{ss:howtoreadwcs}\ldots Read a WCS Calibration from a Dataset} + +Precisely how you extract world coordinate system (WCS) information +from a dataset obviously depends on what type of dataset it +is. Usually, however, you should be able to obtain a set of FITS +header cards which contain the WCS information (and probably much more +besides). Suppose that ``cards'' is a pointer to a string +containing a complete set of concatenated FITS header cards (such as +produced by the CFITSIO function fits\_hdr2str). Then proceed as follows: + +\begin{small} +\begin{terminalv} +fitsfile *fptr; +AstFitsChan *fitschan; +AstFrameSet *wcsinfo; +char *header; +int nkeys, status; + +... + +/* Obtain all the cards in the header concatenated into a single dynamically + allocated null-terminated character string. Note, we do not exclude + any cards since we may later modify the WCS information within the + header and consequently want to write the entire header out again. */ + if( fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) + printf(" Error getting header\n"); + ... + +/* Header obtained succesfully... */ + } else { + +/* Create a FitsChan and fill it with FITS header cards. */ + fitschan = astFitsChan( NULL, NULL, "" ); + astPutCards( fitschan, header ); + +/* Free the memory holding the concatenated header cards. */ + header = free( header ); + +/* Read WCS information from the FitsChan. */ + wcsinfo = astRead( fitschan ); + + ... + +\end{terminalv} +\end{small} + + +The result should be a pointer, ``wcsinfo'', to a \htmlref{FrameSet}{FrameSet} which +contains the WCS information. This pointer can now be used to perform +many useful tasks, some of which are illustrated in the following +recipes. + +Some datasets which do not easily yield FITS header cards may require +a different approach, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} +(\secref{ss:channels}) rather than a \htmlref{FitsChan}{FitsChan}. In the case of the +Starlink NDF data format, for example, all the above may be replaced +by a single call to the function +\xref{ndfGtwcs}{sun33}{ndfGtwcs}---see \xref{SUN/33}{sun33}{}. The +whole process can probably be encapsulated in a similar way for +most data systems, whether they use FITS header cards or not. + +For more details about reading WCS information from datasets, see +\secref{ss:identifyingfitsencoding} and +\secref{ss:readingforeignfits}. For a more general description of +FitsChans and their use with FITS header cards, see +\secref{ss:nativefits} and \secref{ss:foreignfits}. For more details +about FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. + +\subsection{\ldots Validate WCS Information} + +Once you have read WCS information from a dataset, as in +\secref{ss:howtoreadwcs}, you may wish to check that you have been +successful. The following will detect and classify the things that +might possibly go wrong: + +\begin{small} +\begin{terminalv} +#include <string.h> + +... + +if ( !astOK ) { + <an error occurred (a message will have been issued)> +} else if ( wcsinfo == AST__NULL ) { + <there was no WCS information present> +} else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { + <something unexpected was read (i.e. not a FrameSet)> +} else { + <WCS information was read OK> +} +\end{terminalv} +\end{small} + +For more information about detecting errors in AST functions, see +\secref{ss:errordetection}. For details of how to validate input data +read by AST, see \secref{ss:validatinginput} and +\secref{ss:readingforeignfits}. + +\subsection{\ldots Display AST Data} + +If you have a pointer to any AST \htmlref{Object}{Object}, you can display the data +stored in that Object in textual form as follows: + +\begin{small} +\begin{terminalv} +astShow( wcsinfo ); +\end{terminalv} +\end{small} + +Here, we have used a pointer to the \htmlref{FrameSet}{FrameSet} which we read earlier +(\secref{ss:howtoreadwcs}). The result is written to the program's +standard output stream. This can be very useful during debugging. + +For more details about using \htmlref{astShow}{astShow}, see +\secref{ss:displayingobjects}. For information about interpreting the +output, also see \secref{ss:textualoutputformat}. + +\subsection{\label{ss:howtotransform}\ldots Convert Between Pixel and World Coordinates} + +You may use a pointer to a \htmlref{FrameSet}{FrameSet}, such as we read in +\secref{ss:howtoreadwcs}, to transform a set of points between the +pixel coordinates of an image and the associated world coordinates. If +you are working in two dimensions, proceed as follows: + +\begin{small} +\begin{terminalv} +double xpixel[ N ], ypixel[ N ]; +double xworld[ N ], yworld[ N ]; + +... + +astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); +\end{terminalv} +\end{small} + +Here, N is the number of points to be transformed, ``xpixel'' and +``ypixel'' hold the pixel coordinates, and ``xworld'' and ``yworld'' +receive the returned world coordinates.\footnote{By pixel coordinates, +we mean a coordinate system in which the first pixel in the image is +centred on (1,1) and each pixel is a unit square. Note that the world +coordinates will not necessarily be celestial coordinates, but if they +are, then they will be in radians.} To transform in the opposite +direction, interchange the two pairs of arrays (so that the world +coordinates are given as input) and change the fifth argument of +\htmlref{astTran2}{astTran2} to zero. + +To transform points in one dimension, use \htmlref{astTran1}{astTran1}. In any other +number of dimensions (or if the number of dimensions is initially +unknown), use \htmlref{astTranN}{astTranN} or \htmlref{astTranP}{astTranP}. These functions are described in +\appref{ss:functiondescriptions}. + +For more information about transforming coordinates, see +\secref{ss:transforming} and \secref{ss:framesetasmapping}. For +details of how to handle missing coordinates, see +\secref{ss:badcoordinates}. + +\subsection{\label{ss:howtotestforcelestial}\ldots Test if a WCS is a Celestial Coordinate System} + +The world coordinate system (WCS) currently associated with an image +may often be a celestial coordinate system, but this need not +necessarily be the case. For instance, instead of right ascension and +declination, an image might have a WCS with axes representing +wavelength and slit position, or maybe just plain old pixels. + +If you have obtained a WCS calibration for an image, as in +\secref{ss:howtoreadwcs}, in the form of a pointer ``wcsinfo'' to a +\htmlref{FrameSet}{FrameSet}, then you may determine if the current coordinate system is a +celestial one or not, as follows: + +\begin{small} +\begin{terminalv} +AstFrame *frame; +int issky; + +... + +/* Obtain a pointer to the current Frame and determine if it is a + SkyFrame. */ +frame = astGetFrame( wcsinfo, AST__CURRENT ); +issky = astIsASkyFrame( frame ); +frame = astAnnul( frame ); +\end{terminalv} +\end{small} + +This will set ``issky'' to 1 if the WCS is a celestial coordinate +system, and to zero otherwise. + +\subsection{\label{ss:howtotestforspectral}\ldots Test if a WCS is a Spectral Coordinate System} +Testing for a spectral coordinate system is basically the same as testing +for a celestial coordinate system (see the previous section). The one +difference is that you use the +astIsASpecFrame function +in place of the +astIsASkyFrame function. + +\subsection{\label{ss:howtoformatcoordinates}\ldots Format Coordinates for Display} + +Once you have converted pixel coordinates into world coordinates +(\secref{ss:howtotransform}), you may want to format them as text +before displaying them. Typically, this would convert from (say) +radians into something more comprehensible. Using the \htmlref{FrameSet}{FrameSet} pointer +``wcsinfo'' obtained in \secref{ss:howtoreadwcs} and a pair of world +coordinates ``xw'' and ``yw'' (\emph{e.g.}\ see +\secref{ss:howtotransform}), you could proceed as follows: + +\begin{small} +\begin{terminalv} +#include <stdio.h> +const char *xtext, *ytext; +double xw, yw; + +... + +xtext = astFormat( wcsinfo, 1, xw ); +ytext = astFormat( wcsinfo, 2, yw ); + +(void) printf( "Position = %s, %s\n", xtext, ytext ); +\end{terminalv} +\end{small} + +Here, the second argument to \htmlref{astFormat}{astFormat} is the axis number. + +With celestial coordinates, this will usually result in sexagesimal +notation, such as ``12:34:56.7''. However, the same method may be +applied to any type of coordinates and appropriate formatting will be +employed. + +For more information about formatting coordinate values and how to +control the style of formatting used, see +\secref{ss:formattingaxisvalues} and +\secref{ss:formattingskyaxisvalues}. If necessary, also see +\secref{ss:normalising} for details of how to ``normalise'' a set of +coordinates so that they lie within the standard range (\emph{e.g.}\ 0 +to 24 hours for right ascension and $\pm 90^\circ$ for +declination). + +\subsection{\ldots Display Coordinates as they are Transformed} + +In addition to formatting coordinates as part of a program's output, +you may also want to examine coordinate values while debugging your +program. To save time, you can ``eavesdrop'' on the coordinate values +being processed every time they are transformed. For example, when +using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in +\secref{ss:howtoreadwcs} to transform coordinates +(\secref{ss:howtotransform}), you could inspect the coordinate values +as follows: + +\begin{small} +\begin{terminalv} +astSet( wcsinfo, "Report=1" ); +astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); +\end{terminalv} +\end{small} + +By setting the FrameSet's \htmlref{Report}{Report} attribute to 1, coordinate +transformations are automatically displayed on the program's standard +output stream, appropriately formatted, for example: + +\begin{terminalv} +(42.1087, 20.2717) --> (2:06:03.0, 34:22:39) +(43.0197, 21.1705) --> (2:08:20.6, 35:31:24) +(43.9295, 22.0716) --> (2:10:38.1, 36:40:09) +(44.8382, 22.9753) --> (2:12:55.6, 37:48:55) +(45.7459, 23.8814) --> (2:15:13.1, 38:57:40) +(46.6528, 24.7901) --> (2:17:30.6, 40:06:25) +(47.5589, 25.7013) --> (2:19:48.1, 41:15:11) +(48.4644, 26.6149) --> (2:22:05.6, 42:23:56) +(49.3695, 27.5311) --> (2:24:23.1, 43:32:41) +(50.2742, 28.4499) --> (2:26:40.6, 44:41:27) +\end{terminalv} + +For a complete description of the Report attribute, see its entry in +\appref{ss:attributedescriptions}. For further details of how to set +and enquire attribute values, see \secref{ss:settingattributes} and +\secref{ss:gettingattributes}. + +\subsection{\ldots Read Coordinates Entered by a User} + +In addition to writing out coordinate values generated by your program +(\secref{ss:howtoformatcoordinates}), you may also need to accept +coordinates entered by a user, or perhaps read from a file. In this +case, you will probably want to allow ``free-format'' input, so that +the user has some flexibility in the format that can be used. You will +probably also want to detect any typing errors. + +Let's assume that you want to read a number of lines of text, each +containing the world coordinates of a single point, and to split each +line into individual numerical coordinate values. Using the \htmlref{FrameSet}{FrameSet} +pointer ``wcsinfo'' obtained earlier (\secref{ss:howtoreadwcs}), you +could proceed as follows: + +\begin{small} +\begin{terminalv} +#include <stdio.h> +char *t; +char text[ MAXCHARS + 2 ]; +double coord[ 10 ]; +int iaxis, n, naxes; + +... + +/* Obtain the number of coordinate axes (if not already known). */ +naxes = astGetI( wcsinfo, "Naxes" ); + +/* Loop to read each line of input text, in this case from the + standard input stream (your programming environment will probably + provide a better way of reading text than this). Set the pointer + "t" to the start of each line read. */ +while ( t = fgets( text, MAXCHARS + 2, stdin ) ) { + +/* Attempt to read a coordinate for each axis. */ + for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { + n = astUnformat( wcsinfo, iaxis, t, &coord[ iaxis - 1 ] ); + +/* If nothing was read and this is not the first axis or the + end-of-string, try stepping over a separator and reading again. */ + if ( !n && ( iaxis > 1 ) && *t ) + n = astUnformat( wcsinfo, iaxis, ++t, &coord[ iaxis - 1 ] ); + +/* Quit if nothing was read, otherwise move on to the next coordinate. */ + if ( !n ) break; + t += n; + } + +/* Test for the possible errors that may occur... */ + +/* Error detected by AST (a message will have been issued). */ + if ( !astOK ) { + break; + +/* Error in input data at character t[n]. */ + } else if ( *t || !n ) { + <handle the error, or report your own message here> + break; + + } else { + <coordinates were read OK> + } +} +\end{terminalv} +\end{small} + +This algorithm has the advantage of accepting free-format input in +whatever style is appropriate for the world coordinates in use (under +the control of the FrameSet whose pointer you provide). For example, +wavelength values might be read as floating point numbers +(\emph{e.g.}\ ``1.047'' or ``4787''), whereas celestial positions +could be given in sexagesimal format (\emph{e.g.}\ ``12:34:56'' or +``12~34.5'') and would be converted into radians. Individual +coordinate values may be separated by white space and/or any +non-ambiguous separator character, such as a comma. + +For more information on reading coordinate values using the +\htmlref{astUnformat}{astUnformat} function, see \secref{ss:unformattingaxisvalues}. For +details of how sexagesimal formats are handled, and the forms of input +that may be used for celestial coordinates, see +\secref{ss:unformattingskyaxisvalues}. + +\subsection{\label{ss:howtocreatenewwcs}\ldots Create a New WCS Calibration} + +This section describes how to add a WCS calibration to a data set which you +are creating from scratch, rather than modifying an existing data set. + +In most common cases, the simplest way to create a new WCS calibration +from scratch is probably to create a set of strings describing the +required calibration in terms of the keywords used by the FITS WCS +standard, and then convert these strings into an AST \htmlref{FrameSet}{FrameSet} describing +the calibration. This FrameSet can then be used for many other purposes, or +simply stored in the data set. + +The full FITS-WCS standard is quite involved, currently running to four +separate papers, but the basic kernel is quite simple, involving the +following keywords (all of which end with an integer axis index, +indicated below by $<i>$): + +\begin{description} +\item[CRPIX<i>]\mbox{}\\ +hold the pixel coordinates at a reference point +\item[CRVAL<i>]\mbox{}\\ +hold the corresponding WCS coordinates at the reference point +\item[CTYPE<i>]\mbox{}\\ +name the quantity represented by the WCS axes, together with the +projection algorithm used to convert the scaled and rotated pixel coordinates +to WCS coordinates. +\item[CD<i>\_<j>]\mbox{}\\ +a set of keywords which specify the elements of a matrix. This matrix scales +pixel offsets from the reference point into the offsets required as input +by the projection algorithm specified by the CTYPE keywords. This matrix +specifies the scale and rotation of the image. If there is no rotation +the off-diagonal elements of the matrix (\emph{e.g.} CD1\_2 and +CD2\_1) can be omitted. +\end{description} + +As an example consider the common case of a simple 2D image of the sky in +which north is parallel to the second pixel axis and east parallel to the +(negative) first pixel axis. The image scale is 1.2 arc-seconds per pixel +on both axes, and the image is presumed to have been obtained with a +tangent plane projection. Furthermore, it is known that pixel coordinates +(100.5,98.4) correspond to an RA of 11:00:10 and a Dec. of -23:26:02. +A suitable set of FITS-WCS header cards could be: + +\begin{small} +\begin{terminalv} +CTYPE1 = 'RA---TAN' / Axis 1 represents RA with a tan projection +CTYPE2 = 'DEC--TAN' / Axis 2 represents Dec with a tan projection +CRPIX1 = 100.5 / Pixel coordinates of reference point +CRPIX2 = 98.4 / Pixel coordinates of reference point +CRVAL1 = 165.04167 / Degrees equivalent of "11:00:10" hours +CRVAL2 = -23.433889 / Decimal equivalent of "-23:26:02" degrees +CD1_1 = -0.0003333333 / Decimal degrees equivalent of -1.2 arc-seconds +CD2_2 = 0.0003333333 / Decimal degrees equivalent of 1.2 arc-seconds +\end{terminalv} +\end{small} + +Notes: +\begin{itemize} +\item a FITS header card begins with the keyword name starting at column 1, +has an equals sign in column 9, and the keyword value in columns 11 to 80. +\item string values must be enclosed in single quotes. +\item celestial longitude and latitude must both be specified in decimal degrees. +\item the CD1\_1 value is negative to indicate that RA increases as the +first pixel axis decreases. +\item the (RA,Dec) coordinates will be taken as ICRS coordinates. For FK5 +you should add: + +\begin{small} +\begin{terminalv} +RADESYS = 'FK5' +EQUINOX = 2005.6 +\end{terminalv} +\end{small} + +The EQUINOX value defaults to J2000.0 if omitted. FK4 can also be used in +place of FK5, in which case EQUINOX defaults to B1950.0. + +\end{itemize} + +Once you have created these FITS-WCS header card strings, you should +store them in a \htmlref{FitsChan}{FitsChan} and then read the corresponding FrameSet from the +FitsChan. How to do this is described in \secref{ss:howtoreadwcs}. + +Having created the WCS calibration, you may want to store it in a data +file. How to do this is described in \secref{ss:howtowritewcs}).\footnote{If +you are writing the WCS calibration to a FITS file you obviously +have the choice of storing the FITS-WCS cards directly.} + +If the required WCS calibration cannot be described as a set of FITS-WCS +headers, then a different approach is necessary. In this case, you should +first create a \htmlref{Frame}{Frame} describing pixel coordinates, and store this Frame +in a new FrameSet. You should then create a new Frame describing the +world coordinate system. This Frame may be a specific subclass of Frame such +as a \htmlref{SkyFrame}{SkyFrame} for celestial coordinates, a \htmlref{SpecFrame}{SpecFrame} for spectral +coordinates, a Timeframe for time coordinates, or a \htmlref{CmpFrame}{CmpFrame} for a combination +of different coordinates. +You also need to create a suitable \htmlref{Mapping}{Mapping} which transforms pixel +coordinates into world coordinates. AST provides many different types of +Mappings, all of which can be combined together in arbitrary fashions to +create more complicated Mappings. The WCS Frame should then be added into +the FrameSet, using the Mapping to connect the WCS Frame with the pixel +Frame. + +\subsection{\label{ss:howtomodifywcs}\ldots Modify a WCS Calibration} + +The usual reason for wishing to modify the WCS calibration associated +with a dataset is that the data have been geometrically transformed in +some way (here, we will assume a 2-dimensional image dataset). This +causes the image features (stars, galaxies, \emph{etc.}) to move with +respect to the grid of pixels which they occupy, so that any +coordinate systems previously associated with the image become +invalid. + +To correct for this, it is necessary to set up a \htmlref{Mapping}{Mapping} which +expresses the positions of image features in the new data grid in +terms of their positions in the old grid. In both cases, the grid +coordinates we use will have the first pixel centred at (1,1) with +each pixel being a unit square. + +AST allows you to correct for any type of geometrical transformation +in this way, so long as a suitable Mapping to describe it can be +constructed. For purposes of illustration, we will assume here that +the new image coordinates ``xnew'' and ``ynew'' can be expressed in +terms of the old coordinates ``xold'' and ``yold'' as follows: + +\begin{small} +\begin{terminalv} +double xnew, xold, ynew, yold; +double m[ 4 ], z[ 2 ]; + +... + +xnew = xold * m[ 0 ] + yold * m[ 1 ] + z[ 0 ]; +ynew = xold * m[ 2 ] + yold * m[ 3 ] + z[ 1 ]; +\end{terminalv} +\end{small} + +where ``m'' is a 2$\times$2 transformation matrix and ``z'' represents +a shift of origin. This is therefore a general linear coordinate +transformation which can represent displacement, rotation, +magnification and shear. + +In AST, it can be represented by concatenating two Mappings. The first +is a \htmlref{MatrixMap}{MatrixMap}, which implements the matrix multiplication. The second +is a \htmlref{WinMap}{WinMap}, which linearly transforms one coordinate window on to +another, but will be used here simply to implement the shift of +origin (alternatively, a \htmlref{ShiftMap}{ShiftMap} could have been used in place of a +WinMap). These Mappings may be constructed and concatenated as follows: + +\begin{small} +\begin{terminalv} +AstCmpMap *newmap; +AstMatrixMap *matrixmap; +AstWinMap *winmap; + +... + +/* The MatrixMap may be constructed directly from the matrix "m". */ +matrixmap = astMatrixMap( 2, 2, 0, m, "" ); + +/* For the WinMap, we set up the coordinates of the corners of a unit + square (window) and then the same square shifted by the required + amount. */ +{ + double ina[] = { 0.0, 0.0 }; + double inb[] = { 1.0, 1.0 }; + double outa[] = { z[ 0 ], z[ 1 ] }; + double outb[] = { 1.0 + z[ 0 ], 1.0 + z[ 1 ] }; + +/* The WinMap will then implement this shift. */ + winmap = astWinMap( 2, ina, inb, outa, outb, "" ); +} + +/* Join the two Mappings together, so that they are applied one after + the other. */ +newmap = astCmpMap( matrixmap, winmap, 1, "" ); +\end{terminalv} +\end{small} + +You might, of course, create any other form of Mapping depending on +the type of geometrical transformation involved. For an overview of +the Mappings provided by AST, see \secref{ss:mappingselection}, and +for a description of the capabilities of each class of Mapping, see +its entry in \appref{ss:classdescriptions}. For an overview of how +individual Mappings may be combined, see \secref{ss:cmpmapoverview} +(\secref{ss:cmpmaps} gives more details). + +Assuming you have obtained a WCS calibration for your original image +in the form of a pointer to a \htmlref{FrameSet}{FrameSet}, ``wcsinfo1'' +(\secref{ss:howtoreadwcs}), the Mapping created above may be used to +produce a calibration for the new image as follows: + +\begin{small} +\begin{terminalv} +AstFrameSet *wcsinfo1, *wcsinfo2; + +... + +/* If necessary, make a copy of the WCS calibration, since we are + about to alter it. */ +wcsinfo2 = astCopy( wcsinfo1 ); + +/* Re-map the base Frame so that it refers to the new data grid + instead of the old one. */ +astRemapFrame( wcsinfo2, AST__BASE, newmap ); +\end{terminalv} +\end{small} + +This will produce a pointer, ``wcsinfo2'', to a new FrameSet in which +all the coordinate systems associated with your original image are +modified so that they are correctly registered with the new image +instead. + +For more information about re-mapping the Frames within a FrameSet, +see \secref{ss:remapframe}. Also see \secref{ss:wcsprocessingexample} +for a similar example to the above, applicable to the case of reducing +the size of an image by binning. + +\subsection{\label{ss:howtowritewcs}\ldots Write a Modified WCS Calibration to a Dataset} + +If you have modified the WCS calibration associated with a dataset, +such as in the example above (\secref{ss:howtomodifywcs}), then you +will need to write the modified version out along with any new data. + +In the same way as when reading a WCS calibration +(\secref{ss:howtoreadwcs}), how you do this will depend on your data +system, but we will assume that you wish to generate a set of FITS +header cards that can be stored with the data. You should usually make +preparations for doing this when you first read the WCS calibration +from your input dataset by modifying the example given in +\secref{ss:howtoreadwcs} as follows: + +\begin{small} +\begin{terminalv} +AstFitsChan *fitschan1; +AstFrameSet *wcsinfo1; +const char *encode; + +... + +/* Create an input FitsChan and fill it with FITS header cards. Note, + if you have all the header cards in a single string, use astPutCards in + place of astPutFits. */ +fitschan1 = astFitsChan( NULL, NULL, "" ); +for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan1, cards[ icard ], 0 ); + +/* Note which encoding has been used for the WCS information. */ +encode = astGetC( fitschan1, "Encoding" ); + +/* Rewind the input FitsChan and read the WCS information from it. */ +astClear( fitschan1, "Card" ); +wcsinfo1 = astRead( fitschan1 ); +\end{terminalv} +\end{small} + +Note how we have added an enquiry to determine how the WCS information +is encoded in the input FITS cards, storing a pointer to the resulting +string in the ``encode'' variable. This must be done \textbf{before} +actually reading the WCS calibration. + +\emph{(\textbf{N.B.}\ If you will be making extensive use of astGetC in +your program, then you should allocate a buffer and make a copy of +this string, because the pointer returned by astGetC will only remain +valid for 50 invocations of the function, and you will need to use the +\htmlref{Encoding}{Encoding} value again later on.)} + +Once you have produced a modified WCS calibration for the output +dataset (\emph{e.g.}\ \secref{ss:howtomodifywcs}), in the form of a +\htmlref{FrameSet}{FrameSet} identified by the pointer ``wcsinfo2'', you can produce a new +\htmlref{FitsChan}{FitsChan} containing the output FITS header cards as follows: + +\small +\begin{terminalv} +AstFitsChan *fitschan2; +AstFrameSet *wcsinfo2; + +... + +/* Make a copy of the input FitsChan, AFTER the WCS information has + been read from it. This will propagate all the input FITS header + cards, apart from those describing the input WCS calibration. */ +fitschan2 = astCopy( fitschan1 ); + +/* If necessary, make modifications to the cards in "fitschan2" + (e.g. you might need to change NAXIS1, NAXIS2, etc., to account for + a change in image size). You probably only need to do this if your + data system does not provide these facilities itself. */ +<details not shown - see below> + +/* Alternatively, if your data system handles the propagation of FITS + header cards to the output dataset for you, then simply create an + empty FitsChan to contain the output WCS information alone. +fitschan2 = astFitsChan( NULL, NULL, "" ); +*/ + +/* Rewind the new FitsChan (if necessary) and attempt to write the + output WCS information to it using the same encoding method as the + input dataset. */ +astSet( fitschan2, "Card=1, Encoding=%s", encode ); +if ( !astWrite( fitschan2, wcsinfo2 ) ) { + +/* If this didn't work (the WCS FrameSet has become too complex), then + use the native AST encoding instead. */ + astSet( fitschan2, "Encoding=NATIVE" ); + (void) astWrite( fitschan2, wcsinfo2 ); +} +\end{terminalv} +\normalsize + +For details of how to modify the contents of the output FitsChan in +other ways, such as by adding, over-writing or deleting header cards, +see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and +\secref{ss:findingandchangingfits}. + +Once you have assembled the output FITS cards, you may retrieve them +from the FitsChan that contains them as follows: + +\small +\begin{terminalv} +#include <stdio.h> +char card[ 81 ]; + +... + +astClear( fitschan2, "Card" ); +while ( astFindFits( fitschan2, "%f", card, 1 ) ) (void) printf( "%s\n", card ); +\end{terminalv} +\normalsize + +Here, we have simply written each card to the standard output stream, +but you would obviously replace this with a function invocation to +store the cards in your output dataset. + +For data systems that do not use FITS header cards, a different +approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} +(\secref{ss:channels}) rather than a FitsChan. In the case of the +Starlink NDF data format, for example, all of the above may be +replaced by a single call to the function +\xref{ndfPtwcs}{sun33}{ndfPtwcs}---see \xref{SUN/33}{sun33}{}. The +whole process can probably be encapsulated in a similar way for most +data systems, whether they use FITS header cards or not. + +For an overview of how to propagate WCS information through data +processing steps, see \secref{ss:propagatingwcsinformation}. For more +information about writing WCS information to FitsChans, see +\secref{ss:writingnativefits} and \secref{ss:writingforeignfits}. For +information about the options for encoding WCS information in FITS +header cards, see \secref{ss:nativeencoding}, +\secref{ss:foreignencodings}, and the description of the Encoding +attribute in \appref{ss:attributedescriptions}. For a complete +understanding of FitsChans and their use with FITS header cards, you +should read \secref{ss:nativefits} and \secref{ss:foreignfits}. + +\subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid} + + A common requirement when displaying image data is to plot an + associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid}) + over the displayed image. + \begin{figure} + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/overgrid_bw} + \caption[An example of a displayed image with a coordinate grid + plotted over it.]{An example of a displayed image with a coordinate grid + plotted over it.} + \label{fig:overgrid} + \end{center} + \end{figure} + +The use of AST in such circumstances is independent of the underlying +graphics system, so starting up the graphics system, setting up a +coordinate system, displaying the image, and closing down afterwards +can all be done using the graphics functions you would normally use. + +However, displaying an image at a precise location can be a little +fiddly with some graphics systems, and obviously the grid drawn by AST +will not be accurately registered with the image unless this is done +correctly. In the following template, we therefore illustrate both +steps, basing the image display on the C interface to the PGPLOT +graphics package.\footnote{An interface is provided with AST that +allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics, +although interfaces to other graphics systems may also be written.} +Plotting a coordinate grid with AST then becomes a relatively minor +part of what is almost a complete graphics program. + +Once again, we assume that a pointer, ``wcsinfo'', to a suitable +\htmlref{FrameSet}{FrameSet} associated with the image has already been obtained +(\secref{ss:howtoreadwcs}). + +\small +\begin{terminalv} +#include "cpgplot.h" +AstPlot *plot; +const float *data; +float hi, lo, scale, x1, x2, xleft, xright, xscale; +float y1, y2, ybottom, yscale, ytop; +int nx, ny; + +... + +/* Access the image data, which we assume has dimension sizes "nx" and + "ny", and will be accessed via the "data" pointer. Also derive + limits for scaling it, which we assign to the variables "hi" and + "lo". */ +<this stage depends on your data system, so is not shown> + +/* Open PGPLOT using the device given by environment variable + PGPLOT_DEV and check for success. */ +if( cpgbeg( 0, " ", 1, 1 ) == 1 ) { + +/* Clear the screen and ensure equal scales on both axes. */ + cpgpage(); + cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f ); + +/* Obtain the extent of the plotting area (not strictly necessary for + PGPLOT, but possibly for other graphics systems). From this, derive + the display scale in graphics units per pixel so that the image + will fit within the display area. */ + cpgqwin( &x1, &x2, &y1, &y2 ); + xscale = ( x2 - x1 ) / nx; + yscale = ( y2 - y1 ) / ny; + scale = ( xscale < yscale ) ? xscale : yscale; + +/* Calculate the extent of the area in graphics units that the image + will occupy, so as to centre it within the display area. */ + xleft = 0.5f * ( x1 + x2 - nx * scale ); + xright = 0.5f * ( x1 + x2 + nx * scale ); + ybottom = 0.5f * ( y1 + y2 - ny * scale ); + ytop = 0.5f * ( y1 + y2 + ny * scale ); + +/* Set up a PGPLOT coordinate transformation matrix and display the + image data as a grey scale map (these details are specific to + PGPLOT). */ + { + float tr[] = { xleft - 0.5f * scale, scale, 0.0f, + ybottom - 0.5f * scale, 0.0f, scale }; + cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr ); + } + +/* BEGINNING OF AST BIT */ +/* ==================== */ +/* Store the locations of the bottom left and top right corners of the + region used to display the image, in graphics coordinates. */ + { + float gbox[] = { xleft, ybottom, xright, ytop }; + +/* Similarly, store the locations of the image's bottom left and top + right corners, in pixel coordinates -- with the first pixel centred + at (1,1). */ + double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 }; + +/* Create a Plot, based on the FrameSet associated with the + image. This attaches the Plot to the graphics surface so that it + matches the displayed image. Specify that a complete set of grid + lines should be drawn (rather than just coordinate axes). */ + plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" ); + } + +/* Optionally, we can now set other Plot attributes to control the + appearance of the grid. The values assigned here use the + colour/font indices defined by the underlying graphics system. */ + astSet( plot, "Colour(grid)=2, Font(textlab)=3" ); + +/* Use the Plot to draw the coordinate grid. */ + astGrid( plot ); + + <maybe some more AST graphics here> + +/* Annul the Plot when finished (or use the astBegin/astEnd technique + shown earlier). */ + plot = astAnnul( plot ); + +/* END OF AST BIT */ +/* ============== */ + +/* Close down the graphics system. */ + cpgend(); +} +\end{terminalv} +\normalsize + +Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a +displayed image, you may also use it to generate further graphical +output of your own, specified in the image's world coordinate system +(such as markers to represent astronomical objects, annotation, +\emph{etc.}). There is also a range of Plot attributes which gives +control over most aspects of the output's appearance. For details of +the facilities available, see \secref{ss:plots} and the description of +the Plot class in \appref{ss:classdescriptions}. + +For details of how to build a graphics program which uses PGPLOT, see +\secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in +\appref{ss:commanddescriptions}. + +\subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid} + +Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid +(\secref{ss:howtoplotgrid}), it is a simple matter to change things so +that the grid represents a different celestial coordinate system. For +example, after creating the Plot with \htmlref{astPlot}{astPlot}, you could use: + +\small +\begin{terminalv} +astSet( plot, "System=Galactic" ); +\end{terminalv} +\normalsize +or: +\small +\begin{terminalv} +astSet( plot, "System=FK5, Equinox=J2010" ); +\end{terminalv} +\normalsize + +and any axes and/or grid drawn subsequently would represent the new +celestial coordinate system you specified. Note, however, that this +will only work if the original grid represented celestial coordinates +of some kind (see \secref{ss:howtotestforcelestial} for how to +determine if this is the case\footnote{Note that the methods applied +to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not, +you will get an error message. + +For more information about the celestial coordinate systems available, +see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in +\appref{ss:attributedescriptions}. + +\subsection{\ldots Give a User Control Over the Appearance of a Plot} + +The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the +graphical output it produces (\secref{ss:howtoplotgrid} and +\secref{ss:howtoswitchgrid}) can easily be extended to allow the user +of a program complete control over such matters. + +For instance, if the file ``plot.config'' contains a series of +plotting options in the form of Plot attribute assignments (see below +for an example), then we could create a Plot and implement these +assignments before producing the graphical output as follows: + +\small +\begin{terminalv} +#include <stdio.h> +#define MAXCHARS 120 +FILE *stream; +char line[ MAXCHARS + 2 ]; +int base; + +... + +/* Create a Plot and define the default appearance of the graphical + output it will produce. */ +plot = astPlot( wcsinfo, gbox, pbox, + "Grid=1, Colour(grid)=2, Font(textlab)=3" ); + +/* Obtain the value of any Plot attributes we want to preserve. */ +base = astGetI( plot, "Base" ); + +/* Open the plot configuration file, if it exists. Read each line of + text and use it to set new Plot attribute values. Close the file + when done. */ +if ( stream = fopen( "plot.config", "r" ) ) { + while ( fgets( line, MAXCHARS + 2, stream ) ) astSet( plot, "%s", line ); + close( stream ); +} + +/* Restore any attribute values we are preserving. */ +astSetI( plot, "Base", base ); + +/* Produce the graphical output (e.g.). */ +astGrid( plot ); +\end{terminalv} +\normalsize + +Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved +so that the user cannot change it. This is because graphical output +will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe +the plotting surface to which we attached the Plot when we created it. + +The arrangement shown above allows the contents of the ``plot.config'' +file to control most aspects of the graphical output produced +(including the coordinate system used; the colour, line style, +thickness and font used for each component; the positioning of axes +and tick marks; the precision, format and positioning of labels; +\emph{etc.}) \emph{via} assignments of the form: + +\small +\begin{terminalv} +System=Galactic, Equinox = 2001 +Border = 1, Colour( border ) = 1 +Colour( grid ) = 2 +DrawAxes = 1 +Colour( axes ) = 3 +Digits = 8 +Labelling = Interior +\end{terminalv} +\normalsize + +For a more sophisticated interface, you could obviously perform +pre-processing on this input---for example, to translate words like +``red'', ``green'' and ``blue'' into colour indices, to permit +comments and blank lines, \emph{etc.} + +For a full list of the attributes that may be used to control the +appearance of graphical output, see the description of the Plot class +in \appref{ss:classdescriptions}. For a complete description of each +individual attribute (\emph{e.g.}\ those above), see the attribute's +entry in \appref{ss:attributedescriptions}. + +\cleardoublepage +\section{\label{ss:primer}An AST Object Primer} + +The AST library deals throughout with entities called Objects and a +basic understanding of how to handle these is needed before you can +use the library effectively. If you are already familiar with an +object-oriented language, such as C$++$, few of the concepts should +seem new to you. Be aware, however, that AST is designed to be used +\emph{via} fairly conventional C and Fortran interfaces, so some +things have to be done a little differently. + +If you are not already familiar with object-oriented programming, then +don't worry---we will not emphasise this aspect more than is necessary +and will not assume any background knowledge. Instead, this section +concentrates on presenting all the fundamental information you will +need, explaining how AST Objects behave and how to manipulate them +from conventional C programs. + +If you like to read documents from cover to cover, then you can +consider this section as an introduction to the programming techniques +used in the rest of the document. Otherwise, you may prefer to skim +through it on a first reading and return to it later as reference +material. + +\subsection{AST Objects} + +An AST \htmlref{Object}{Object} is an entity which is used to store information and +Objects come in various kinds, called \emph{classes}, according to the +sort of information they hold. Throughout this section, we will make +use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to +illustrate many of the basic concepts. + +A ZoomMap is an Object that contains a recipe for converting +coordinates between two hypothetical coordinate systems. It does this +by multiplying all the coordinate values by a constant called the +\emph{\htmlref{Zoom}{Zoom} factor}. A ZoomMap is a very simple Object which exists +mainly for use in examples. It allows us to illustrate the ways in +which Objects are manipulated and to introduce the concept of a +\htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental +to the way the AST library works. + +\subsection{\label{ss:objectcreation}Object Creation and Pointers} + +Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very +simply as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstZoomMap *zoommap; + +... + +zoommap = astZoomMap( 2, 5.0, "" ) +\end{terminalv} +\normalsize + +The first step is to include the header file ``ast.h'' which declares +the interface to the AST library. We then declare a pointer of type +AstZoomMap$*$ to receive the result and invoke the function \htmlref{astZoomMap}{astZoomMap} +to create the ZoomMap. The pattern is the same for all other classes +of AST \htmlref{Object}{Object}---you simply prefix ``ast'' to the class name to obtain +the function that creates the Object and prefix ``Ast'' to obtain the +type of the returned pointer. + +These functions are called \emph{constructor functions}, or simply +\emph{constructors} (you can find an individual description of all AST +functions in \appref{ss:functiondescriptions}) and the arguments +passed to the constructor are used to initialise the new Object. In +this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we +are going to work in a 2-dimensional +space) and 5.0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a C +double value. We will return to the final argument, an empty string, +shortly (\secref{ss:attributeinitialisation}). + +The value returned by the constructor is termed an \emph{Object pointer} +or, in this case, a \emph{ZoomMap pointer} and is used to refer to the +Object. You perform all subsequent operations on the Object by +passing this pointer to other AST functions. + +\subsection{\label{ss:objecthierarchy}The Object Hierarchy} + +Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it +relates to other kinds of \htmlref{Object}{Object} before investigating what we can do +with it. + +We have so far indicated that a ZoomMap is a kind of Object and have +also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements +can be represented very simply using the following hierarchy: + +\small +\begin{terminalv} +Object + Mapping + ZoomMap +\end{terminalv} +\normalsize + +which is a way of stating that a ZoomMap is a special class of +Mapping, while a Mapping, in turn, is a special class of Object. This +is exactly like saying that an Oak is a special form of Tree, while a +Tree, in turn, is a special form of Plant. This may seem almost +trivial, but before you turn to read something less dull, be assured +that it is a very important idea to keep in mind in what follows. + +If we look at some of the other Objects used by the AST library, we +can see how these are all related in a similar way (don't worry about +what they do at this stage): +\label{ss:mappinghierarchy} + +\small +\begin{terminalv} +Object + Mapping + Frame + FrameSet + Plot + UnitMap + ZoomMap + Channel + FitsChan + XmlChan +\end{terminalv} +\normalsize + +Notice that there are several different types of Mapping available +(\emph{i.e.}\ there are classes of Object indented beneath the +``Mapping'' heading) and, in addition, other types of Object which are +not Mappings---Channels for instance (which are at the same +hierarchical level as Mappings). + +The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we +will not discuss in detail until \secref{ss:plots}). As you can see, a +Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and, +like everything else, ultimately an Object. + +What this means is that you can use a Plot not only for its own +specialised behaviour, but also whenever any of these other +less-specialised classes of Object is called for. The general rule is +that an Object of a particular class may substitute for any of the +classes appearing above it in this hierarchy. The Object is then said +to \emph{inherit} the behaviour of these higher classes. We can +therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object +is called for. + +Sometimes, this can lead to some spectacular short-cuts by avoiding +the need to break large Objects down in order to access their +components. With some practice and a little lateral thinking you +should soon be able to spot opportunities for this. + +You can find the full \emph{class hierarchy}, as this is called, for +the AST library in \appref{ss:classhierarchy} and you may need to +refer to it occasionally until you are familiar with the classes you +need to use. + +\subsection{\label{ss:displayingobjects}Displaying Objects} + +Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier +(\secref{ss:objectcreation}) and examine what it's made of. +There is a function for doing this, called \htmlref{astShow}{astShow}, which is provided +mainly for looking at Objects while you are debugging programs. + +If you consult the description of astShow in +\appref{ss:functiondescriptions}, you will find that it takes a +pointer to an \htmlref{Object}{Object} (of type AstObject$*$) as its argument. Although +we have only a ZoomMap pointer available, this is not a problem. If +you refer to the brief class hierarchy described above +(\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an +Object, albeit a specialised one, so it inherits the properties of all +Objects and can be substituted wherever an Object is required. We can +therefore pass our ZoomMap pointer directly to astShow, as follows: + +\small +\begin{terminalv} +astShow( zoommap ); +\end{terminalv} +\normalsize + +The output from this will appear on the standard output stream and +should look like the following: + +\small +\begin{terminalv} +Begin ZoomMap + Nin = 2 +IsA Mapping + Zoom = 5 +End ZoomMap +\end{terminalv} +\normalsize + +Here, the ``Begin'' and ``End'' lines mark the beginning and end of +the ZoomMap, while the values 2 and 5 are simply the values we +supplied to initialise it (\secref{ss:objectcreation}). These have +been given simple names to make them easy to refer to. + +The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line +between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a +property shared by all Mappings, so the ZoomMap has inherited this +from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however, +is specific to a ZoomMap and isn't shared by other kinds of Mappings. + +\subsection{\label{ss:gettingattributes}Getting Attribute Values} + +We saw above (\secref{ss:displayingobjects}) how to display the +internal values of an \htmlref{Object}{Object}, but what about accessing these values +from a program? Not all internal Object values are accessible in this +way, but many are. Those that are, are called \emph{attributes}. A +description of all the attributes used by the AST library can be found +in \appref{ss:attributedescriptions}. + +Attributes come in several data types (character string, integer, +boolean and floating point) and there is a standard way of obtaining +their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin} +attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as +follows: + +\small +\begin{terminalv} +int nin; + +... + +nin = astGetI( zoommap, "Nin" ); +\end{terminalv} +\normalsize + +Here, the function astGetI is used to extract the attribute value by +giving it the ZoomMap pointer and the attribute name (attribute names +are not case sensitive, but we have used consistent capitalisation in +this document in order to identify them). Remember to use the +``ast.h'' header file to include the function prototype. + +If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably +have used astGetD instead, this being a double version of the same +function, for example: + +\small +\begin{terminalv} +double zoom; + +... + +zoom = astGetD( zoommap, "Zoom" ); +\end{terminalv} +\normalsize + +However, we could equally well have read the Nin value as double, or +the Zoom value as an integer, or whatever we wanted. + +The data type you want returned is specified simply by replacing the +final character of the astGetX function name with C~(character +string), D~(double), F~(float), I~(int) or L~(long). If possible, the +value is converted to the type you want. If not, an error message will +result. Note that all floating point values are stored internally as +double, and all integer values as int. Boolean values are also stored +as integers, but only take the values 1 and 0 (for true/false). + +\subsection{\label{ss:settingattributes}Setting Attribute Values} + +Some attribute values are read-only and cannot be altered after an +\htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing +the number of coordinates) is like this. It is defined when the +ZoomMap is created, but cannot then be altered. + +Other attributes, however, can be modified whenever you want. A +ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this +could be done simply as follows: + +\small +\begin{terminalv} +astSetD( zoommap, "Zoom", 99.6 ); +\end{terminalv} +\normalsize + +which sets the value to 99.6. As when getting an attribute value +(\secref{ss:gettingattributes}), you have a choice of which data type +you will use to supply the new value. For instance, you could use an +integer value, as in: + +\small +\begin{terminalv} +astSetI( zoommap, "Zoom", 99 ); +\end{terminalv} +\normalsize + +and the necessary data conversion would occur. You specify the data +type you want to supply simply by replacing the final character of the +astSetX function name with C~(character string), D~(double), +F~(float), I~(int) or L~(long). Setting a boolean attribute to any +non-zero integer causes it to take the value 1. + +An alternative way of setting attribute values for Objects is to use +the \htmlref{astSet}{astSet} function (\emph{i.e.}\ with no final character specifying a +data type). In this case, you supply the attribute values in a +character string. The big advantage of this method is that you can +assign values to several attributes at once, separating them with +commas. This also reads more naturally in programs. For example: + +\small +\begin{terminalv} +astSet( zoommap, "Zoom=99.6, Report=1" ); +\end{terminalv} +\normalsize + +would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute +(about which more shortly---\secref{ss:transforming}). You don't really +have to worry about data types with this method, as any character +representation will do. Note, when using astSet, a +literal comma may be included in an attribute value by enclosed the value in +quotation marks: +\small +\begin{terminalv} + astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' ); +\end{terminalv} +\normalsize + +Another attractive feature of astSet is that you can build the +character string which contains the attribute settings in the same way +as when using the C run time library ``printf'' function. This is most +useful when the values you want to set are held in other +variables. For example: + +\small +\begin{terminalv} +double zoom = 99.6; +int report = 1; + +... + +astSet( zoommap, "Zoom=%g, Report=%d", zoom, report ); +\end{terminalv} +\normalsize + +would replace the ``\%'' conversion specifications by the values +supplied as additional arguments. Any number of additional arguments +may be supplied and the formatting rules are exactly the same as for +the C ``printf'' family of functions. This is a very flexible +technique, but does contain one pitfall: + +\begin{quote} +\textbf{Pitfall.} The default precision used by ``printf'' (and astSet) +for floating point values is only 6 decimal digits, corresponding +approximately to float on most machines, whereas the AST library +stores such values internally as doubles. You should be careful to +specify a larger precision (such as DBL\_DIG, as defined in +$<$float.h$>$) when necessary. For example: + +\small +\begin{terminalv} +#include <float.h> + +... + +astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value ); +\end{terminalv} +\normalsize +\end{quote} + +Substituted strings may contain commas and this is a useful way of +assigning such strings as attribute values without the comma being +interpreted as an assignment separator, for example: + +\small +\begin{terminalv} +astSet( object, "Attribute=%s", "A string, containing a comma" ); +\end{terminalv} +\normalsize + +This is equivalent to using astSetC and one of these two methods +should always be used when assigning string attribute values which +might potentially contain a comma (\emph{e.g.}\ strings obtained from +an external source). However, you should not attempt to use astSet to +substitute strings that contain newline characters, since these are +used internally as separators between adjacent attribute assignments. +\label{ss:attributeinitialisation} + +Finally, a very convenient way of setting attribute values is to do so +at the same time as you create an Object. Every Object constructor +function has a final character string argument which allows you to do +this. Although you can simply supply an empty string, it is an ideal +opportunity to initialise the Object to have just the attributes you +want. For example, we might have created our original ZoomMap with: + +\small +\begin{terminalv} +zoommap = astZoomMap( 2, 5.0, "Report=1" ); +\end{terminalv} +\normalsize + +and it would then start life with its Report attribute set to 1. +The ``printf''-style substitution described above may also be used +here. + +\subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes} + +You can use the astGetX family of functions +(\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute +at any time, regardless of whether a value has previously been set for +it. If no value has been set, the AST library will generate a suitable +default value. + +Often, the default value of an attribute will not simply be trivial +(zero or blank) but may involve considerable processing to +calculate. Wherever possible, defaults are designed to be real-life, +sensible values that convey information about the state of the +Object. In particular, they may often be based on the values of other +attributes, so their values may change in response to changes in these +other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a +little too simple to show this behaviour, but we will meet it later +on. + +An attribute that returns a default value in this way is said to be +\emph{un-set}. Conversely, once an explicit value has been assigned to +an attribute, it becomes \emph{set} and will always return precisely +that value, never a default. + +The distinction between set and un-set attributes is important and +affects the behaviour of several key routines in the AST library. You +can test if an attribute is set using the function \htmlref{astTest}{astTest}, which +returns a boolean (integer) result, as in: + +\small +\begin{terminalv} +if ( astTest( zoommap, "Report" ) ) { + <the Report attribute is set> +} +\end{terminalv} +\normalsize + + +Once an attribute is set, you can return it to its un-set state using +\htmlref{astClear}{astClear}. The effect is as if it had never been set in the first +place. For example: + +\small +\begin{terminalv} +astClear( zoommap, "Report" ); +\end{terminalv} +\normalsize + +would ensure that the default value of the \htmlref{Report}{Report} attribute is used +subsequently. + +%\subsection{TBW--Handling Character Attributes} + +\subsection{\label{ss:transforming}Transforming Coordinates} + +We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show +what it is really for. Here, we will also encounter a routine that is +a little more fussy about the type of pointer it will accept. + +The purpose of a ZoomMap is to multiply coordinates by a constant zoom +factor. To witness this in action, we will first set the \htmlref{Report}{Report} +attribute for our ZoomMap to a non-zero value: + +\small +\begin{terminalv} +astSet( zoommap, "Report=1" ); +\end{terminalv} +\normalsize + +This boolean (integer) attribute, which is present in all Mappings +(and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all +coordinate values that the Mapping converts. It is not a good idea to +leave this feature turned on in a finished program, but it can save a +lot of work during debugging. + +Our next step is to set up some coordinates for the ZoomMap to work +on, using two arrays ``xin'' and ``yin'', and two arrays to receive +the transformed coordinates, ``xout'' and ``yout''. Note that these +are arrays of double, as are all coordinate data processed by the AST +library: + +\small +\begin{terminalv} +double xin[ 10 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 }; +double yin[ 10 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0 }; +double xout[ 10 ]; +double yout[ 10 ]; +\end{terminalv} +\normalsize + +We will now use the function \htmlref{astTran2}{astTran2} to transform the input +coordinates. This is the most commonly-used (2-dimensional) coordinate +transformation function. If you look at its description in +\appref{ss:functiondescriptions}, you will see that it requires a +pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer, +as we could with the functions discussed previously. If we passed it a +pointer to an inappropriate Object, an error message would result. + +Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we +can use it with astTran2 to transform our coordinates, as follows: + +\small +\begin{terminalv} +astTran2( zoommap, 10, xin, yin, 1, xout, yout ); +\end{terminalv} +\normalsize + +Here, 10 is the number of points we want to transform and the fifth +argument value of 1 indicates that we want to transform in the +\emph{forward} direction (from input to output). + +Because our ZoomMap's Report attribute is set to 1, this will cause +the effects of the ZoomMap on the coordinates to be displayed on the +standard output stream: + +\small +\begin{terminalv} +(0, 0) --> (0, 0) +(1, 2) --> (5, 10) +(2, 4) --> (10, 20) +(3, 6) --> (15, 30) +(4, 8) --> (20, 40) +(5, 10) --> (25, 50) +(6, 12) --> (30, 60) +(7, 14) --> (35, 70) +(8, 16) --> (40, 80) +(9, 18) --> (45, 90) +\end{terminalv} +\normalsize + +This shows the coordinate values of each point both before and after +the ZoomMap is applied. You can see that each coordinate value has +been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute +value. The transformed coordinates are now stored in the ``xout'' and +``yout'' arrays. + +If we wanted to transform in the opposite direction, we need simply +change the fifth argument of astTran2 from 1 to 0. We can also feed +the output coordinates from the above back into the function: + +\small +\begin{terminalv} +astTran2( zoommap, 10, xout, yout, 0, xin, yin ); +\end{terminalv} +\normalsize + +The output would then look like: + +\small +\begin{terminalv} +(0, 0) --> (0, 0) +(5, 10) --> (1, 2) +(10, 20) --> (2, 4) +(15, 30) --> (3, 6) +(20, 40) --> (4, 8) +(25, 50) --> (5, 10) +(30, 60) --> (6, 12) +(35, 70) --> (7, 14) +(40, 80) --> (8, 16) +(45, 90) --> (9, 18) +\end{terminalv} +\normalsize + +This is termed the \emph{inverse} transformation (we have converted +from output to input) and you can see that the original coordinates +have been recovered by dividing by the Zoom factor. + +\subsection{\label{ss:annullingpointers}Managing Object Pointers} + +So far, we have looked at creating Objects and using them in various +simple ways but have not yet considered how to get rid of them again. + +Every \htmlref{Object}{Object} consumes various computer resources (principally memory) +and should be disposed of when it is no longer required, so as to free +up these resources. One way of doing this (not necessarily the +best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once +you have finished with it, using \htmlref{astAnnul}{astAnnul}. For example: + +\small +\begin{terminalv} +zoommap = astAnnul( zoommap ); +\end{terminalv} +\normalsize + +This indicates that you have finished with the pointer. Since astAnnul +always returns the null value AST\_\_NULL (as defined in ``ast.h''), +the recommended way of using it, as here, is to assign the returned +value to the pointer being annulled. This ensures that any attempt to +use the pointer again will generate an error message. + +In general, this process may not delete the Object, because there may +still be other pointers associated with it. However, each Object +maintains a count of the number of pointers associated with it and +will be deleted if you annul the final pointer. Using astAnnul +consistently will therefore ensure that all Objects are disposed of at +the correct time. You can determine how many pointers are associated +with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute. + +\subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End} + +The use of \htmlref{astAnnul}{astAnnul} (\secref{ss:annullingpointers}) is not completely +foolproof, however. Consider the following: + +\small +\begin{terminalv} +astShow( astZoomMap( 2, 5.0, "" ) ); +\end{terminalv} +\normalsize + +This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output +(\secref{ss:displayingobjects}). Using function invocations as +arguments to other functions in this way is very convenient because it +avoids the need for intermediate pointer variables. However, the +pointer generated by \htmlref{astZoomMap}{astZoomMap} is still active, and since we have not +stored its value, we cannot use astAnnul to annul it. The ZoomMap will +therefore stay around until the end of the program. + +A simple way to avoid this problem is to enclose all use of AST +functions between invocations of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}, for example: + +\small +\begin{terminalv} +astBegin; +astShow( astZoomMap( 2, 5.0, "" ) ); +astEnd; +\end{terminalv} +\normalsize + +When the expansion of astEnd (which is a macro) executes, every \htmlref{Object}{Object} +pointer created since the previous use of astBegin (also a macro) is +automatically annulled and any Objects left without pointers are +deleted. This provides a simple solution to managing Objects and their +pointers, and allows you to create Objects very freely without needing +to keep detailed track of each one. Because this is so convenient, we +implicitly assume that astBegin and astEnd are used in most of the +examples given in this document. Pointer management is not generally +shown explicitly unless it is particularly relevant to the point being +illustrated. + +If necessary, astBegin and astEnd may be nested, like blocks delimited +by ``\{\ldots\}'' in C, to define a series of AST pointer +contexts. Each use of astEnd will then annul only those Object +pointers created since the matching use of astBegin. + +\subsection{Exporting, Importing and Exempting AST Pointers} +The \htmlref{astExport}{astExport} function allows you to export particular pointers from +one AST context (\secref{ss:contexts}) to the next outer one, as +follows: + +\small +\begin{terminalv} +astExport( zoommap ); +\end{terminalv} +\normalsize + +This would identify the pointer stored in ``zoommap'' as being required +after the end of the current AST context. It causes any pointers +nominated in this way to survive the next use of \htmlref{astEnd}{astEnd} (but only one +such use) unscathed, so that they are available to the next outer +context. This facility is not needed often, but is invaluable when +the purpose of your \htmlref{astBegin}{astBegin}\ldots astEnd block is basically to +generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting +that pointer out. + + +The \htmlref{astImport}{astImport} routine can be used in a similar manner to import a +pointer into the current context, so that it is deleted when the current +context is closed using astEnd. + +Sometimes, you may also want to exempt a pointer from all the effects +of AST contexts. You should not need to do this often, but it will +prove essential if you ever need to write a library of functions that +stores AST pointers as part of its own internal data. Without some +form of exemption, the caller of your routines could cause the +pointers you have stored to be annulled---thus corrupting your +internal data---simply by using astEnd. To avoid this, you should use +\htmlref{astExempt}{astExempt} on each pointer that you store, for example: + +\small +\begin{terminalv} +astExempt( zoommap ); +\end{terminalv} +\normalsize + +This will prevent the pointer being affected by any subsequent use of +astEnd. Of course, it then becomes your responsibility to annul this +pointer (using \htmlref{astAnnul}{astAnnul}) when it is no longer required. + + +\subsection{AST Objects within Multi-threaded Applications} + +When the AST library is built from source, the build process checks to +see if the POSIX threads library (``\texttt{pthreads}'') is available. If so, +appropriate \texttt{pthreads} calls are inserted into the AST source code to +ensure that AST is thread-safe, and the AST\_\_THREADSAFE macro (defined +in the ``ast.h'' header file) is set to ``\texttt{1}''. If the \texttt{pthreads} +library cannot be found when AST is built, a working version of the AST +library will still be created, but it will not be thread-safe. In this +case the AST\_\_THREADSAFE macro will be set to ``\texttt{0}'' in ast.h. The +rest of this section assumes that the thread-safe version of AST is being +used. + +Note, some AST functions call externally specified functions (\emph{e.g.} +the source and sink functions used by the \htmlref{Channel}{Channel} class or the graphics +primitives functions used by the \htmlref{Plot}{Plot} class). AST does not know whether +such functions are thread-safe or not. For this reason, invocations of these +functions within a multi-threaded environment are serialised using a mutex +in order to avoid two or more threads executing an external function +simultaneously. + +If an application uses more than one thread, the possibility arises that +an \htmlref{Object}{Object} created by one thread may be accessed by another thread, potentially +simultaneously. If any of the threads modifies any aspect of the Object, +this could lead to serious problems within the other threads. For this +reason, some restrictions are placed on how Objects can be used in a +multi-threaded application. + +\subsubsection{Locking AST Objects for Exclusive Use} +The basic restriction is that a thread can only access Objects that it +has previously locked for its own exclusive use. If a thread attempts to +access any \htmlref{Object}{Object} that it has not locked, an error is reported. + +The \htmlref{astAnnul}{astAnnul} function is the one exception to this restriction. Pointers +for Objects not currently locked by the calling thread can be annulled +succesfully using astAnnul. This means that a thread that has finished +with an Object pointer can unlock the Object by passing the pointer to +\htmlref{astUnlock}{astUnlock} (so that other threads can use the Object via their own cloned +pointers), and can then annul the pointer using astAnnul. Note, however, +that an error will be reported by astAnnul if the supplied pointer has +been locked by another thread using \htmlref{astLock}{astLock}. + +When an Object is created, it is initially locked by the calling thread. +Therefore a thread does not need to lock an Object explicitly if it was +created in the same thread. + +If the Object pointer is then passed to another thread, the first thread +must unlock the Object using astUnlock and the second thread must then lock +it using astLock. + +If a thread attempts to lock an Object that is already locked by another +thread, it can choose to report an error immediately or to wait until the +Object is available. + +The \htmlref{astThread}{astThread} function can be used to determine whether an Object is +locked by the running thread, locked by another thread, or unlocked. + +If two or more threads need simultaneous access to an Object, a deep copy +of the Object should be taken for each thread, using \htmlref{astCopy}{astCopy}, and then +the copies should be unlocked and passed to the othe threads, which +should then lock them. Note, if a thread modifies the Object, the +modification will have no effect on the other threads, because the Object +copies are independent of each other. + +\subsubsection{AST Pointer Contexts} + +Each thread maintains its own set of nested AST contexts, so when \htmlref{astEnd}{astEnd} +is called, only Objects that are locked by the current thread will +be annulled. + +If an \htmlref{Object}{Object} is unlocked by a thread using \htmlref{astUnlock}{astUnlock}, it is exempted from +context handling so that subsequent invocations of astEnd will not cause it +to be annulled (this is similar to using \htmlref{astExempt}{astExempt} on the Object). When the +Object is subsequently locked by another thread using \htmlref{astLock}{astLock}, it will be +imported into the context that was active when astLock was called. + + + +\subsection{\label{ss:copyingobjects}Copying Objects} + +The AST library makes extensive use of pointers, not only for +accessing Objects directly, but also as a means of storing Objects +inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to +hold collections of other Objects). Rather than copy an Object in its +entirety, a pointer to the interior Object is simply stored in the +enclosing Object. + +This means that Objects may frequently not be completely independent +of each other because, for instance, they both contain pointers to the +same sub-Object. In this situation, changing one Object (say assigning +an attribute value) may affect the other one \emph{via} the common +Object. + +It is difficult to describe all cases where this may happen, so you +should always be alert to the possibility. Fortunately, there is a +simple solution. If you require two Objects to be independent, then +simply use \htmlref{astCopy}{astCopy} to make a copy of one, \emph{e.g.}: + +\small +\begin{terminalv} +AstZoomMap *zoommap1, *zoommap2; + +... + +zoommap2 = astCopy( zoommap1 ); +\end{terminalv} +\normalsize + +This process will create a true copy of any Object and return a +pointer to the copy. This copy will not contain any pointers to any +component of the original Object (everything is duplicated), so you +can then modify it safely, without fear of affecting either the +original or any other Object. + +%\subsection{TBW - Inheritance} + +\subsection{C Pointer Types} + +At this point it is necessary to confess to a small amount of +deception. So far, we have been passing \htmlref{Object}{Object} pointers to AST +functions in order to perform operations on those Objects. In fact, +however, what we were using were not true C functions at all, but +merely macros which invoke a related set of hidden functions with +essentially the same arguments. In practical terms, this makes very +little difference to how you use the functions, as we will continue to +call them.\footnote{About the only difference is that you cannot store +a pointer to an AST ``function'' in a variable and use the variable's +value to invoke that function again later.} + +The reason for this deception has to do with the rules for data typing +in C. Recall that most AST functions can be used to process Objects +from a range of different classes (\secref{ss:objecthierarchy}). In C, +this means passing different pointer types to the same function and +most C compilers will not permit this (at least, not without +grumbling) because it usually indicates a programming error. In AST, +however, it is perfectly safe if done properly. Some way is therefore +needed of circumventing the normal compiler checking. + +The normal way of doing this in C is with a cast. This approach +quickly becomes cumbersome, however, so we have adopted the strategy +of wrapping each function in a macro which applies the appropriate +cast for you. This means that you can pass pointers of any type to any +AST function. For example, in passing a \htmlref{ZoomMap}{ZoomMap} pointer to \htmlref{astShow}{astShow}: + +\small +\begin{terminalv} +AstZoomMap *zoommap; + +... + +zoommap = astZoomMap( 2, 5.0, "" ); +astShow( zoommap ); +\end{terminalv} +\normalsize + +we are exploiting this mechanism to avoid a compiler warning, because +the notional type of astShow's parameter is AstObject$*$ (not +AstZoomMap$*$). + +We must still guard against programming errors, however, so every +pointer's type is checked by the enclosing macro immediately before +any AST function executes. This allows pointer mis-matches (in the +more liberal AST sense---\emph{i.e.}\ taking account of the class +hierarchy, rather than the stricter C sense) to be detected at +run-time and a suitable error message will be reported. This message +should also identify the line where the error occurs. + +A similar strategy is used when pointers are returned by AST functions +(\emph{i.e.}\ as the function result). In this case the pointer is +cast to void$*$, although we retain the notional pointer type in the +function's documentation +(\emph{e.g.}\ \appref{ss:functiondescriptions}). This allows you to +assign function results to pointer variables without using an explicit +cast. For example, the \htmlref{astRead}{astRead} function returns an Object pointer, but +might be used to read (say) a ZoomMap as follows: + +\small +\begin{terminalv} +AstChannel *channel; +AstZoomMap *zoommap; + +... + +zoommap = astRead( channel ); +\end{terminalv} +\normalsize + +Strictly, there is a C pointer mis-match here, but it is ignored +because the operation makes perfect sense to AST. + +\textbf{There is an important exception to this, however, in that +constructor functions always return strongly-typed pointers.} What +we mean by this is that the returned pointer is never implicitly cast +to void$*$. You must therefore match pointer types when you initially +create an Object using its constructor, such as in the following: + +\small +\begin{terminalv} +AstZoomMap *zoommap; + +... + +zoommap = astZoomMap( 2, 5.0, "" ); +\end{terminalv} +\normalsize + +If the variable receiving the pointer is of a different type, an +appropriate cast should be used, as in: + +\small +\begin{terminalv} +AstMapping *mapping; + +... + +mapping = (AstMapping *) astZoomMap( 2, 5.0, "" ); +\end{terminalv} +\normalsize + +This is an encouragement for you to declare your pointer types +consistently, since this is of great benefit to anyone trying to +understand your software. + +Finally, we should also make one more small confession---AST pointers +are not really pointers at all. Although they behave like pointers, +the actual ``values'' stored are not the addresses of C data +structures. This means that you cannot de-reference an AST pointer to +examine the data within (although you can use astShow +instead---\secref{ss:displayingobjects}). This is necessary so that AST +pointers can be made unique even although several of them might +reference the same Object. + +\subsection{\label{ss:errordetection}Error Detection} + +If an error occurs in an AST function (for example, if you supply an +invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an +error message will be written to the standard error stream and the +function will immediately return. + +To indicate than an error has occurred, an AST \emph{error status} +value is used. This integer value is stored internally by AST and is +initially clear (\emph{i.e.}\ set to zero\footnote{We will assume +throughout that the ``OK'' value is zero, as it currently is. However, +a different value could, in principle, be used if the environment in +which AST is running requires it. This is why a simple interface is +provided to isolate you from the actual value of the error status.} +to indicate no error). If an error occurs, it becomes set to a +different \emph{error value}, which allows you to detect the error, as +follows: + +\small +\begin{terminalv} +zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" ); +if ( !astOK ) { + <an error has occurred> +} +\end{terminalv} +\normalsize + +The macro \htmlref{astOK}{astOK} is used to test whether the AST error status is still +OK. In this example it would not be, because we have attempted to set +a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not +have such an attribute. The actual value of the AST error status can +be obtained using the \htmlref{astStatus}{astStatus} macro, as follows: + +\small +\begin{terminalv} +int status; + +... + + +status = astStatus; +\end{terminalv} +\normalsize + +A consequence of the AST error status being set is that almost all AST +functions will subsequently cease to function and will instead simply +return without action. This means that you do not need to use astOK +to check for errors very frequently. Instead, you can usually simply +invoke a succession of AST functions. If an error occurs in any of +them, the following ones will do nothing and you can check for the +error at the end, for example: + +\small +\begin{terminalv} +astFunctionA( ... ); +astFunctionB( ... ); +astFunctionC( ... ); +if ( !astOK ) { + <an error has occurred> +} +\end{terminalv} +\normalsize + +There are, however, a few functions which do not adhere to this +general rule and which will attempt to execute if the AST error status +is set. These functions, such as \htmlref{astAnnul}{astAnnul}, are concerned with cleaning +up and recovering resources. For example, in the following: + +\small +\begin{terminalv} +zoommap = astZoomMap( 2, 5.0, "" ); + +astFunctionX( ... ); +astFunctionY( ... ); +astFunctionZ( ... ); + +zoommap = astAnnul( zoommap ); +if ( !astOK ) { + <an error has occurred> +} +\end{terminalv} +\normalsize + +astAnnul will execute normally in order to recover the resources +associated with the ZoomMap that was created earlier, regardless of +whether an error has occurred in any of the intermediate functions. +Functions which behave in this way are noted in the relevant +descriptions in \appref{ss:functiondescriptions}. + +If a serious error occurs, you will probably want to abort your +program, but sometimes you may want to recover and carry on. Because +very few AST functions will execute once the AST error status has been +set, you must first clear this status by using the \htmlref{astClearStatus}{astClearStatus} +macro, as follows: + +\small +\begin{terminalv} +astClearStatus; +\end{terminalv} +\normalsize + +This will restore the AST error status to its OK value, so that AST +functions execute normally again. + +Occasionally, you may also need to set the AST error status to an +explicit error value (see \secref{ss:channelsink} for an +example). This is done using \htmlref{astSetStatus}{astSetStatus} and can be used to +communicate to AST that an error has occurred in some other item of +software, for example: + +\small +\begin{terminalv} +int new_status; + +... + +astSetStatus( new_status ); +\end{terminalv} +\normalsize + +The effect is that most AST routines will subsequently return without +action, just as if an error had occurred within the AST library +itself. + +\subsection{Sharing the Error Status} + +In some software, it is usual to maintain a single integer error +status variable which is accessed by each function as it executes. If +an error occurs, this status variable is set and other functions can +detect this and take appropriate action. + +If you use AST in such a situation, it can be awkward to have a +separate internal error status used by AST functions alone. To remedy +this, AST is capable of sharing the error status variable used by any +other software, so long as they use the same conventions +(\emph{i.e.}\ a C int with the same ``OK'' value). To enable this +facility, you should pass the address of your status variable to +\htmlref{astWatch}{astWatch}, as follows: + +\small +\begin{terminalv} +int my_status; +int *old_address; + +... + +old_address = astWatch( &my_status ); +\end{terminalv} +\normalsize + +Henceforth, instead of using its own internal error status variable, +AST will use the one you supply, so that it can detect errors flagged +by other parts of your software. The address of the original error +status variable is returned by astWatch, so you can restore the +original behaviour later if necessary. + +Note that this facility is not available \emph{via} the Fortran +interface to the AST library. + +\cleardoublepage +\section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)} + +In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a +\htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its +input to its output and back again (\secref{ss:transforming}). We also +saw how its behaviour could be controlled by setting various +attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made +it display coordinate values as it transformed them. + +In this section, we will look at Mappings a bit more thoroughly and +explore the behaviour which is common to all the Mappings provided by +AST. This is good background for what follows, because many of the +Objects we discuss later will also turn out to be Mappings in various +disguises. + +\subsection{\label{ss:mappingclass}The Mapping Class} + +Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class +as a whole and some of the sub-classes it contains: + +\begin{terminalv} + Mapping + CmpMap + DssMap + GrismMap + IntraMap + LutMap + MathMap + MatrixMap + PermMap + PolyMap + SlaMap + SpecMap + TimeMap + UnitMap + WcsMap + ZoomMap + + Frame + <various types of Frame> +\end{terminalv} + +The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered +in detail in \secref{ss:frames}. We start by looking at the parent +class, Mapping. + +AST does not provide a function to create a basic Mapping +(\emph{i.e.}\ the astMapping constructor does not exist). This is +because the Mapping class itself is ``virtual'' and basic Mappings are +of no use in themselves. The Mapping class serves simply to contain +the various specialised Mappings that exist. +However, it provides more than just a convenient heading for them +because it bestows all classes of Mapping with common properties +(\emph{e.g.}\ attributes) and behaviour. By examining the Mapping +class, we are therefore examining the things that all other Mappings +have in common. + +\subsection{The Mapping Model} + +The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}. +It is a black box which you can supply with a set of coordinate values +in return for a set of transformed coordinates. The two sets are +termed \emph{input} and \emph{output} coordinates. You can also go +back the other way and transform output coordinates back into input +coordinates, as we saw in \secref{ss:transforming}. + +\subsection{Changing Attributes of a Mapping} + +Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter +used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an +attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each +coordinate is to be multiplied. These attribute values should be set when +the Mapping is created and should not be changed afterwards. Indeed, the +AST library will report an error if an attempt is made to change the +value of a Mapping attribute. This is because, once created, Mappings are +often later included within other objects such as FrameSets and CmpMaps. +This means that in general there could be many active references to a single +Mapping object within a program. Changing an attribute of the Mapping +via one particular reference (i.e pointer) would cause all the other +references to change too, with often undesirable or unpredictable +consequences. To avoid this, Mappings are considered \emph{immutable} in +most situations. The one exception is if the Mapping has not yet been +cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference +couint of one) - changing the attributes of such a Mapping is allowed, +and will not generate an error. + +Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and +can be changed at any time. + +\subsection{Input and Output Coordinate Numbers} + +In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to +represent a single point need not be the same as the number that comes +out. Often these numbers will be the same, and often they will both +equal 2 (because 2-dimensional coordinate systems are common), but +this needn't necessarily be the case. + +The number of coordinates required to specify an input point is +represented by the integer attribute \htmlref{Nin}{Nin} and the number required to +specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only +attributes common to all Mappings. Generally, their values are fixed +when a Mapping is created. + +In \secref{ss:objectcreation}, we saw how the Nin attribute for a +\htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function +\htmlref{astZoomMap}{astZoomMap} which created it. In this case, the Nout attribute was not +needed and it implicitly took the same value as Nin, but we could +have enquired about its value had we wanted, as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstZoomMap *zoommap; +int nout; + +... + +nout = astGetI( zoommap, "Nout" ); +\end{terminalv} +\normalsize + +\subsection{Forward and Inverse Transformations} + +We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates +either from input to output, or \emph{vice versa}. These are termed +its \emph{forward} and \emph{inverse} transformations. + +This statement was not quite accurate, however, because in general +Mappings are only \textbf{potentially} capable of working in both +directions. In practice, coordinate transformation may only be +feasible in one direction or the other because some functions are not +easily inverted (they may be multi-valued, for instance). Allowance +must be made for this, so each Mapping has two read-only boolean +(integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate +whether each transformation is available. + +A transformation is available if the corresponding attribute is +non-zero, otherwise it is not.\footnote{Most of the Mappings provided +by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can +behave otherwise.} If you enquire about the value of these attributes, +a value of 0 or 1 is returned. Attempting to use a Mapping to apply a +transformation which is not available will result in an error. + +\subsection{\label{ss:invertingmappings}Inverting Mappings} + +An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert} +flag. This is a boolean (integer) attribute that can be assigned a new +value at any time. If it is non-zero, it has the effect of +interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the +Mapping is then said to be \emph{inverted}. By default, the Invert +attribute is zero. + +There is no magic in this. There is no fancy arithmetic involved in +inverting mathematical functions, for instance. The Invert flag is +simply a switch that interchanges a Mapping's input and output +ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are +swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and +when you ask for what was once the forward transformation you get the +inverse transformation instead (and \emph{vice versa}). When you +return the Invert attribute to zero, or clear it, the Mapping returns +to its original behaviour. + +Often, the actual value of the Invert attribute is unimportant and you +simply wish to invert its boolean sense, so that what was the +Mapping's input becomes its output and \emph{vice versa}. This is most +easily accomplished using \htmlref{astInvert}{astInvert}, as follows: + +\small +\begin{terminalv} +AstMapping *mapping; + +... + +astInvert( mapping ); +\end{terminalv} +\normalsize + +If the Mapping you have happens to be the wrong way around, astInvert +allows you to correct the problem. + +\subsection{Finding the Rate of Change of a Mapping Output} +The +\htmlref{astRate}{astRate} +function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output +with respect to any Mapping input, at a given input position. The method +used produces good accuracy (typically a relative error of 10E-10 or +less) but may require the Mapping to be evaluated 100 or more times. +An estimate of the second derivative is also produced by this function. + + +\subsection{Reporting Coordinate Transformations} + +We have already seen (\secref{ss:transforming}) how the boolean +(integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the +operation of transforming a set of coordinates will result in a report +being written to standard output. This will display the coordinate +values before and after transformation. It can save considerable time +during program development by eliminating the need to add loops and +output statements to your program. + +In a finished program, however, you should be careful that the Report +attribute is not set to a non-zero value unless you want to see the +output (there may often be rather a lot of this!). To help prevent +unwanted output being produced by accident, the Report attribute is +unusual in that its value is not preserved when a Mapping is copied +using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). Instead, it reverts to its +default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to +zero when a Mapping is written out, \emph{e.g.}\ to a file using a +\htmlref{Channel}{Channel} (\secref{ss:channels}). + +%\subsection{TBW---More on Transforming Coordinates} + +\subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values} + +Even when coordinates can, in principle, be transformed in either +direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific +coordinate values cannot be handled. For example, the Mapping may be +mathematically intractable (\emph{e.g.}\ singular) in certain places, +or it may map a subset of one space on to another, so that some points +in one space are not represented in the other. Sky projections often +show this behaviour, since it is quite common to project only half of +the celestial sphere on to two dimensions, omitting points on the +opposite side of the sky. There are many other examples. + +To indicate when coordinates cannot be transformed, for whatever +reason, AST substitutes a special output coordinate value given by the +macro AST\_\_BAD (as defined in the ``ast.h'' header file). Before +making use of coordinates generated by any of the AST transformation +functions, therefore, you may need to check for the presence of this +value. + +Because coordinates with the value AST\_\_BAD can be generated in this +way, all other AST functions are also capable of recognising this +value and handling it appropriately. The coordinate transformation +functions do this by propagating any missing input coordinate +information through to their output. This means that if you supply +coordinates with the value AST\_\_BAD, the returned coordinates are +also likely to contain this value. Here, for example, is what happens +if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of +coordinates: + +\small +\begin{terminalv} +(0, 0) --> (0, 0) +(<bad>, 2) --> (<bad>, 10) +(2, 4) --> (10, 20) +(3, 6) --> (15, 30) +(4, <bad>) --> (20, <bad>) +(5, 10) --> (25, 50) +(<bad>, <bad>) --> (<bad>, <bad>) +(7, 14) --> (35, 70) +(8, 16) --> (40, 80) +(9, 18) --> (45, 90) +\end{terminalv} +\normalsize + +The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This +is a case of ``garbage in, garbage out'' but at least it's consistent +garbage that you can recognise! + +Note how the presence of the AST\_\_BAD value in one input dimension +does not necessarily result in the loss of information for all output +dimensions. Sometimes, such loss will be unavoidable, but in general +an attempt is made to preserve information as far as possible. The +exact behaviour will depend on the Mapping involved. + +\subsection{\label{ss:unitmapexample}Example---the UnitMap} + +The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its +purpose is simply to copy coordinate values, unaltered, from its input +to its output and \emph{vice versa}. + +A UnitMap has no additional attributes beyond those of a basic +Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are +specified by the first argument supplied to its constructor. For +example: + +\small +\begin{terminalv} +AstUnitMap *unitmap; + +... + +unitmap = astUnitMap( 2, "" ); +\end{terminalv} +\normalsize + +will create a UnitMap that copies 2-dimensional coordinates. Inverting +a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert} +attribute. + +The main use of a UnitMap is to allow a Mapping to be supplied when one +is required (as an argument to a function, for example) but you wish +it to leave coordinate values unchanged. + +\subsection{\label{ss:permmapexample}Example---the PermMap} + +The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met +previously. Its purpose is to change the order, or number, of +coordinates. It is also able to substitute fixed values for +coordinates. + +To illustrate its action, suppose our input coordinates are denoted by +($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output +coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore, +should rotate the coordinate values by one position. + +To create such a PermMap, we first set up two integer arrays. One of +these, ``outperm'', controls the selection of input coordinates for +use in the output and the other, ``inperm'', controls selection of +output coordinates for use in the input: + +\small +\begin{terminalv} +int outperm[ 4 ] = { 4, 1, 2, 3 }; +int inperm[ 4 ] = { 2, 3, 4, 1 }; +\end{terminalv} +\normalsize + +Note that the numbers we store in these arrays are the indices of the +coordinates that we want to select. We have chosen these so that the +forward and inverse transformations will perform complementary +permutations on the coordinates. + +The PermMap is then created by passing these arrays to its +constructor, as follows: + +\small +\begin{terminalv} +AstPermMap *permmap; + +... + +permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" ); +\end{terminalv} +\normalsize + +Note that we specify the number of input and output coordinates +separately, but set both to 4 in this example. The resulting PermMap +would have the following effect when used to transform coordinates: + +\begin{terminalv} +Forward: + (1, 2, 3, 4) --> (4, 1, 2, 3) + (2, 4, 6, 8) --> (8, 2, 4, 6) + (3, 6, 9, 12) --> (12, 3, 6, 9) + (4, 8, 12, 16) --> (16, 4, 8, 12) + (5, 10, 15, 20) --> (20, 5, 10, 15) + +Inverse: + (4, 1, 2, 3) --> (1, 2, 3, 4) + (8, 2, 4, 6) --> (2, 4, 6, 8) + (12, 3, 6, 9) --> (3, 6, 9, 12) + (16, 4, 8, 12) --> (4, 8, 12, 16) + (20, 5, 10, 15) --> (5, 10, 15, 20) +\end{terminalv} + +If the number of input and output coordinates are unequal so, also, +will be the size of the ``outperm'' and ``inperm'' arrays. This means, +however, that we cannot fill them with coordinate indices so that they +perform complementary permutations, because one transformation will +lose information (discard a coordinate) that the other cannot recover. +To give an example, consider the following: + +\small +\begin{terminalv} +int outperm[ 3 ] = { 4, 3, 2 }; +int inperm[ 4 ] = { -1, 3, 2, 1 }; +double con[ 1 ] = { 99.004 }; +\end{terminalv} +\normalsize + +In this case, the forward transformation will change +($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The +inverse transformation restores the original coordinate order, but has +no value to assign to the first coordinate. In this case, the number +entered in the ``inperm'' array is $-$1. + +This negative value indicates that the coordinate value should be +obtained by addressing the first element of the ``con'' array +(\emph{i.e.}\ element zero). This array, ignored in the previous +example, may then be used to supply a value for the missing +coordinate. + +The constructor function: + +\small +\begin{terminalv} +permmap = astPermMap( 4, inperm, 3, outperm, con, "" ); +\end{terminalv} +\normalsize + +will then create a PermMap with the following effect when used to +transform coordinates: + +\begin{terminalv} +Forward: + (1, 2, 3, 4) --> (4, 3, 2) + (2, 4, 6, 8) --> (8, 6, 4) + (3, 6, 9, 12) --> (12, 9, 6) + (4, 8, 12, 16) --> (16, 12, 8) + (5, 10, 15, 20) --> (20, 15, 10) + +Inverse: + (4, 3, 2) --> (99.004, 2, 3, 4) + (8, 6, 4) --> (99.004, 4, 6, 8) + (12, 9, 6) --> (99.004, 6, 9, 12) + (16, 12, 8) --> (99.004, 8, 12, 16) + (20, 15, 10) --> (99.004, 10, 15, 20) +\end{terminalv} + +The ``con'' array may contain more than one value if necessary and may +be addressed by both the ``inperm'' and ``outperm'' arrays using +coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the +first, second, third,~\emph{etc.}\ elements. + +If there is no suitable replacement value that can be supplied +\emph{via} the ``con'' array, a value of zero may be entered into the +``outperm'' and/or ``inperm'' arrays. This causes the value AST\_\_BAD +to be used for the affected coordinate (as defined in the ``ast.h'' +header file), thus indicating a missing coordinate value +(\secref{ss:badcoordinates}). + +The principle use for a PermMap lies in matching a coordinate system +to a data array where there is a choice of storage order for the data. +PermMaps are also useful for discarding unwanted coordinates so as to +reduce the number of dimensions, such as when selecting a ``slice'' +from a multi-dimensional array. + +\cleardoublepage +\section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)} + +We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The +Mappings we have considered so far have been atomic, in the sense that +they perform pre-defined elementary transformations. A CmpMap, +however, is a compound Mapping. In essence, it is a framework for +containing other Mappings and its purpose is to allow those Mappings +to work together in various combinations while appearing as a single +\htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is +determined by the other Mappings it contains. + +\subsection{\label{ss:seriescmpmap}Combining Mappings in Series} + +Consider a simple example based on two 2-dimensional coordinate +systems. Suppose that to convert from one to the other we must swap +the coordinate order and multiply both coordinates by 5, so that the +coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done +in two stages: + +\begin{enumerate} +\item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the +coordinate order. + +\item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both +coordinate values by the constant 5. +\end{enumerate} + +The PermMap and ZoomMap are then said to operate \emph{in series}, +because they are applied sequentially +(\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}). We can create a \htmlref{CmpMap}{CmpMap} +that applies these Mappings in series as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstCmpMap *cmpmap; +AstPermMap *permmap; +AstZoomMap *zoommap; + +... + +/* Create the individual Mappings. */ +{ + int inperm[ 2 ] = { 2, 1 }; + int outperm[ 2 ] = { 2, 1 }; + permmap = astPermMap( 2, inperm, 2, outperm, NULL, "" ); +} +zoommap = astZoomMap( 2, 5.0, "" ) + +/* Combine them in series. */ +cmpmap = astCmpMap( permmap, zoommap, 1, "" ); + +/* Annul the individual Mapping pointers. */ +permmap = astAnnul( permmap ); +zoommap = astAnnul( zoommap ); +\end{terminalv} +\normalsize + +Here, the third argument (1) of the constructor function \htmlref{astCmpMap}{astCmpMap} +indicates ``in series''. + +When used to transform coordinates in the forward direction, the +resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap) +and then the second one (the ZoomMap). When transforming in the +inverse direction, it will apply the second one (in the inverse +direction) and then the first one (also in the inverse direction). In +general, although not in this particular example, the order in which +the two component Mappings are supplied is significant. Clearly, also, +the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first +Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for +the second one. + +\subsection{Combining Mappings in Parallel} + +Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the +only way of combining them. The alternative, \emph{in parallel}, +involves applying the two Mappings at once but on different subsets of +the coordinate values. + +Consider, for example, a set of 3-dimensional coordinates and suppose +we wish to transform them by swapping the first two coordinate values +and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms +into ($x_2,x_1,5x_3$). Again, we can perform each of these steps +individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used +earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is +1-dimensional and the individual Mappings are applied in parallel +(\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}). + +Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple: + +\small +\begin{terminalv} +cmpmap = astCmpMap( permmap, zoommap, 0, "" ); +\end{terminalv} +\normalsize + +The only difference is that the third argument of \htmlref{astCmpMap}{astCmpMap} is now +zero, meaning ``in parallel''. + +As before, the order in which the two component Mappings are supplied +is significant. The first one acts on the lower-numbered input +coordinate values (however many it needs) and produces the +lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on +the higher-numbered input coordinates (however many remain) and +generates the remaining higher-numbered output coordinates. When the +CmpMap transforms coordinates in the inverse direction, both component +Mappings are applied to the same coordinates, but in the inverse +direction. + +Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings +(\emph{i.e.}\ the numbers of input and output coordinates) will sum to +give the Nin and Nout attributes of the overall CmpMap. + +\subsection{\label{ss:cmpmapcomponents}The Component Mappings} + +A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply +holds pointers to them. In the example above +(\secref{ss:seriescmpmap}), we were free to annul the individual +\htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held +internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount} +attribute) of each component Mapping by one. The individual components +are therefore not deleted by \htmlref{astAnnul}{astAnnul}, but retained until the CmpMap +itself is deleted and annuls the pointers it holds. Consistent use of +astAnnul (\secref{ss:annullingpointers}) and/or pointer contexts +(\secref{ss:contexts}) will therefore ensure that all Objects are +deleted at the appropriate time. + +Note that access to a CmpMap's component Mappings is not generally +available unless pointers to them are retained when the CmpMap is +created. If such pointers are retained, then subsequent modifications +to the individual components can be used to indirectly modify the +behaviour of the overall CmpMap. + +There is an important exception to this, however, because a CmpMap +retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its +components and uses these in order to ignore any subsequent external +changes. This means that you may invert either component Mapping +before inserting it into a CmpMap and need not worry if you un-invert +it again later. The CmpMap's behaviour will not be affected by the +later action. + +\subsection{\label{ss:complexcmpmap}Creating More Complex Mappings} + +Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can +substitute (\secref{ss:objecthierarchy}) as a component Mapping when +constructing a new CmpMap using \htmlref{astCmpMap}{astCmpMap}. This has the effect of +nesting one CmpMap inside another and opens up many new possibilities. +For example, combining three Mappings in series can be accomplished as +follows: + +\small +\begin{terminalv} +AstMapping *map1, *map2, *map3; + +... + +cmpmap = astCmpMap( map1, astCmpMap( map2, map3, 1, "" ), 1, "" ); +\end{terminalv} +\normalsize + +The way in which the individual component Mappings are grouped within +the nested CmpMaps is not usually important. + +A similar technique can be used to combine multiple Mappings in +parallel and, of course, mixed series and parallel combinations are +also possible (Figure~\ref{fig:complexcmpmap}). There is no built-in +limit to how many CmpMaps may be nested in this way, so this mechanism +provides an indefinitely extensible method of building complex +Mappings out of the elemental building blocks provided by AST. + +In practice, you might not need to construct such complex CmpMaps +yourself very frequently, but they will often be returned by AST +routines. Nested CmpMaps underlie the library's entire ability to +represent a wide range of different coordinate transformations. + +\subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images} + +Consider, as a practical example of CmpMaps, two images of the +sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from +pixel coordinates to a standard celestial coordinate system, say +FK5~(J2000.0). If we wish to inter-compare these images, we can do so +by using this celestial coordinate system to align them. That is, we +first convert from pixel coordinates in the first image into FK5 +coordinates and we then convert from FK5 coordinates into pixel +coordinates in the second image. + +If ``mapa'' and ``mapb'' are pointers to our two original Mappings, we +could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel +coordinates of the first and second images by combining these +Mappings, as follows: + +\small +\begin{terminalv} +AstCmpMap *alignmap; +AstMapping *mapa, *mapb; + +... + +astInvert( mapb ); +alignmap = astCmpMap( mapa, mapb, 1, "" ); +astInvert( mapb ); +\end{terminalv} +\normalsize + +Here, we have used \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}) to invert +``mapb'' before inserting it into the CmpMap because, as supplied, it +converted in the wrong direction. Afterwards, we invert it again to +return it to its original state. The CmpMap, however, will ignore this +subsequent change (\secref{ss:cmpmapcomponents}). + +The forward transformation of the resulting CmpMap will now transform +from pixel coordinates in the first image to pixel coordinates in the +second image, while its inverse transformation will convert in the +opposite direction. + +\subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings} + +While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing +arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it +unfortunately also provides an opportunity for representing simple +Mappings in complex ways. Sometimes, unnecessary complexity can be +difficult to avoid but can obscure important simplifications. + +Consider the example above (\secref{ss:cmpmapexample}), in which we +inter-related two images of the sky \emph{via} a CmpMap. If the two +images turned out to be simply offset from each other by a shift along +each pixel axis, then this approach would align them correctly, but it +would be inefficient. This is because it would introduce unnecessary +and expensive transformations to and from an intermediate celestial +coordinate system, whereas a simple shift of pixel origin would +suffice. + +Recognising that a simpler and more efficient solution exists +obviously requires a little more than simply joining two Mappings +end-to-end. We must also determine whether the resulting CmpMap is +more complex than it needs to be, \emph{i.e.}\ contains redundant +information. If it is, we then need a way to simplify it. + +The problem is not always just one of efficiency, however. Sometimes +we may also need to know something about the actual form a \htmlref{Mapping}{Mapping} +takes---\emph{i.e.}\ the nature of the operations it performs. +Unnecessary complexity can obscure this, but such complexity can +easily accumulate during normal data processing. + +For example, a Mapping that transforms pixel coordinates into +positions on the sky might be repeatedly modified as changes are made +to the shape and size of the image. Typically, on each occasion, +another Mapping will be concatenated to reflect what has happened to +the image. This could soon make it difficult to discern the overall +nature of the transformation from the complex CmpMap that +accumulates. If only shifts of origin were involved on each occasion, +however, they could be combined into a single shift which could be +represented much more simply. + +Suppose we now wanted to represent our image's celestial coordinate +calibration using FITS conventions (\secref{ss:foreignfits}). This +requires AST to determine whether the Mapping which relates pixel +coordinate to sky positions conforms to the FITS model (for example, +whether it is equivalent to applying a single set of shifts and scale +factors followed by a map projection). Clearly, there is an important +use here for some means of simplifying the internal structure of a +CmpMap. + +\subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings} + +The ability to simplify compound Mappings is provided by the +\htmlref{astSimplify}{astSimplify} function. This function encapsulates a number of +heuristics for converting Mappings, or combinations of Mappings within +a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap, +astSimplify tries to reduce the number of individual Mappings within +it by merging neighbouring component Mappings together. It will do +this with both series and parallel combinations of Mappings, or both, +and will handle CmpMaps nested to any depth +(\secref{ss:complexcmpmap}). + + To illustrate how astSimplify works, consider the combination of + Mappings shown in Figure~\ref{fig:simplifyexample}. + \begin{figure} + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/simpexamp} + \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps, + ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single + UnitMap. The enclosing nested CmpMaps have been omitted for clarity.} + \label{fig:simplifyexample} + \end{center} + \end{figure} + +If this were contained in a CmpMap, it could be simplified as follows: + +\small +\begin{terminalv} +AstMapping *simpler; + +... + +simpler = astSimplify( cmpmap ); +\end{terminalv} +\normalsize + +In this case, the result would be a simple 3-dimensional UnitMap (the +identity \htmlref{Mapping}{Mapping}). To reach this conclusion, astSimplify will have +made a number of deductions, roughly as follows: + +\begin{enumerate} +\item The two 2-dimensional ZoomMaps in series are equivalent to a +single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is +equivalent to a 2-dimensional UnitMap. + +\item This UnitMap in parallel with the other 1-dimensional UnitMap is +equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched +between any other pair of Mappings, can then be eliminated. + +\item The remaining two PermMaps in series are equivalent to a single +3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap +is found to be equivalent to a 3-dimensional UnitMap. +\end{enumerate} + +This example is a little contrived, but illustrates how astSimplify +can deal with even quite complicated compound Mappings through a +series of incremental simplifications. Where possible, this will +result in either a simpler compound Mapping or, if feasible, an atomic +(non-compound) Mapping, as here. If no simplification is possible, +astSimplify will just return a pointer to the original Mapping. + +Although astSimplify cannot identify every simplification that is +theoretically possible, sufficient rules are included to deal with the +most common and important cases. + +\cleardoublepage +\section{\label{ss:frames}Representing Coordinate Systems (Frames)} + +An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate +system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is +used to describe how to convert between coordinate systems. The two +concepts are complementary and we will see how they work together in +\secref{ss:framesets}. + +In this section we will discuss only basic Frames, which represent +Cartesian coordinate systems. More specialised types of Frame +(\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate +systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate +systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes}) +and, naturally, inherit the properties and behaviour of the simple Frames +discussed here. + +\subsection{The Frame Model} + +The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would +plot around a graph. In two dimensions, you would have an ``$x$'' and +a ``$y$'' axis, a title on the graph and labels on the axes, together +with an indication of the physical units being plotted. The values +marked along each axis would be formatted in a human-readable way. The +frame around a graph therefore defines a coordinate space within which +you can locate points, draw lines, calculate distances, \emph{etc.} + +An AST Frame works in much the same way, embodying all of these +concepts and a few more. It also allows any number of axes, which +means that a Frame can represent coordinate systems with any number of +dimensions. You specify how many when you create it. + +Remember that the basic Frame we are considering here is completely +general. It knows nothing of celestial coordinates, for example, and +all its axes are equivalent. It can be adapted to describe any general +purpose Cartesian coordinate system by setting its attributes, such as +its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values. + +\subsection{\label{ss:creatingframes}Creating a Frame} + +Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern: + +\small +\begin{terminalv} +#include "ast.h" +astFrame *frame; + +... + +frame = astFrame( 2, "" ); +\end{terminalv} +\normalsize + +The first argument of the \htmlref{astFrame}{astFrame} constructor function specifies the +number of axes which the Frame should have. + +\subsection{\label{ss:frameasmapping}Using a Frame as a Mapping} + +We should briefly point out that the \htmlref{Frame}{Frame} we created above +(\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping} +(\secref{ss:mappingclass}) and therefore inherits the properties and +behaviour common to other Mappings. + +One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited +from the Mapping class) to a non-zero value and pass the Frame pointer +to a coordinate transformation function, such as \htmlref{astTran2}{astTran2}. + +\small +\begin{terminalv} +double xin[ 5 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 }; +double yin[ 5 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0 }; +double xout[ 5 ]; +double yout[ 5 ]; + +... + +astSet( frame, "Report=1" ); +astTran2( frame, 5, xin, yin, 1, xout, yout ); +\end{terminalv} +\normalsize + +The resulting output might then look like this: + +\begin{terminalv} +(1, 2) --> (1, 2) +(2, 4) --> (2, 4) +(3, 6) --> (3, 6) +(4, 8) --> (4, 8) +(5, 10) --> (5, 10) +\end{terminalv} + +This is not very exciting because a Frame implements an identity +transformation just like a \htmlref{UnitMap}{UnitMap} +(\secref{ss:unitmapexample}). However, it illustrates that a Frame can +be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both +equal to the number of Frame axes. + +When we consider more specialised Frames +(\emph{e.g.}~\secref{ss:framesets}), we will see that using them as +Mappings can be very useful indeed. + +\subsection{\label{ss:frameaxisattributes}Frame Axis Attributes} + +Frames have a number of attributes which can take multiple values, one +for each axis. These separate values are identified by appending the +axis number in parentheses to the attribute name. For example, the +Label(1) attribute is a character string containing the label which +appears on the first axis. + +\htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes +(\secref{ss:gettingattributes}, \secref{ss:settingattributes} and +\secref{ss:defaultingattributes}). For example, the Label on the second +axis might be obtained as follows: + +\small +\begin{terminalv} +const char *label; + +... + +label = astGetC( frame, "Label(2)" ); +\end{terminalv} +\normalsize + +Other attribute access functions (astSetX, \htmlref{astTest}{astTest} and \htmlref{astClear}{astClear}) may +also be applied to axis attributes in the same way. + +If the axis number is stored in a program variable, then its value +must be formatted to generate a suitable attribute name before using +this to access the attribute itself. For example, the following will +print out the Label value for each axis of a \htmlref{Frame}{Frame}: + +\small +\begin{terminalv} +#include <stdio.h> +char name[ 18 ]; +int iaxis, naxes; + +... + +naxes = astGetI( frame, "Naxes" ); +for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { + (void) sprintf( name, "Label(%d)", iaxis ); + label = astGetC( frame, name ); + (void) printf( "Label %2d: %s\n", iaxis, label ); +} +\end{terminalv} +\normalsize + +Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame +axes. + +The output from this might look like the following: + +\begin{terminalv} +Label 1: Axis 1 +Label 2: Axis 2 +\end{terminalv} + +In this case, the Frame's default axis Labels have been revealed as +rather un-exciting. Normally, you would set much more useful values, +typically when you create the Frame---perhaps something like: + +\small +\begin{terminalv} +frame = astFrame( 2, "Label(1)=Offset from centre of field," + "Unit(1) =mm," + "Label(2)=Transmission coefficient," + "Unit(2) =%" ); +\end{terminalv} +\normalsize + +Here, we have also set the (character string) Unit attribute for each +axis to describe the physical units represented on that axis. All the +attribute assignments have been combined into a single string, +separated by commas. + +\subsection{\label{ss:frameattributes}Frame Attributes} + +We will now briefly outline the various attributes associated with a +\htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the +\htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each +attribute, for which you should consult the appropriate description in +\appref{ss:attributedescriptions}. Instead, we aim simply to sketch +the range of facilities available: + +\begin{quote} +\begin{description} +\item[\htmlref{Naxes}{Naxes}]\mbox{}\\ +A read-only integer giving the number of Frame axes. + +\item[\htmlref{Title}{Title}]\mbox{}\\ +A string describing the coordinate system which the Frame represents. + +\item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\ +A label string for each axis. + +\item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\ +A string describing the physical units on each axis. You can choose +whether to make this attribute ``active'' or ``passive'' (using +\htmlref{astSetActiveUnit}{astSetActiveUnit} +). If active, its value will be taken into account when finding the +Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used +to connect two axis with units of ``km'' and ``m''). If passive, its value +is ignored. Its use is described in more detail in \secref{ss:frameunits}. + +\item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\ +A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X'' +or ``Y'') used to represent the quantity plotted on each axis. + +\item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\ +The preferred number of digits of precision to be used when formatting +values for display on each axis. + +\item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\ +A string containing a \emph{format specifier} which determines exactly +how values should be formatted for display on each axis +(\secref{ss:formattingaxisvalues}). If this attribute is un-set, the +formatting is based on the Digits value, otherwise the Format string +over-rides the Digits value. + +\item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\ +A boolean (integer) value which indicates in which direction each axis +should be plotted. If it is non-zero (the default), the axis should be +plotted in the conventional direction---\emph{i.e.}\ increasing to the +right for the abscissa and increasing upwards for the ordinate. If it +is zero, the axis should be plotted in reverse. This attribute is +provided as a hint only and programs are free to ignore it if they +wish. + +\item[\htmlref{Domain}{Domain}]\mbox{}\\ +A character string which identifies the \emph{physical domain} to +which the Frame's coordinate system applies. The primary purpose of +this attribute is to prevent unwanted conversions from occurring +between coordinate systems which are not related. Its use is described +in more detail in \secref{ss:framedomains}. + +\item[\htmlref{System}{System}]\mbox{}\\ +A character string which identifies the specific coordinate system used +to describe positions within the physical domain represented by the Frame. +For a simple Frame, this attribute currently has a fixed value of +``Cartesian'', but could in principle be extended to include options such +as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such +as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame} and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be +appropriate to the domain which they describe. For instance, the SkyFrame +allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows +values such as ``frequency'' and ``wavelength''. + +\item[\htmlref{Epoch}{Epoch}]\mbox{}\\ +This value is used to qualify a coordinate system by giving the moment in +time when the coordinates are correct. Usually, this will be the date of +observation. The Epoch value is important in cases where coordinates +systems move with respect to each other over time. An example of two such +coordinate systems are the FK4 and FK5 celestial coordinate systems. + +\item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\ +Specifies the longitude of the observer (assumed to be on the surface of +the earth). The basic Frame class does not use this value, but +specialised sub-classes may. For instance, the SpecFrame class uses it to +calculate the relative velocity of the observer and the centre of the +earth for use in converting between standards of rest. + +\item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\ +Specifies the latitude of the observer. Use in conjunction with ObsLon. + +\end{description} +\end{quote} + +There are also some further Frame attributes, not described above, +which are important when Frames are used as templates to search for +other Frames. Their use goes beyond the present discussion. +%TBW---Add reference here. + +\subsection{\label{ss:formattingaxisvalues}Formatting Axis Values} + +The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored +(\emph{e.g.}\ within your program) as double values. The Frame class +therefore provides a function, \htmlref{astFormat}{astFormat}, to convert these values into +formatted strings for display: + +\small +\begin{terminalv} +const char *string +double value; + +... + +string = astFormat( frame, iaxis, value ); +\end{terminalv} +\normalsize + +Here, the astFormat function is passed a Frame pointer, the number of +an axis (``iaxis'') and a double precision value to format +(``value''). It returns a pointer to character string containing the +formatted value. +\label{ss:formattingwithdigits} + +By default, the formatting applied will be determined by the Frame's +Digits attribute and will normally display results with seven digits +of precision (corresponding approximately to the C ``float'' data type +on many machines). Setting a different Digits value, however, allows +you to adjust the precision as necessary to suit the accuracy of the +coordinate data you are processing. If finer control is needed, it is +also possible to set a Digits value for each individual axis by +appending an axis number to the attribute name +(\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the +effect of the Frame's main Digits value for that axis. + +Even finer control is possible by setting the (character string) Format +attribute for a Frame axis. The string given should contain a C +\emph{format specifier} which explicitly determines how the values on +that axis should be formatted. This will over-ride the effects of any +Digits value\footnote{The exception to this rule is that if the Format +value includes a precision of ``$.*$'', then Digits will be used to +determine the actual precision used.}. Any valid ``printf'' format +specifier may be used so long as it consumes exactly one double value. + +When setting Format values, remember that the ``\%'' which appears in +the format specifier may need to be doubled to ``\%\%'' if you are +using a function (such as \htmlref{astSet}{astSet}) which interprets ``printf'' format +specifiers itself. + +It is recommended that you use astFormat whenever you display +formatted coordinate values, even although you could format them +yourself using ``sprintf''. This is because it puts the Frame in +control of formatting. When you start to handle more elaborate Frames +(representing, say, celestial coordinates), you will need different +formatting methods. This approach delivers them without any change to +your software. + +You should also consider regularly using the \htmlref{astNorm}{astNorm} function, +described below (\secref{ss:normalising}), for any values that will be +made visible to the user of your software. + +\subsection{\label{ss:normalising}Normalising Frame Coordinates} + +The function \htmlref{astNorm}{astNorm} is provided to cope with the fact that some +coordinate systems do not extend indefinitely in all directions. Some +may have boundaries, outside which coordinates are meaningless, while +others wrap around on themselves, so that after a certain distance you +return to the beginning again (coordinate systems based on circles and +spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but +other more specialised Frames (such as SkyFrames, representing the +celestial sphere---\secref{ss:skyframes}) do. + +The role played by astNorm is to \emph{normalise} any arbitrary set of +coordinates by converting them into a set which is ``within bounds'', +interpreted according to the particular Frame in question. For +example, on the celestial sphere, a right ascension value of 24~hours +or more can have a suitable multiple of 24~hours subtracted without +affecting its meaning and astNorm would perform this task. Similarly, +negative values of right ascension would have a multiple of 24~hours +added, so that the result lies in the range zero to 24~hours. The +coordinates in question are modified in place by astNorm, as follows: + +\small +\begin{terminalv} +double point[ 2 ]; + +... + +astNorm( frame, point ); +\end{terminalv} +\normalsize + +If the coordinates supplied are initially OK, as they would always be +with a basic Frame, then they are returned unchanged. + +Because the main purpose of astNorm is to convert coordinates into the +preferred range for human consumption, its use is almost always +appropriate immediately before formatting coordinate values for +display using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}). Even if +the Frame in question does not restrict the range of coordinates, so +that astNorm does nothing, using it will allow you to process other +more specialised Frames, where normalisation is important, without +changing your software. + +\subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values} + +The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame} +axis, such as might be produced by \htmlref{astFormat}{astFormat} +(\secref{ss:formattingaxisvalues}), back into a numerical (double) +value ready for processing is performed by \htmlref{astUnformat}{astUnformat}. However, +although this process is essentially the inverse of that performed by +astFormat, there are a number of additional difficulties that must be +addressed in practice. + +The main use for astUnformat is in reading formatted coordinate values +which have been entered by the user of a program, or read from a +file. As such, we can rarely assume that the values are neatly +formatted in the way that astFormat would produce. Instead, it is +usually desirable to allow considerable flexibility in the form of +input that can be accommodated, so as to permit ``free-format'' data +input by the user. In addition, we may need to extract individual +coordinate values embedded in other textual data. + +Underlying these requirements is the root difficulty that the textual +format used to represent a coordinate value will depend on the class +of Frame we are considering. For example, for a basic Frame, +astUnformat may have to read a value like ``1.25e-6'', whereas for a +more specialised Frame representing celestial coordinates it may have +to handle a value like ``-07d~49m~13s''. Of course, the format might +also depend on which axis is being considered. + +Ideally, we would like to write software that can handle any kind of +Frame. However, this makes it a little more difficult to analyse +textual input data to extract individual coordinate values, since we +cannot make assumptions about how the values are formatted. It would +not be safe, for example, simply to assume that the values being read +are separated by white space. This is not just because they might be +separated by some other character, but also because celestial +coordinate values might themselves contain spaces. In fact, to be +completely safe, we cannot make any assumptions about how a formatted +coordinate value is separated from the surrounding text, except that +it should be separated in some way which is not ambiguous. + +This is the very basic assumption upon which astUnformat works. It is +invoked as follows: + +\small +\begin{terminalv} +int n; + +... + +n = astUnformat( frame, iaxis, string, &value ); +\end{terminalv} +\normalsize + +It is supplied with a Frame pointer (``frame''), the number of an axis +(``iaxis'') and a character string to be read (``string''). If it +succeeds in reading a value, astUnformat returns the resulting +coordinate to the address supplied \emph{via} the final argument +(``\&value''). The returned function value indicates how many +characters were read from the string in order to obtain this result. + +The string is read as follows: + +\begin{enumerate} +\item Any white space at the start is skipped over. + +\item Further characters are considered, one at a time, until the next +character no longer matches any of the acceptable forms of input +(given the characters that precede it). The longest sequence of +characters which matches is then considered ``read''. + +\item If a suitable sequence of characters was read successfully, it +is converted into a coordinate value which is returned. Any white +space following this sequence is then skipped over and the total +number of characters consumed is returned as the function value. + +\item If the sequence of characters read is empty, or insufficient to +define a coordinate value, then the string does not contain a value to +read. In this case, the read is aborted and astUnformat returns a +function value of zero and no coordinate value. However, it returns +without error. +\end{enumerate} + +Note that failing to read a coordinate value does not constitute an +error, at least so far as astUnformat is concerned. However, an error +can occur if the sequence of characters read appears to have the +correct form but cannot be converted into a valid coordinate +value. Typically, this will be because it violates some constraint, +such as a limit on the value of one of its fields. The resulting error +message will give details. + +For any given Frame axis, astUnformat does not necessarily always use +the same algorithm for converting the sequence of characters it reads +into a coordinate value. This is because some forms of input +(particularly free-format input) can be ambiguous and might be +interpreted in several ways depending on the context. For example, the +celestial longitude ``12:34:56.7'' could represent an angle in degrees +or a right ascension in hours. To decide which to use, astUnformat may +examine the Frame's attributes and, in particular, the appropriate +\htmlref{Format(axis)}{Format(axis)} string which is used by astFormat when formatting +coordinate values (\secref{ss:formattingaxisvalues}). This is done in +order that astFormat and astUnformat should complement each other---so +that formatting a value and then un-formatting it will yield the +original value, subject to any rounding error. + +To give a simple (but crucially incomplete!) example, consider reading +a value for the axis of a basic Frame, as follows: + +\small +\begin{terminalv} +n = astUnformat( frame, iaxis, " 1.5e6 -99.0", &value ); +\end{terminalv} +\normalsize + +astUnformat will skip over the initial space in the string supplied +and then examine each successive character. It will accept the +sequence ``1.5e6'' as input, but reject the space which follows +because it does not form part of the format of a floating point +number. It will then convert the characters ``1.5e6'' into a +coordinate value and skip over the three spaces which follow them. The +returned function value will therefore be 9, equal to the total number +of characters consumed. This result may be used to address the string +during a subsequent read, so as to commence reading at the start of +``-99.0''. + +Most importantly, however, note that if the user of a program +mistakenly enters the string ``~1.5r6\ldots'' instead of +``~1.5e6\ldots'', a coordinate value of 1.5 and a function result of 4 +will be returned, because the ``r'' would prematurely terminate the +attempt to read the value. Because this sort of mistake does not +automatically result in an error but can produce incorrect results, it +is \textbf{vital} to check the returned function value to ensure that +the expected number of characters have been read.\footnote{Anyone who +seriously uses the C run time library ``scanf'' function will know +about the need for this check!} For example, if the string is +expected to contain exactly one value, and nothing else, then the +following would suffice: + +\small +\begin{terminalv} +n = astUnformat( frame, iaxis, string, &value ); +if ( astOK ) { + if ( string[ n ] || !n ) { + <error in input data> + } else { + <value read correctly> + } +} +\end{terminalv} +\normalsize + +If astUnformat does not detect an error itself, we check that it has +read to the end-of-string and consumed at least one character (which +traps the case of a zero-length input string). If this reveals an +error, the value of ``n'' indicates where it occurred. + +Another common requirement is to obtain a position by reading a list +of coordinates from a string which contains one value for each axis of +a Frame. We assume that the values are separated in some unambiguous +manner, perhaps using white space and/or some unspecified +single-character separator. The choice of separator is up to the data +supplier, who must choose it so as not to conflict with the format of +the coordinate values, but our software does not need to know what it +is. The following is a template algorithm for reading data in this +form: + +\small +\begin{terminalv} +const char *s; +double values[ 10 ]; + +... + +/* Initialise a string pointer. */ +s = string; + +/* Obtain the number of Frame axes and loop through them. */ +naxes = astGetI( frame, "Naxes" ); +for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { + +/* Attempt to read a value for this axis. */ + n = astUnformat( frame, iaxis, s, &values[ iaxis - 1 ] ); + +/* If nothing was read and this is not the first axis or the + end-of-string, try stepping over a separator and reading again. */ + if ( !n && ( iaxis > 1 ) && *s ) + n = astUnformat( frame, iaxis, ++s, &values[ iaxis - 1 ] ); + +/* Quit if nothing was read, otherwise move on to the next value. */ + if ( !n ) break; + s += n; +} + +/* Check for possible errors. */ +if ( astOK ) { + if ( *s || !n ) { + <error in input data> + } else { + <values read correctly> + } +} +\end{terminalv} +\normalsize + +In this case, ``s'' will point to the location of any input error. + +Note that this algorithm is insensitive to the precise format of the +data and will therefore work with any class of Frame and any +reasonably unambiguous input data. For example, here is a range of +suitable input data for a 3-dimensional basic Frame: + +\small +\begin{terminalv} +1 2.5 3 +3.1,3.2,3.3 +1.5, 2.6, -9.9e2 +-1.1+0.4-1.8 + .1/.2/.3 + 44.0 ; 55.1 -14 +\end{terminalv} +\normalsize + +\subsection{\label{ss:permutingaxes}Permuting Frame Axes} + +Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number +of axes it contains, but it is possible to change the order in which +these axes occur. To do so, an integer \emph{permutation array} is +filled with the numbers of the axes so as to specify the new order, +\emph{e.g.:} + +\small +\begin{terminalv} +int perm[ 2 ] = { 2, 1 }; +\end{terminalv} +\normalsize + +In this case, the axes of a 2-dimensional Frame could be interchanged +by passing this permutation array to the \htmlref{astPermAxes}{astPermAxes} function. That +is, an ($x_1,x_2$) coordinate system would be changed into an +($x_2,x_1$) coordinate system by: + +\small +\begin{terminalv} +astPermAxes( frame, perm ); +\end{terminalv} +\normalsize + +If the axes are permuted more than once, the effects are cumulative. +You are, of course, not restricted to Frames with only two axes. + +\subsection{Selecting Frame Axes} + +An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not +allowed, is to create a new Frame by selecting axes from an existing +one. The method of doing this is very similar to the way \htmlref{astPermAxes}{astPermAxes} +is used (\secref{ss:permutingaxes}), in that we supply an integer +array filled with the numbers of the axes we want, in their new +order. In this case, however, the number of array elements need not +equal the number of Frame axes. + +For example, we could select axes 3 and 2 (in that order) from a +3-dimensional Frame as follows: + +\small +\begin{terminalv} +astFrame *frame1, *frame2; +astMapping *mapping; +int pick[ 2 ] = { 3, 2 }; + +... + +frame2 = astPickAxes( frame1, 2, pick, &mapping ); +\end{terminalv} +\normalsize + +This would return a pointer to a 2-dimensional Frame (``frame2'') +which contains the information associated with axes 3 and 2, in that +order, from the original Frame (``frame1''). The original Frame is not +altered by this process. Beware, however, that the axis information +may still be shared by both Frames, so if you wish to alter either of +them independently you may first need to use \htmlref{astCopy}{astCopy} +(\secref{ss:copyingobjects}) to make an independent copy. + +In addition to the new Frame pointer, \htmlref{astPickAxes}{astPickAxes} will also return a +pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument (you may supply a +NULL pointer as an argument if you do not want this Mapping). This +Mapping will inter-relate the two Frames. By this we mean that its +forward transformation will convert coordinates originally in the +coordinate system represented by ``frame1'' into that represented by +``frame2'', while its inverse transformation will convert in the +opposite direction. In this particular case, the Mapping would be a +\htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following +transformations: + +\begin{terminalv} +Forward: + (1, 2, 3) --> (3, 2) + (2, 4, 6) --> (6, 4) + (3, 6, 9) --> (9, 6) + (4, 8, 12) --> (12, 8) + (5, 10, 15) --> (15, 10) + +Inverse: + (3, 2) --> (<bad>, 2, 3) + (6, 4) --> (<bad>, 4, 6) + (9, 6) --> (<bad>, 6, 9) + (12, 8) --> (<bad>, 8, 12) + (15, 10) --> (<bad>, 10, 15) +\end{terminalv} + +This is our first introduction to the idea of inter-relating pairs of +Frames \emph{via} a Mapping, but this will assume a central role later on. + +Note that when using astPickAxes, it is also possible to request more +axes than there were in the original Frame. This will involve +selecting axes from the original Frame that do not exist. To do this, +the corresponding axis number (in the ``pick'' array) should be set to +zero and the effect is to introduce an additional new axis which is +not derived from the original Frame. This axis will have default +values for all its attributes. You will need to do this because +astPickAxes does not allow you to select any of the original axes more +than once.\footnote{It will probably not be obvious why this +restriction is necessary, but consider creating a Frame with one +longitude axis and two latitude axes. Which latitude axis should be +associated with the longitude axis?} + +\subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets} +Some complementary +functions +are provided for use with Frames to allow you to perform geometric +operations without needing to know the nature of the coordinate system +represented by the \htmlref{Frame}{Frame}. + +Functions +can be used to find the distance between two points, and to offset a +specified distance along a line joining two points, \emph{etc.} In essence, +these define the metric of the coordinate space which the Frame represents. In +the case of a basic Frame, this is a Cartesian metric. + +The first of these functions, \htmlref{astDistance}{astDistance}, returns a double distance +value when supplied with the Frame coordinates of two points. For +example: + +\small +\begin{terminalv} +double dist; +double point1[ 2 ] = { 0.0, 0.0 }; +double point2[ 2 ] = { 1.0, 1.0 }; + +... + +dist = astDistance( frame, point1, point2 ); +\end{terminalv} +\normalsize + +This calculates the distance between the origin (0,0) and a point at +position (1,1). In this case, the result, as you would expect, is +$\surd{2}$. However, this is only true for the Cartesian coordinate +system which a basic Frame represents. In general, astDistance will +calculate the geodesic distance between the two points, so that with a +more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial +sphere) a great-circle distance might be returned. + +The \htmlref{astOffset}{astOffset} function is really the inverse of astDistance. Given two +points in a Frame, it calculates the coordinates of a third point +which is offset a specified distance away from the first point along +the geodesic joining it to the second one. For example: + +\small +\begin{terminalv} +double point1[ 2 ] = { 0.0, 0.0 }; +double point2[ 2 ] = { 1.0, 1.0 }; +double point3[ 2 ]; + +... + +astOffset( frame, point1. point2, 0.5, point3 ); +\end{terminalv} +\normalsize + +This would fill the ``point3'' array with the coordinates of a point +which is offset 0.5 units away from the origin (0,0) in the direction +of the position (1,1). Again, this is a simple result in a Cartesian +Frame, as varying the offset will trace out a straight line. On the +celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would +trace out a great circle. + +The functions \htmlref{astAxDistance}{astAxDistance} and \htmlref{astAxOffset}{astAxOffset} are similar to astDistance +and astOffset, except that the curves which they use as ``straight +lines'' are not geodesics, but curves parallel to a specified axis\footnote +{For instance, a line of constant Declination is not a geodesic}. One +reason for using these functions is to deal with the cyclic ambiguity of +longitude and latitude axes. + +The \htmlref{astOffset2}{astOffset2} function is similar to astOffset, but instead of using the +geodesic which passes through two positions, it uses the geodesic which +passes at a given position angle through the starting position. + +Position angles are always measured from the positive direction of the +second Frame axis to the required line, with positive angles being in the +same sense as rotation from the positive direction of the second axis to +the positive direction of the first Frame axis. This definition applies +to all classes of Frame, including SkyFrame. The default ordering of axes +in a SkyFrame makes the second axis equivalent to north, and so the +definition of position angle given above corresponds to the normal +astronomical usage, ``from north, through east''. However, it should be +remembered that it is possible to permute the axes of a SkyFrame (or +indeed any Frame), so that north becomes axis 1. In this case, an AST +``position angle'' would be the angle ``from east, through north''. +Always take the axis ordering into account when deriving an astronomical +position angle from an AST position angle. + +Within a Cartesian coordinate system, the position angle of a geodesic +(\emph{i.e.}\ a straight line) is constant along its entire length, but +this is not necessarily true of other coordinate systems. Within a +spherical coordinate system, for instance, the position angle of a geodesic +will vary along its length (except for the special cases of a meridian and +the equator). In addition to returning the required offset position, the +astOffset2 function +returns the position angle of the geodesic at the +offset position. This is useful if you want to trace out a path which +involves turning through specified angles. For instance, tracing out a +rectangle in which each side is a geodesic involves turning through 90 +degrees at the corners. To do this, use astOffset2 to calculate the +position of each corner, and then add (or subtract) 90 degrees from the +position angle returned by astOffset2. + +The \htmlref{astAngle}{astAngle} function +calculates the angle subtended by two points, at a third point. +If used with a 2-dimensional Frame the returned angle +is signed to indicate the sense of rotation (clockwise or anti-clockwise) +in taking the ``shortest route'' from the first point to the second. +If the Frame has more than 2 axes, the result is un-signed and is always +in the range zero to $\pi$. + +The \htmlref{astAxAngle}{astAxAngle} function is similar to astAngle, +but the ``reference direction'', from which angles are measured, is +a specified axis. + +The \htmlref{astResolve}{astResolve} function +resolves a given displacement within a Frame into two components, parallel and +perpendicular to a given reference direction. + +The displacement is specified by two positions within the Frame; the +starting and ending positions. The reference direction is defined by the +geodesic curve passing through the starting position and a third specified +position. The lengths of the two components are returned, together with +the position on the reference geodesic which is closest to the third +supplied point. + +\subsection{\label{ss:framedomains}The Domain Attribute} + +The \htmlref{Domain}{Domain} attribute is one of the most important properties of a +\htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little +subtle. We will introduce it here, but its true value will probably +not become apparent until later (\secref{ss:framesetconverting}). + +To understand the need for the Domain attribute, consider using +different Frames to represent the following different coordinate +systems associated with a CCD image: + +\begin{enumerate} +\item A coordinate system based on pixel numbers. + +\item Positions on the CCD chip, measured in $\mu$m. + +\item Positions in the focal plane of the telescope, measured in mm. + +\item A celestial coordinate system, measured in radians. +\end{enumerate} + +If we had two such CCD images, we might legitimately want to align +them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based +on pixel numbers) in order to, say, divide by a flat-field exposure. +We might similarly consider aligning them using any of the other +coordinate systems so as to achieve different results. For example, we +might consider merging separate images from a CCD mosaic by using +focal plane positions. + +It would obviously not be legitimate, however, to directly compare +positions in one image measured in pixels with positions in the other +measured in mm, nor to equate chip positions in $\mu$m with sky +coordinates in radians. If we wanted to inter-compare these +coordinates, we would need to do it indirectly, using other +information based on the experimental set-up. For instance, we might +need to know the size of the pixels expressed in mm and the +orientation of the CCD chip in the focal plane. + +Note that it is not simply the difference in physical units which +prevents certain coordinates from being directly inter-compared +(because the appropriate unit scaling factors could be included +without any additional information). Neither is it the fact that +different coordinate systems are in use (because we could legitimately +inter-compare two different celestial coordinate systems without any +extra information). Instead, it is the different nature of the +coordinate spaces to which these coordinate systems have been applied. + +We normally express this by saying that the coordinate systems apply +to different \emph{physical domains}. Although we may establish +\emph{ad hoc} relationships between coordinates in different physical +domains, they are not intrinsically related to each other and we need +to supply extra information before we can convert coordinates between +them. + +In AST, the role of the (character string) Domain attribute is to +assign Frames to their respective physical domains. The way it +operates is as follows: + +\begin{itemize} +\item Coordinate systems which apply to the same physical domain +(\emph{i.e.}\ whose Frames have the same Domain value) can be directly +inter-compared. + +If the domain has several coordinate systems associated with it +(\emph{e.g.}\ the celestial sphere), then a coordinate conversion may +be involved. Otherwise, coordinate values may simply be equated. + +\item Coordinate systems which apply to different physical domains +(\emph{i.e.}\ whose Frames have different Domain values) cannot be +directly inter-compared. + +If any relationship does exist between such coordinate systems---and +it need not---then additional information must be supplied in order to +establish the relationship between them in any particular case. We +will see later (\secref{ss:framesets}) how to establish such +relationships between Frames in different domains. +\end{itemize} + +With the basic Frames we are considering here, each physical domain only +has a single (Cartesian) coordinate system associated with it, so that if +two such Frames have the same Domain value, their coordinate systems will +be identical and may simply be equated. With more specialised Frames, +however, more than one coordinate system may apply to each domain. In +such cases, a coordinate conversion may need to be performed. + +When a basic Frame is created, its Domain attribute defaults to an +empty string. This means that all such Frames belong to the same +(null) domain by default and therefore describe the same unspecified +physical coordinate space. In order to assign a Frame to a different +domain, you simply need to set its Domain value. This is normally most +conveniently done when it is created, as follows: + +\small +\begin{terminalv} +frame1 = astFrame( 2, "Domain=CCD_CHIP," + "Unit(1)=micron," + "Unit(2)=micron" ); +frame2 = astFrame( 2, "Domain=FOCAL_PLANE," + "Unit(1)=mm," + "Unit(2)=mm" ); +\end{terminalv} +\normalsize + +Here, we have created two Frames in different physical +domains. Although their coordinate values all have units of length, +they cannot be directly inter-compared (because their axes may be +rotated with respect to each other, for instance). + +All Domain values are automatically converted to upper case and white +space is removed, but there are no other restrictions on the names you +may use to label different physical domains. From a practical point of +view, however, it is worth following a few conventions +(\secref{ss:domainconventions}). + +\subsection{\label{ss:domainconventions}Conventions for Domain Names} + +When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it +obviously makes sense to avoid generic names which might clash with +those used for similar (but subtly different!) purposes by other +programmers. If you are developing software for an instrument, for +example, and want to identify an instrumental coordinate system, then +it is sensible to add a distinguishing prefix. For instance, you might +use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an +acronym) identifies your instrument. + +For some purposes, however, a standard choice of Domain name is +desirable so that different items of software can communicate. For +this purpose, the following Domain names are reserved by AST and the +use recommended below should be carefully observed: + +\begin{quote} +\begin{description} +\item[GRAPHICS]\mbox{}\\ +Identifies the coordinate space used by an underlying computer +graphics system to specify plotting operations. Typically, when +performing graphical operations, AST is used to define additional +coordinate systems which are related to these ``native'' graphical +coordinates. Plotting may be carried out in any of these coordinate +systems, but the GRAPHICS domain identifies the native coordinates +through which AST communicates with the underlying graphics system. + +\item[GRID]\mbox{}\\ +Identifies the instantaneous \emph{data grid} used to store and handle +data, together with an associated coordinate system. In this +coordinate system, the first element stored in an array of data always +has a coordinate value of unity at its centre and all elements have +unit extent. This applies to all dimensions. + +If data are copied or transformed to a new data grid (by whatever +means), or a subset of the original grid is extracted, then the same +rules apply to the copy or subset. Its first element therefore has +GRID coordinate values of unity at its centre. Note that this means +that GRID coordinates remain attached to the first element of the data +grid and not to its data content (\emph{e.g.}\ the features in an +image). + +\item[PIXEL]\mbox{}\\ +Identifies an array of pixels and an associated \emph{pixel-based} +coordinate system which is related to the GRID coordinate system +(above) simply by a shift of origin along each axis. This shift may be +integral, fractional, positive, negative or zero. The data elements +retain their unit extent along each axis. + +Because the amount of shift is unspecified, the PIXEL domain is +distinct from the GRID domain. The relationship between them contains +a degree of uncertainty, such as typically arises from the different +conventions used by different software systems. For instance, in some +software the first pixel is regarded as being centred at (1,1), while +in other software it is at (0.5,0.5). In addition, some software +packages implement a ``pixel origin'' which allows pixel coordinates +to start at an arbitrary value. + +The GRID domain (which corresponds with the pixel-numbering convention +used by FITS) is a special case of the PIXEL domain and avoids this +uncertainty. In general, additional information is required in order +to convert from one to the other. + +\item[SKY]\mbox{}\\ +Identifies the domain which contains all equivalent celestial +coordinate systems. Because these are represented in AST by SkyFrames +(\secref{ss:skyframes}), it should be no surprise that the default +Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you +probably won't need to change this very often. + +\item[SPECTRUM]\mbox{}\\ +Identifies the domain used to describe positions within an +electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes}) +class describes positions within this domain, allowing a wide range of +different coordinate systems to be used (frequency, wavelength, +\emph{etc}). The default Domain value for a SpecFrame is SPECTRUM. + +\item[TIME]\mbox{}\\ +Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame} +class describes positions within this domain, allowing a wide range of +different coordinate systems and timescales to be used. The default Domain +value for a TimeFrame is TIME. + +\end{description} +\end{quote} + +Although we have drawn a necessary distinction here between the GRID +and PIXEL domains, we will continue to refer in general terms to image +``pixels'' and ``pixel coordinates'' whenever this distinction is not +important. This should not be taken to imply that the GRID convention +for numbering pixels is excluded---in fact, it is usually to be +preferred (at the level of data handling being discussed in this +document) and we recommend it. + +\subsection{\label{ss:frameunits}The Unit Attribute} +Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used +to describe positions on the axis. The index of the axis to which the +attribute refers should normally be placed in parentheses following the +attribute name (``Unit(2)'' for instance). However, if the Frame has only +a single axis, then the axis index can be omitted. + +In versions of AST prior to version 2.0, the Unit attribute was nothing +more than a descriptive string intended purely for human readers---no +part of the AST system used the Unit string for any purpose (other than +inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no +account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between +two Frames. Thus if the conversion between a pair of 1-dimensional Frames +representing velocity was found (using +\htmlref{astConvert}{astConvert} +) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit +attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is +referred to below as a \emph{passive} Unit attribute. + +As of AST version 2.0, a facility exists which allows the Unit attribute +to be \emph{active}; that is, differences in the +Unit attribute may be taken into account when finding the Mapping between +two Frames. In order to minimise the risk of breaking older software, the +\emph{default} behaviour of simple Frames and SkyFrames is unchanged from +previous versions (\emph{i.e.} they have passive Unit attributes). However, +the new +functions \htmlref{astSetActiveUnit}{astSetActiveUnit} and \htmlref{astGetActiveUnit}{astGetActiveUnit} +allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame} +classes \emph{always} have an active Unit attribute (attempts to change this +are ignored). + +For instance, consider the above example of two 1-dimensional Frames +describing velocity. These Frames can be created as follows: + +\small +\begin{terminalv} +AstFrame *frame1, *frame2; +frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" ); +frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" ); +\end{terminalv} +\normalsize + +By default, these Frames have passive Unit attributes, and so an attempt +to find a Mapping between them would ignore the difference in their Unit +attributes and return a unit Mapping. To avoid this, we indicate that we +want these Frames to have \emph{active} Unit attributes, as follows: + +\small +\begin{terminalv} +astSetActiveUnit( frame1, 1 ); +astSetActiveUnit( frame2, 1 ); +\end{terminalv} +\normalsize + +If we then find the Mapping between them as follows: + +\small +\begin{terminalv} +AstFrameSet *cvt; +... +cvt = astConvert( frame1, frame2, "" ); +\end{terminalv} +\normalsize + +the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by +astConvert +will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a +velocity in $km/h$) by a factor of 0.278 to create its output (a velocity +in $m/s$). + +In fact we need not have set the Unit attribute active in ``frame1'' +since the behaviour of astConvert is determined by its ``to'' Frame +(the second Frame parameter). + +\subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings} +Conversion between units systems relies on the use of a specific syntax +for the Unit attribute. If the value of the Unit attribute does not +conform to this syntax, then an error will be reported if an attempt is +made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen +if the Unit attribute is \emph{passive}). + +The adopted syntax is that described in FITS-WCS paper I "Representation +of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish +here between ``basic'' units and ``derived'' units: derived units are +defined in terms of other units (either derived or basic), whereas basic +units have no such definitions. Derived units may be represented by their +own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a +\emph{mathematical expression} which combines other symbols and constants +to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per +second). Unit symbols may be prefixed by a string representing a standard +multiple or sub-multiple. + +In addition to the unit symbols listed in FITS-WCS Paper I, any other +arbitrary unit symbol may be used, with the proviso that it will not be +possible to convert between Frames using such units. The exception to +this is if both Frames refer to the same unknown unit string. For instance, +an axis with unknown unit symbol "flop" \emph{could} be converted to an axis +with unit "Mflop" (Mega-flop). + +Unit symbols (optionally prefixed with a multiple or sub-multiple) can be +combined together using a limited range of mathematical operators and +functions, to produce new units. Such expressions may also contain +parentheses and numerical constants (these may optionally use +``scientific'' notation including an ``E'' character to represent the +power of 10). + +The following tables list the symbols for the basic and derived units which +may be included in a units string, the standard prefixes for multiples +and sub-multiples, and the strings which may be used to represent +mathematical operators and functions. + +\begin{table}[htbp] +\begin{center} +\begin{tabular}{|l|l|l|} +\hline +\multicolumn{3}{|c|}{{\large Basic units}} \\ \hline +\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & +\multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline +length & m & metre \\ +mass & g & gram \\ +time & s & second \\ +plane angle & rad & radian \\ +solid angle & sr & steradian \\ +temperature & K & Kelvin \\ +electric current & A & Ampere \\ +amount of substance & mol & mole \\ +luminous intensity & cd & candela \\ +\hline +\end{tabular} +\end{center} +\end{table} + +\begin{table}[htbp] +\begin{center} +\begin{small} +\begin{tabular}{|l|l|l|l|} +\hline +\multicolumn{4}{|c|}{{\large Derived units}} \\ \hline +\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & +\multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline +area & barn & barn & 1.0E-28 m**2 \\ +area & pix & pixel & \\ +area & pixel & pixel & \\ +electric capacitance & F & Farad & C/V \\ +electric charge & C & Coulomb & A s \\ +electric conductance & S & Siemens & A/V \\ +electric potential & V & Volt & J/C \\ +electric resistance & Ohm & Ohm & V/A \\ +energy & J & Joule & N m \\ +energy & Ry & Rydberg & 13.605692 eV \\ +energy & eV & electron-Volt & 1.60217733E-19 J \\ +energy & erg & erg & 1.0E-7 J \\ +events & count & count & \\ +events & ct & count & \\ +events & ph & photon & \\ +events & photon & photon & \\ +flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\ +flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\ +flux density & mag & magnitude & \\ +force & N & Newton & kg m/s**2 \\ +frequency & Hz & Hertz & 1/s \\ +illuminance & lx & lux & lm/m**2 \\ +inductance & H & Henry & Wb/A \\ +length & AU & astronomical unit & 1.49598E11 m \\ +length & Angstrom & Angstrom & 1.0E-10 m \\ +length & lyr & light year & 9.460730E15 m \\ +length & pc & parsec & 3.0867E16 m \\ +length & solRad & solar radius & 6.9599E8 m \\ +luminosity & solLum & solar luminosity & 3.8268E26 W \\ +luminous flux & lm & lumen & cd sr \\ +magnetic field & G & Gauss & 1.0E-4 T \\ +magnetic flux & Wb & Weber & V s \\ +mass & solMass & solar mass & 1.9891E30 kg \\ +mass & u & unified atomic mass unit & 1.6605387E-27 kg \\ +magnetic flux density & T & Tesla & Wb/m**2 \\ +plane angle & arcmin & arc-minute & 1/60 deg \\ +plane angle & arcsec & arc-second & 1/3600 deg \\ +plane angle & mas & milli-arcsecond & 1/3600000 deg \\ +plane angle & deg & degree & pi/180 rad \\ +power & W & Watt & J/s \\ +pressure, stress & Pa & Pascal & N/m**2 \\ +time & a & year & 31557600 s \\ +time & d & day & 86400 s \\ +time & h & hour & 3600 s \\ +time & yr & year & 31557600 s \\ +time & min & minute & 60 s \\ + & D & Debye & 1.0E-29/3 C.m \\ +\hline +\end{tabular} +\end{small} +\end{center} +\end{table} + +\begin{table}[htbp] +\begin{center} +\begin{tabular}{|lll|lll|} +\hline +\multicolumn{6}{|c|}{{\large Prefixes for multiples \& +sub-multiples}} \\ \hline +\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & +\multicolumn{1}{c|}{Prefix} & +\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & +\multicolumn{1}{c|}{Prefix} \\ \hline +$10^{-1}$ & deci & d & $10$ & deca & da \\ +$10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\ +$10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\ +$10^{-6}$ & micro & u & $10^{6}$ & mega & M \\ +$10^{-9}$ & nano & n & $10^{9}$ & giga & G \\ +$10^{-12}$ & pico & p & $10^{12}$ & tera & T \\ +$10^{-15}$ & femto & f & $10^{15}$ & peta & P \\ +$10^{-18}$ & atto & a & $10^{18}$ & exa & E \\ +$10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\ +$10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\ +\hline +\end{tabular} +\end{center} +\end{table} + +\begin{table}[htbp] +\begin{center} +\begin{tabular}{|l|l|} +\hline +\multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\ +\hline +\multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline +sym1 sym2 & multiplication (a space) \\ +sym1*sym2 & multiplication (an asterisk) \\ +sym1.sym2 & multiplication (a dot) \\ +sym1/sym2 & division \\ +sym1**y & exponentiation ($y$ must be a numerical constant)\\ +sym1\verb+^+y & exponentiation ($y$ must be a numerical constant)\\ +log(sym1) & common logarithm \\ +ln(sym1) & natural logarithm \\ +exp(sym1) & exponential \\ +sqrt(sym1) & square root \\ +\hline +\end{tabular} +\end{center} +\end{table} + +\subsubsection{Side-effects of Changing the Unit attribute} +If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by +setting a new value or by clearing it so that the default value is +re-instated) may cause the Label and Symbol attributes to be changed +accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'', +``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)'' +will cause AST to change its Label and Symbol to ``log(Frequency)'' and +``Log(nu)''. These changes are only made if the Unit attribute is active, +and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other + hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change +to the Label or Symbol attributes. + +\cleardoublepage +\section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)} + +A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on +the celestial sphere is obviously of great importance in +astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine +the additional properties and behaviour of a SkyFrame that distinguish +it from a basic Frame (\secref{ss:frames}). + +\subsection{The SkyFrame Model} + +A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a +\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and +behaviour of these two ancestral classes. When used as a Mapping, a +SkyFrame implements a unit transformation, exactly like a basic Frame +(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its +behaviour is not of great importance. + +When used as a Frame, however, a SkyFrame represents a 2-dimensional +\emph{spherical} coordinate system, in which the shortest distance +between two points is a great circle. A SkyFrame therefore always has +exactly two axes which represent the longitude and latitude of a +coordinate system residing on the celestial sphere. Many such +coordinate systems can be represented by a SkyFrame, as we will see +shortly. + +A SkyFrame can represent any of the commonly used celestial coordinate +systems. Optionally, the origin of the longitude/latitude system can be +moved to any specified point in the standard celestial system, allowing +a SkyFrame to represent offsets from a specified sky position. + +When it is first created, a SkyFrame's axes are always in the order +(longitude,~latitude) but this can be changed, if required, by using the +\htmlref{astPermAxes}{astPermAxes} function (\secref{ss:permutingaxes}). The order of the axes +can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A +SkyFrame's coordinate values are always stored as angles in (double +precision) radians, regardless of the setting of the Unit attribute +\footnote{The units used for the internal floating-point representation of an +axis value can be determined by examining the InternalUnit attribute of +the Frame. For most Frames, the Unit and InternalUnit attributes will be +equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}. + +\subsection{Creating a SkyFrame} + +The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a +SkyFrame with default attributes is created as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstSkyFrame *skyframe; + +... + +skyframe = astSkyFrame( "" ); +\end{terminalv} +\normalsize + +Such a SkyFrame would represent the default celestial coordinate +system which, at present, is the ICRS system (the default was "FK5(J2000)" +in versions of AST prior to 3.0). + +\subsection{Specifying a Particular Celestial Coordinate System} + +For many purposes, the ICRS coordinate system is perfectly +adequate. In order to support conversion between a variety of +celestial coordinate systems, however, you can create SkyFrames that +represent any of these. + +Selection of a particular coordinate system is performed simply by +setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System} +attribute. This setting is most conveniently done when the SkyFrame is +created. For example, a SkyFrame representing the old FK4~(B1950.0) +coordinate system would be created by: + +\small +\begin{terminalv} +skyframe = astSkyFrame( "System=FK4" ); +\end{terminalv} +\normalsize + +Note that specifying ``System$=$FK4'' also changes the associated +equinox (from J2000.0 to B1950.0). This is because the default value +of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends +on the System attribute setting. + +You may change the System value at any time, although this is not +usually needed. The values supported are set out in the attribute's +description in \appref{ss:attributedescriptions} and include a variety +of equatorial coordinate systems, together with ecliptic and galactic +coordinates. + +General spherical coordinates are supported by specifying +``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be +created to convert between ``unknown'' coordinates and any of the other +celestial coordinate systems (see \secref{ss:introducingconversion} ). + +\subsection{Attributes which Qualify Celestial Coordinate Systems} + +Many celestial coordinate systems have some additional free parameters +which serve to identify a particular coordinate system from amongst a +broader class of related coordinate systems. For example, the +FK5~(J2010.0) system is distinguished from the FK5~(J2000.0) +system by a different equinox---and the coordinates of a fixed +astronomical source would have different values when expressed in +these two systems. + +In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame} +attributes, each of which has a default appropriate to +(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} +attribute. Each of these \emph{qualifying attributes} may, however, be +assigned an explicit value so as to select a particular coordinate +system. Note, it is usually best to assign explicit +values whenever possible rather than relying on defaults. Attribute +should only be left at their default value if you ``don't care'' what +value is used. In certain circumstances (particularly, when aligning two +Frames), a default value for an attribute may be replaced by the value +from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by +assigning an explicit value to the attribute, rather than simply relying on +the default. + + +The main SkyFrame attributes which qualify the System attribute are: + +\begin{quote} +\begin{description} + +\item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\ +This attribute is inherited from the Frame class. It gives the moment in +time when the coordinates are correct for the astronomical source +under study (usually the date of observation). + +\item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\ +This value is used to qualify celestial coordinate systems that are +notionally based on the Earth's equator and/or the ecliptic (the plane +of the Earth's orbit around the Sun). The position of either of these +planes is difficult to specify precisely, so in practice a model +\emph{mean} equator and/or ecliptic are used instead. These, together +with the point on the sky that defines the coordinate origin (termed +the \emph{mean equinox}) move with time according to some model which +smoothes out the more rapid fluctuations. The SkyFrame class supports +both the old FK4 model and the newer FK5 one. + +Coordinates expressed in any of these systems vary with time due to +movement (by definition) of the coordinate system itself, and must +therefore be qualified by a moment in time (the \emph{epoch of the mean +equinox}, or ``equinox'' for short) which specifies the position of +the model coordinate system on the sky. This is the role of the +Equinox attribute. + +Note that it is quite valid and common to relate the position of a +source to an equinox other than the date of observation. Usually a +standard equinox such as J2000.0 is used, meaning that the coordinates +are referred to axes defined by where the model mean equator and +ecliptic would lie on the sky at the Julian epoch J2000.0. +\end{description} +\end{quote} + +For further details of these attributes you should consult their +descriptions in \appref{ss:attributedescriptions} and for details of +the System settings for which they are relevant, see the description +of the System attribute (also in \appref{ss:attributedescriptions}). +For the interested reader, an excellent overview of celestial +coordinate systems can also be found in the documentation for the +SLALIB library (\xref{SUN/67}{sun67}{}). + +The value of these qualifying attributes is most conveniently set at +the same time as the System value, \emph{e.g.}\ when a SkyFrame is +created. For instance: + +\small +\begin{terminalv} +skyframe = astSkyFrame( "System=Ecliptic, Equinox=J2005.5" ); +\end{terminalv} +\normalsize + +would create a SkyFrame representing an ecliptic coordinate system +referred to the mean equinox and ecliptic of Julian epoch J2005.5. + +Note that it does no harm to assign values to qualifying attributes +which are not relevant to the main System value. Any such values are +stored, but are not used unless the System value is later set so that +they become relevant. + +\subsection{Using Default SkyFrame Attributes} + +The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend +on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this +means that there is usually little need to specify many of these +attributes explicitly unless you have some special requirement. This +can be illustrated by using \htmlref{astShow}{astShow} to examine a SkyFrame, as follows: + +\small +\begin{terminalv} +astShow( astSkyFrame( "System=FK4-NO-E, Epoch=1958" ) ); +\end{terminalv} +\normalsize + +The output from this might look like the following: + +\begin{terminalv} + Begin SkyFrame # Description of celestial coordinate system +# Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0; +epoch B1958.0" # Title of coordinate system + Naxes = 2 # Number of coordinate axes +# Domain = "SKY" # Coordinate system domain + Epoch = 1958 # Besselian epoch of observation +# Lbl1 = "Right ascension" # Label for axis 1 +# Lbl2 = "Declination" # Label for axis 2 + System = "FK4-NO-E" # Coordinate system type +# Uni1 = "hh:mm:ss.s" # Units for axis 1 +# Uni2 = "ddd:mm:ss" # Units for axis 2 +# Dir1 = 0 # Plot axis 1 in reverse direction +# Bot2 = -1.5707963267949 # Lowest legal axis value +# Top2 = 1.5707963267949 # Highest legal axis value + Ax1 = # Axis number 1 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + Ax2 = # Axis number 2 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + IsA Frame # Coordinate system description +# Eqnox = 1950 # Besselian epoch of mean equinox + End SkyFrame +\end{terminalv} + +Note that the defaults (indicated by the ``\verb?#?'' comment +character at the start of the line) for attributes such as the \htmlref{Title}{Title}, +axis Labels and Format specifiers are all set to values appropriate +for the particular equatorial coordinate system that the SkyFrame +represents. + +This means, for example, that if we were to use this SkyFrame to +format a right ascension value stored in radians using \htmlref{astFormat}{astFormat} +(\secref{ss:formattingaxisvalues}), it would automatically result in a +string in sexagesimal notation (such as ``12:14:35.7'') suitable for +display. If we changed the value of the SkyFrame's Digits attribute +(which is inherited from the \htmlref{Frame}{Frame} class), the number of digits +appearing would also change accordingly. + +These choices would be appropriate for a System value of ``FK4-NO-E'', +but if a different System value were set, the defaults would be +correspondingly different. For example, ecliptic longitude is +traditionally expressed in degrees, so setting ``System=ecliptic'' +would result in coordinate values being formatted as degrees by +default. + +Of course, if you do not like any of these defaults, you may always +over-ride them by setting explicit attribute values yourself. + +\subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates} + +SkyFrames use \htmlref{astFormat}{astFormat} for formatting coordinate values in the same +way as other Frames (\secref{ss:formattingaxisvalues}). However, they +offer a different set of formatting options more appropriate to +celestial coordinates. + +The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way +as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the +precision with which celestial coordinates are displayed can also be +adjusted in this way. However, the range of format specifiers that can +be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format +resulting from any particular Digits value, is different. + +The syntax of SkyFrame format specifiers is detailed under the +description of the Format(axis) attribute in +\appref{ss:attributedescriptions}. Briefly, however, it allows +celestial coordinates to be expressed either as angles or times and to +include one or more of the fields: + +\begin{quote} +\begin{itemize} +\item degrees or hours +\item arc-minutes or minutes +\item arc-seconds or seconds +\end{itemize} +\end{quote} + +with a specified number of decimal places for the final field. A range +of field separators is also available, as the following examples show: + +\begin{quote} +\begin{center} +\begin{tabular}{|l|l|} +\hline +\textbf{Format Specifier} & \textbf{Example Formatted Value}\\ +\hline \hline +{\tt{d}} & {\tt{219}}\\ +{\tt{d.3}} & {\tt{219.123}}\\ +{\tt{dm}} & {\tt{219:05}}\\ +{\tt{dm.2}} & {\tt{219:05.44}}\\ +{\tt{dms}} & {\tt{219:05:42}}\\ +{\tt{hms.1}} & {\tt{15:44:13.8}}\\ +{\tt{bdms.2}} & {\tt{219 05 42.81}}\\ +{\tt{lhms.3}} & {\tt{15h44m13.88s}}\\ +{\tt{+zlhms}} & {\tt{+06h10m44s}}\\ +{\tt{ms.1}} & {\tt{13145:42.8}}\\ +{\tt{lmst.3}} & {\tt{876m22.854s}}\\ +{\tt{s.2}} & {\tt{788742.81}}\\ +\hline +\end{tabular} +\end{center} +\end{quote} + +Note the following key points: + +\begin{itemize} +\item The required fields are specified using characters chosen from +either ``dms'' or ``hms'' according to whether the value is to be +formatted as an angle (in degrees) or a time (in hours). + +\item If no degrees or hours field is required, the distinction +between angle and time may be made by including ``t'' to request time. + +\item The number of decimal places (for the final field) is indicated +using ``\texttt{.}'' followed by an integer. An asterisk can be used in +place of an integer, in which case the number of decimal places is +chosen so that the total number of digits in the formatted value is equal +to the value of the Digits attribute. + +\item ``b'' causes fields to be separated by blanks, while ``l'' +causes them to be separated by the appropriate letters (the default +being a colon). + +\item ``z'' causes padding with leading zeros. + +\item ``+'' cause a plus sign to be prefixed to positive values +(negative values always have a minus sign). +\end{itemize} + +The formatting performed by a SkyFrame is also influenced by the +\htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each +SkyFrame axis. It determines whether the default format specifier for +an axis will present values as angles (\emph{e.g.}\ in degrees) if it +is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero. + +The default AsTime value depends on the celestial coordinate system +which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System} +attribute value. For example, equatorial longitude values (right +ascension) are normally expressed in hours, whereas ecliptic +longitudes are normally expressed in degrees, so their default AsTime +values will reflect this difference. + +The value of the AsTime attribute may be set explicitly to over-ride +these defaults if required, with the formatting precision being +determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the +Format(axis) attribute may be set explicitly to specify both the +format and precision required. Setting an explicit Format value always +over-rides the effects of both the Digits and AsTime attributes (unless +the Format value does not specify the required number of decimal places, +in which case Digits is used to determine the default number of decimal +places) + +\subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates} + +The process of converting formatted celestial coordinates, such as +might be produced by the \htmlref{astFormat}{astFormat} function +(\secref{ss:formattingskyaxisvalues}), into numerical (double) +coordinate values is performed by using \htmlref{astUnformat}{astUnformat} +(\secref{ss:unformattingaxisvalues}) and passing it a pointer to a +\htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats +accepted is appropriate to positions on the sky expressed as angles +and/or times, while the returned value is in radians. + +The following describes the forms of celestial coordinate which are +supported: + +\begin{itemize} +\item You may supply an optional sign, followed by between one and +three fields representing either degrees, arc-minutes, arc-seconds or +hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03''). + +\item Each field should consist of a sequence of one or more digits, +which may include leading zeros. At most one field may contain a +decimal point, in which case it is taken to be the final field +(\emph{e.g.}\ decimal degrees might be given as ``124.707'', while +degrees and decimal arc-minutes might be given as ``$-$13~33.8''). + +\item The first field given may take any value, allowing angles and +times outside the conventional ranges to be represented. However, +subsequent fields must have values of less than 60 (\emph{e.g.} +``720~45~31'' is valid, whereas ``11~45~61'' is not). + +\item Fields may be separated by white space or by ``:'' (colon), but +the choice of separator must be used consistently throughout the +value. Additional white space may be present around fields and +separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1''). + +\item The following field identification characters may be used as +separators to replace those above (or may be appended to the final +field), in order to identify the field to which they are appended: + +\begin{quote} +\begin{tabular}{lll} +d & -- & degrees \\ +h & -- & hours \\ +m & -- & minutes (of arc or time) \\ +s & -- & seconds (of arc or time) \\ +\texttt{'} & -- & arc-minutes \\ +\texttt{"} & -- & arc-seconds +\end{tabular} +\end{quote} + +Either lower or upper case may be used. Fields must be given in order +of decreasing significance +(\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s''). + +\item The presence of certain field identification characters +indicates whether the value is to be interpreted as an angle or a time +(with 24 hours corresponding to 360 degrees), as follows: + +\begin{quote} +\begin{tabular}{lll} +d & -- & angle \\ +\texttt{'} & -- & angle \\ +\texttt{"} & -- & angle \\ +h & -- & time +\end{tabular} +\end{quote} + +Incompatible angle/time identification characters may not be mixed +(\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid). The remaining +field identification characters and separators do not specify a +preference for an angle or a time and may be used with either. + +\item If no preference for an angle or a time is expressed anywhere +within the value, then it is interpreted as an angle if the Format +attribute string associated with the SkyFrame axis generates an angle +and as a time otherwise. This ensures that values produced by +astFormat (\secref{ss:formattingskyaxisvalues}) are correctly +interpreted by astUnformat. + +\item Fields may be omitted, in which case they default to zero. The +remaining fields may be identified by using appropriate field +identification characters (see above) and/or by adding extra colon +separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field +is not identified explicitly, it is assumed that adjacent fields have +been given, after taking account of any extra separator +characters. For example: + +\begin{quote} +\begin{tabular}{lll} +10d & -- & degrees \\ +10d12 & -- & degrees and arc-minutes \\ +11:14\texttt{"} & -- & arc-minutes and arc-seconds \\ +9h13s & -- & hours and seconds of time \\ +:45:33 & -- & minutes and seconds (of arc or time) \\ +:55: & -- & minutes (of arc or time) \\ +::13 & -- & seconds (of arc or time) \\ +$-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\ +07m14 & -- & minutes and seconds (of arc or time) \\ +$-$8:14\texttt{'} & -- & degrees and arc-minutes \\ +$-$h3:14 & -- & minutes and seconds of time \\ +h:2.1 & -- & seconds of time +\end{tabular} +\end{quote} + +\item If fields are omitted in such a way that the remaining ones +cannot be identified uniquely (e.g. ``01:02''), then the first field +(either given explicitly or implied by an extra leading colon +separator) is taken to be the most significant field that astFormat +would produce when formatting a value (using the Format attribute +associated with the SkyFrame axis). By default, this means that the +first field will normally be interpreted as degrees or hours. However, +if this does not result in consistent field identification, then the +last field (either given explicitly or implied by an extra trailing +colon separator) is taken to to be the least significant field that +astFormat would produce. + +\end{itemize} + +This final convention is intended to ensure that values formatted by +astFormat which contain less than three fields will be correctly +interpreted if read back using astUnformat, even if they do not +contain field identification characters. However, it also affects +other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set +to ``mst.1'' (producing two fields representing minutes and seconds of +time), then formatted input would be interpreted by astUnformat as +follows: + +\begin{quote} +\begin{tabular}{lll} +12 13 & -- & minutes and seconds \\ +12 & -- & minutes \\ +:13 & -- & seconds \\ +$-$18: & -- & minutes \\ +12.8 & -- & minutes \\ +1 2 3 & -- & hours, minutes and seconds \\ +& & \\ +4\texttt{'} & -- & arc-minutes \\ +60::\texttt{"} & -- & degrees \\ +$-$23:\texttt{"} & -- & arc-minutes \\ +$-$33h & -- & hours +\end{tabular} +\end{quote} + +(in the last four cases, explicit field identification has been given +which overrides the implicit identification). + +Alternatively, if the Format(axis) string were set to ``s.3'' +(producing only an arc-seconds field), then formatted input would be +interpreted by astUnformat as follows: + +\begin{quote} +\begin{tabular}{lll} +12.8 & -- & arc-seconds \\ +12 13 & -- & arc-minutes and arc-seconds \\ +:12 & -- & arc-seconds \\ +13: & -- & arc-minutes \\ +1 2 3 & -- & degrees, arc-minutes and arc-seconds +\end{tabular} +\end{quote} + +In general, if you are preparing formatted input data containing +celestial coordinates and wish to omit certain fields, then you are +advised to identify clearly those that you do provide by using the +appropriate field identification characters and/or extra colon +separators. This prevents you depending on the implicit field +identification described above which, in turn, depends on an +appropriate Format(axis) string having been set. + +When writing software, it is also a good idea to set the Format(axis) +string so that data input will be as simple as possible for the +user. Unless some special effect is desired, this normally means that +it should contain ``d'' or ``h'' to ensure that the first field +entered by the user will be interpreted as degrees or hours, unless +otherwise identified. This is the normal behaviour unless an explicit +Format(axis) value has been set to override the default. + +\subsection{Representing Offsets from a Specified Sky Position} +A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are +referred to an origin at any specified sky position. Such a coordinate +system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System} +attribute should be set to represent the celestial coordinate system in +which the origin is to be specified. Then the SkyRef attribute should be +set to hold the coordinates of the origin within the selected celestial +coordinate system. + +By default, ``north'' in the new offset coordinate system is parallel to +north in the original celestial coordinate system. However, the direction +of north in the offset system can be controlled by assigning a value to +the SkyRefP attribute. This attribute should be assigned the celestial +coordinates of a point which is on the zero longitude meridian and which +has non-zero latitude. + +By default, the position given by the SkyRef attribute is used as the +origin of the new longitude/latitude system, but an option exists to use +it as the north pole of the system instead. This option is controlled by +the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what +sort of offset coordinate system you want. Setting SkyRefIs to +``Origin'' (the default) produces an offset coordinate system which is +approximately Cartesian close to the specified position. Setting SkyRefIs +to +``Pole'' produces an offset coordinate system which is approximately Polar +close to the specified position. + +\cleardoublepage +\section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)} + +The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate +systems which describe a position within an electro-magnetic spectrum. +In this section we examine the additional properties and behaviour of a +SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}). + +\subsection{The SpecFrame Model} + +As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a +\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and +behaviour of these two ancestral classes. When used as a Mapping, a +SpecFrame implements a unit transformation, exactly like a basic Frame +(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its +behaviour is not of great importance. + +When used as a Frame, however, a SpecFrame represents a wide range of +different 1-dimensional coordinate system which can be used to describe +positions within a spectrum. The options available largely mirror those +described in the FITS-WCS paper III \emph{Representations of spectral +coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen). + +\subsection{Creating a SpecFrame} + +The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a +SpecFrame with default attributes is created as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstSpecFrame *specframe; + +... + +specframe = astSpecFrame( "" ); +\end{terminalv} +\normalsize + +Such a SpecFrame would represent the default coordinate system which is +heliocentric wavelength in metres (i.e. wavelength corrected to take into +account the Doppler shift caused by the velocity of the observer around the +sun). + +\subsection{Specifying a Particular Spectral Coordinate System} + +Selection of a particular coordinate system is performed simply by +setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System} +attribute. This setting is most conveniently done when the SpecFrame is +created. For example, a SpecFrame representing Energy would be created by: + +\small +\begin{terminalv} +specframe = astSpecFrame( "System=Energy" ); +\end{terminalv} +\normalsize + +Note that specifying ``System$=$Energy'' also changes the associated +Unit (from metres to Joules). This is because the default value +of the SpecFrame's Unit attribute depends on the System attribute setting. + +You may change the System value at any time, although this is not +usually needed. The values supported are set out in the attribute's +description in \appref{ss:attributedescriptions} and include a variety +of velocity systems, together with frequency, wavelength, energy, +wave-number, \emph{etc}. + +\subsection{Attributes which Qualify Spectral Coordinate Systems} + +Many spectral coordinate systems have some additional free parameters +which serve to identify a particular coordinate system from amongst a +broader class of related coordinate systems. For example, the +velocity systems are all parameterised by a rest frequency---the +frequency which defines zero velocity, and all coordinate systems +are qualified by a `standard of rest'' which indicates the rest frame to +which the values refer. + +In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame} +attributes, each of which has a default appropriate to +(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} +attribute. Each of these \emph{qualifying attributes} may, however, be +assigned an explicit value so as to select a particular coordinate +system. Note, it is usually best to assign explicit +values whenever possible rather than relying on defaults. Attribute +should only be left at their default value if you ``don't care'' what +value is used. In certain circumstances (particularly, when aligning two +Frames), a default value for an attribute may be replaced by the value +from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by +assigning an explicit value to the attribute, rather than simply relying on +the default. + + +The main SpecFrame attributes which qualify the System attribute are: + +\begin{quote} +\begin{description} + +\item[\htmlref{Epoch}{Epoch}]\mbox{}\\ +This attribute is inherited from the Frame class. It gives the moment in +time when the coordinates are correct for the astronomical source +under study (usually the date of observation). It is needed in order to +calculate the Doppler shift produced by the velocity of the observer +relative to the centre of the earth, and of the earth relative to the sun. + +\item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\ +This specifies the rest frame in which the coordinates are correct. +Transforming between different standards of rest involves taking account +of the Doppler shift introduced by the relative motion of the two +standards of rest. + +\item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\ +Specifies the frequency which correspond to zero velocity. When setting a +value for this attribute, the value may be supplied as a wavelength +(including an indication of the units being used, ``nm'' ``Angstrom'', +\emph{etc.}), which will be automatically be converted to a frequency. + +\item[\htmlref{RefRA}{RefRA}]\mbox{}\\ +Specifies the RA (FK5 J2000) of the source. This is used when converting +between standards of rest. It specifies the direction along which the +component of the relative velocity of the two standards of rest is taken. + +\item[\htmlref{RefDec}{RefDec}]\mbox{}\\ +Specifies the Dec (FK5 J2000) of the source. Used in conjunction with +REFRA. + +\item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\ +This defines the ``source'' standard of rest. This is a rest frame which +is moving towards the position given by RefRA and RefDec, at a velocity +given by SourceVel. The velocity is stored internally as a heliocentric +velocity, but can be given in any of the other supported standards of rest. + +\end{description} +\end{quote} + +For further details of these attributes you should consult their +descriptions in \appref{ss:attributedescriptions} and for details of +the System settings for which they are relevant, see the description +of the System attribute (also in \appref{ss:attributedescriptions}). + +Note that it does no harm to assign values to qualifying attributes +which are not relevant to the main System value. Any such values are +stored, but are not used unless the System value is later set so that +they become relevant. + +\subsection{Using Default SpecFrame Attributes} + +The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend +on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this +means that there is usually little need to specify many of these +attributes explicitly unless you have some special requirement. This +can be illustrated by using \htmlref{astShow}{astShow} to examine a SpecFrame, as follows: + +\small +\begin{terminalv} +astShow( astSpecFrame( "System=Vopt, RestFreq=250 GHz" ) ); +\end{terminalv} +\normalsize + +The output from this might look like the following: + +\begin{terminalv} + Begin SpecFrame # Description of spectral coordinate system +# Title = "Optical velocity, rest frequency = 250 GHz" # Title +of coordinate system + Naxes = 1 # Number of coordinate axes +# Domain = "SPECTRUM" # Coordinate system domain +# Epoch = 2000 # Julian epoch of observation +# Lbl1 = "Optical velocity" # Label for axis 1 + System = "VOPT" # Coordinate system type +# Uni1 = "km/s" # Units for axis 1 + Ax1 = # Axis number 1 + Begin Axis # Coordinate axis + End Axis + IsA Frame # Coordinate system description +# SoR = "Heliocentric" # Standard of rest + RstFrq = 250000000000 # Rest frequency (Hz) + End SpecFrame +\end{terminalv} + +Note that the defaults (indicated by the ``\verb?#?'' comment +character at the start of the line) for attributes such as the \htmlref{Title}{Title}, +axis Labels and Unit specifiers are all set to values appropriate +for the particular velocity system that the SpecFrame represents. + +These choices would be appropriate for a System value of ``Vopt'', +but if a different System value were set, the defaults would be +correspondingly different. For example, by default frequency is measured in +units of GHz, not $km/s$, so setting ``System=freq'' +would change the appropriate line above from: + +\begin{terminalv} +# Uni1 = "km/s" # Units for axis 1 +\end{terminalv} + +to + +\begin{terminalv} +# Uni1 = "GHz" # Units for axis 1 +\end{terminalv} + +Of course, if you do not like any of these defaults, you may always +over-ride them by setting explicit attribute values yourself. For +instance, you may choose to have your frequency axis expressed in ``kHz'' +rather than ``GHz''. To do this simply set the attribute value as follows: + +\small +\begin{terminalv} +astSetC( specframe, "Unit", "kHz" ); +\end{terminalv} +\normalsize + +No error will be reported if you accidentally set an inappropriate Unit value +(say "J" - Joules)---after all, AST cannot tell what you are about to do, +and you \emph{may} be about to change the System value to ``Energy''. +However, an error \emph{will} be reported if you attempt to find a +conversion between two SpecFrames (for instance using +\htmlref{astConvert}{astConvert} +) if either SpecFrame has a Unit value which is inappropriate for its +System value. + +SpecFrame attributes, like all other attributes, all have default +value. However, be aware that for some attributes these default values +can never be more than ``a legal numerical value'' and have no +astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes +(which give the source position) both have a default value of zero. So +unless your source happens to be at that point (highly unlikely!) you will +need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute +has an arbitrary default value of 1.0E5 GHz. Some operations are not +affected by inappropriate values for these attributes (for instance, +converting from frequency to wavelength, changing axis units, \emph{etc}), +but some are. For instance, converting from frequency to velocity +requires a correct rest frequency, moving between different standards of +rest requires a correct source position. The moral is, always set explicit +values for as many attributes as possible. + +\subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes} +You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube +containing two spatial axes and a spectral axis. To do this you would +create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame} +(often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine +these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}. + +\small +\begin{terminalv} +AstSkyFrame *skyframe; +AstSpecFrame *specframe; +AstCmpFrame *cmpframe; +... +skyframe = astSkyFrame( "Epoch=J2002" ); +specframe = astSpecFrame( "System=Freq,StdOfRest=LSRK" ); +cmpframe = astCmpFrame( skyframe, specframe, "" ); +\end{terminalv} +\normalsize + +In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis +3 will be Frequency. If this is not the order you want, you can permute +the axes using +\htmlref{astPermAxes}{astPermAxes}. + +There is one potential problem with this approach if you are interested in +unusually high accuracy. Conversion between different standards of rest +involves taking account of the Doppler shift caused by the relative +motion of the two standards of rest. At some point this involves finding +the component of the relative velocity in the direction of interest. +For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} +attributes, even if the SpecFrame is embedded within a CmpFrame as above. +It would be more appropriate if this ``direction of interest'' was +specified by the values passed into the CmpFrame on the RA and DEC axes, +allowing each pixel within a data cube to have a slightly different +correction for Doppler shift. + +Unfortunately, the SpecFrame class cannot do this (since it is purely a +1-dimensional Frame), and so some small degree of error will be +introduced when converting between standards of rest, the size of the +error varying from pixel to pixel. It is hoped that at some point in the +future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which +allows for this spatial variation in Doppler shift. + +The maximum velocity error introduced by this problem is of the order of +$V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the +relative velocity of the two standards of rest. As an example, when +correcting from the observers rest frame (i.e. the topocentric rest +frame) to the kinematic local standard of rest the maximum value of $V$ +is about 20 $km/s$, so for 5 arc-minute field of view the maximum +velocity error introduced by the correction will be about 0.03 $km/s$. As +another example, the maximum error when correcting from the observers +rest frame to the local group is about 5 $km/s$ over a 1 degree field of +view. + +\subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra} +Dual sideband super-heterodyne receivers produce spectra in which each channel +contains contributions from two different frequencies, referred to as the +``upper sideband frequency'' and the ``lower sideband frequency''. In the +rest frame of the observer (topocentric), these are related to each other as +follows: + +\begin{quote} +\begin{small} +\begin{equation} +\label{eqn:dsb} + f_{lsb} = 2.f_{LO} - f_{usb} +\end{equation} +\end{small} +\end{quote} + +where $f_{LO}$ is a fixed frequency known as the ``local oscillator +frequency''. In other words, the local oscillator frequency is always +mid-way between any pair of corresponding upper and lower sideband +frequencies\footnote{Note, this simple relationship only applies if all +frequencies are topocentric.}. If you want to describe the spectral axis +of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the +SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot +describe both sidebands simultaneously. However, there is a sub-class of +SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty. + +A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the +DSBSpecFrame is currently being used to describe the upper or lower +sideband spectral axis. The value of this attribute can be changed at any +time. If you use the +\htmlref{astConvert}{astConvert} +function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for +the two SideBand attributes will be taken into account. Thus, if you take +a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use +astConvert +to find a Mapping from the original to the modified copy, the resulting +Mapping will be of the form of equation \ref{eqn:dsb} (if the +DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric''). + +In general, when finding a Mapping between two arbitrary DSBSpecFrames, +the total Mapping is made of of three parts in series: + +\begin{enumerate} +\item A Mapping which converts the first DSBSpecFrame into its upper +sideband representation. If the DSBSpecFrame already represents its upper +sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}. +\item A Mapping which converts from the first to the second DSBSpecFrame, +treating them as if they were both basic SpecFrames. This takes account of +any difference in units, standard of rest, system, \emph{etc} between the +two DSBSpecFrames. +\item A Mapping which converts the second DSBSpecFrame from its upper +sideband representation to its current sideband. If the DSBSpecFrame +currently represents its upper sideband, this Mapping will be a UnitMap. +\end{enumerate} + +If an attempt is made to find the Mapping between a DSBSpecFrame and a +basic SpecFrame, then the DSBSpecFrame will be treated like a basic +SpecFrame. In other words, the returned Mapping will not be affected by +the setting of the SideBand attribute (or any of the other attributes +specific to the DSBSpecFrame class). + +In practice, the local oscillator frequency for a dual sideband +instrument may not be easily available to an observer. Instead, it is +common practice to specify the spectral position of some central feature +in the observation (commonly the centre of the instrument passband), +together with an ``intermediate frequency''. Together, these two values +allow the local oscillator frequency to be determined. The intermediate +frequency is the difference between the topocentric frequency at the +central spectral position and the topocentric frequency of the local +oscillator. So: + +\begin{quote} +\begin{small} +\begin{equation} +\label{eqn:dsb2} + f_{LO} = f_{central} + f_{if} +\end{equation} +\end{small} +\end{quote} + +The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central +spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the +intermediate frequency ($f_{if}$). The DSBCentre value is given and returned +in the spectral system described by the DSBSpecFrame (thus you do not need to +calculate the corresponding topocentric frequency yourself - this will be +done automatically by the DSBSpecFrame when you assign a new value to the +DSBCentre attribute). The value assigned to the IF attribute should +always be a topocentric frequency in units of Hz, however a negative +value may be given to indicate that the DSBCentre value is in the upper +sideband (that is, if $IF < 0$ then $f_{central} > f_{LO}$). A positive +value for IF indicates that the DSBCentre value is in the lower sideband +(that is, if $IF > 0$ then $f_{central} < f_{LO}$). + + +\cleardoublepage +\section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)} + +The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in +time. In this section we examine the additional properties and behaviour of a +TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}). + +\subsection{The TimeFrame Model} + +As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a +\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and +behaviour of these two ancestral classes. When used as a Mapping, a +TimeFrame implements a unit transformation, exactly like a basic Frame +(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its +behaviour is not of great importance. + +When used as a Frame, however, a TimeFrame represents a wide range of +different 1-dimensional coordinate system which can be used to describe +moments in time. Absolute times and relative (i.e. elapsed) times are +supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales +(attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can +be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch}, +\emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to +allow them to be used with any unit of time (attribute Unit). The TimeFrame +class also allows times to formatted as either a simple floating point value +or as a Gregorian date and time of day (attribute Format). + +\subsection{Creating a TimeFrame} + +The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a +TimeFrame with default attributes is created as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstTimeFrame *timeframe; + +... + +timeframe = astTimeFrame( "" ); +\end{terminalv} +\normalsize + +Such a TimeFrame would represent the default coordinate system which is +Modified Julian Date (with the usual units of days) in the International +Atomic Time (TAI) time scale. + +\subsection{Specifying a Particular Time System} +By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent +Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the +time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}). + +Selection of a particular coordinate system is performed simply by +setting a value for the TimeFrame's (character string) System +attribute. This setting is most conveniently done when the TimeFrame is +created. For example, a TimeFrame representing Julian Epoch would be created +by: + +\small +\begin{terminalv} +timeframe = astTimeFrame( "System=JEPOCH" ); +\end{terminalv} +\normalsize + +Note that specifying ``System$=$JEPOCH'' also changes the associated +default Unit (from days to years). This is because the default value +of the TimeFrame's Unit attribute depends on the System attribute setting. + +You may change the System value at any time, although this is not +usually needed. The values supported are set out in the attribute's +description in \appref{ss:attributedescriptions}. + +\subsection{Attributes which Qualify Time Coordinate Systems} + +Time coordinate systems require some additional free parameters to identify +a particular coordinate system from amongst a broader class of related +coordinate systems. For example, all TimeFrames are qualified by the time +scale (that is, the physical process used to define the flow of time), +and some require the position of the observer's clock. + +In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame} +attributes, each of which has a default appropriate to (\emph{i.e.}\ defined +by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying +attributes} may, however, be assigned an explicit value so as to select a +particular coordinate system. Note, it is usually best to assign explicit +values whenever possible rather than relying on defaults. Attribute +should only be left at their default value if you ``don't care'' what +value is used. In certain circumstances (particularly, when aligning two +Frames), a default value for an attribute may be replaced by the value +from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by +assigning an explicit value to the attribute, rather than simply relying on +the default. + +The main TimeFrame attributes which qualify the System attribute are: + +\begin{quote} +\begin{description} + +\item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\ +This specifies the time scale. + +\item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\ +This specifies the offset from Local Time to UTC in hours (time zones +east of Greenwich have positive values). Note, AST uses the value as +supplied without making any correction for daylight saving. + +\item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\ +This specifies the zero point from which time values are measured, within +the system specified by the System attribute. Thus, a value of zero (the +default) indicates that time values represent absolute times. Non-zero +values may be used to indicate that the TimeFrame represents elapsed time +since the specified origin. + +\end{description} +\end{quote} + +For further details of these attributes you should consult their +descriptions in \appref{ss:attributedescriptions} and for details of +the System settings for which they are relevant, see the description +of the System attribute (also in \appref{ss:attributedescriptions}). + +Note that it does no harm to assign values to qualifying attributes +which are not relevant to the main System or TimeScale value. Any such +values are stored, but are not used unless the System and/or TimeScale +value is later set so that they become relevant. + +\cleardoublepage +\section{\label{ss:cmpframes}Compound Frames (CmpFrames)} + +We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The +Frames we have considered so far have been atomic, in the sense that +they represent pre-defined elementary physical domains. A CmpFrame, +however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for +containing other Frames and its purpose is to allow those Frames +to work together in various combinations while appearing as a single +\htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is +determined by the other Frames it contains (its ``component'' Frames). + +As with compound Mappings, compound Frames can be nested within each +other, forming arbitrarily complex Frames. + +\subsection{Creating a CmpFrame} +A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a +``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes +represents position within a spectrum, and the other two axes represent +position on the sky (or some other spatial domain such as the focal plane +of a telescope). As an example, we create such a CmpFrame in which axes +1 and 2 represent Right Ascension and Declination (ICRS), and axis 3 +represents wavelength (these are the default coordinate Systems +represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively): + +\small +\begin{terminalv} +AstSkyFrame *skyframe; +AstSpecFrame *specframe; +AstCmpFrame *cmpframe; +... +skyframe = astSkyFrame( "" ); +specframe = astSpecFrame( "" ); +cmpframe = astCmpFrame( skyframe, specframe, "" ); +\end{terminalv} +\normalsize + +If it was desired to make RA and Dec correspond to axes 1 and 3, with +axis 2 being the spectral axis, then the axes of the CmpFrame created +above would need to be permuted as follows: + +\small +\begin{terminalv} +int perm[ 3 ]; +... + +perm[ 0 ] = 0; +perm[ 1 ] = 2; +perm[ 2 ] = 1; +astPermAxes( cmpframe, perm ); +\end{terminalv} +\normalsize + +\subsection{The Attributes of a CmpFrame} + +A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame. +The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by +concatenating the Domains of the two component Frames, separated by a +minus sign (``-'').\footnote{If both component Frames have blank Domains, +then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed) +value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to +change the System value of a CmpFrame is ignored.} A CmpFrame has no +further attributes over and above those common to all Frames. However, +attributes of the two component Frames can be accessed as if they were +attributes of the CmpFrame, as described below. + +Frame attributes which are specific to individual axes (such as Label(2), +Format(1), \emph{etc}) simply mirror the corresponding axes of the +relevant component Frame. That is, if the ``Label(2)'' attribute of a +CmpFrame is accessed, the CmpFrame will forward the access request to the +component Frame which contains axis 2. Thus, default values for axis +attributes will be the same as those provided by the component Frames. + +An axis index can optionally be appended to the name of Frames attributes +which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title}, +\emph{etc}). If this is done, the access request is forwarded to the +component Frame containing the indicated axis. For instance, if a +CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes +have not been permuted, then getting the value of attribute ``System'' will +return ``Compound'' as mentioned above (that is, the System value of the +CmpFrame as a whole), whereas getting the value of attribute +``System(1)'' will return ``Spectral''(that is, the System value of the +component Frame containing axis 1 --- the SpecFrame). + +This technique is not limited to attributes common to all Frames. For +instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is +not held by other classes of Frames. To set a value for the Equinox +attribute of the SkyFrame contained within the above CmpFrame, assign the +value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame +defines both axes 2 and 3 of the CmpFrame, we could equivalently have set +a value for ``Equinox(3)'' since this would also result in the attribute +access being forwarded to the SkyFrame. + +Finally, if an attribute is not qualified by a axis index, attempts will +be made to access it using each of the CmpFrame axes in turn. Using the +above example of the spectral cube, if an attempt was made to get the +value of attribute ``Equinox'' (with no axis index), each axis in turn +would be used. Since axis 1 is contained within a SpecFrame, the first +attempt would fail since the SpecFrame class does not have an Equinox +attribute. However, the second attempt would succeed because axis 2 is +contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus +the returned attribute value would be that obtained from the SkyFrame +containing axis 2. When getting or testing an attribute value, the +returned value is determined by the \emph{first} axis which recognises +the attribute. When setting an attribute value, \emph{all} axes +which recognises the attribute have the attribute value set to the given +value. Likewise, when clearing an attribute value, all axes +which recognises the attribute have the attribute value cleared. + +\cleardoublepage +\section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions} + +In this section, we start to look at techniques for converting between +different coordinate systems. At this stage, the tools we have available +are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}), +SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and +various Mappings (\secref{ss:mappings}). These are sufficient to allow us to +begin examining the problem, but more sophisticated approaches will also emerge +later (\secref{ss:framesetconverting}). + +\subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems} + +We begin by examining how to convert between two celestial coordinate +systems represented by SkyFrames, as this is both an illuminating and +practical example. Consider the problem of converting celestial +coordinates between: + +\begin{enumerate} +\item The old FK4 system, with no E terms, a Besselian epoch of +1958.0 and a Besselian equinox of 1960.0. + +\item An ecliptic coordinate system based on the mean equinox and +ecliptic of Julian epoch 2010.5. +\end{enumerate} + +This example is arbitrary but not completely unrealistic. Unless you +already have expertise with such conversions, you are unlikely to find +it straightforward. + +Using AST, we begin by creating two SkyFrames to represent these +coordinate systems, as follows: + +\small +\begin{terminalv} +#include "ast.h" +AstSkyFrame *skyframe1, *skyframe2; + +... + +skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); +skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); +\end{terminalv} +\normalsize + +Note how specifying the coordinate systems consists simply of +initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately. The next +step is to find a way of converting between these SkyFrames. This is +done using \htmlref{astConvert}{astConvert}, as follows: + +\small +\begin{terminalv} +AstFrameSet *cvt; + +... + +cvt = astConvert( skyframe1, skyframe2, "" ); +if ( cvt == AST__NULL ) { + <conversion is not possible> +} else { + <conversion is possible> +} +\end{terminalv} +\normalsize + +The third argument of astConvert is not used here and should be an +empty string. + +astConvert will return a null result, AST\_\_NULL (as defined in the +``ast.h'' header file), if conversion is not possible. In this +example, conversion is possible, so it will return a pointer to a new +\htmlref{Object}{Object} that describes the conversion. + +The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed +FrameSets yet (\secref{ss:framesets}), but for the present purposes we +can consider them simply as Objects that can behave both as Mappings +and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we +are mainly interested here, because the Mapping it implements is the +one we require---\emph{i.e.}\ it converts between the two celestial +coordinate systems (\secref{ss:framesetsfromconvert}). + +For example, if ``alpha1'' and ``delta1'' are two arrays containing +the longitude and latitude, in radians, of N points on the sky in the +original coordinate system (corresponding to ``skyframe1''), then they +could be converted into the new coordinate system (represented by +``skyframe2'') as follows: + +\small +\begin{terminalv} +#define N 10 +double alpha1[ N ], delta1[ N ]; +double alpha2[ N ], delta2[ N ]; + +... + +astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); +\end{terminalv} +\normalsize + +The new coordinates are returned \emph{via} the ``alpha2'' and +``delta2'' arrays. To transform coordinates in the opposite +direction, we simply invert the 5th (boolean int) argument to +\htmlref{astTran2}{astTran2}, as follows: + +\small +\begin{terminalv} +astTran2( cvt, N, alpha2, delta2, 0, alpha1, delta1 ); +\end{terminalv} +\normalsize + +The FrameSet returned by astConvert also contains information about +the SkyFrames used in the conversion +(\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet +may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the +``destination'' Frame used in the conversion (\emph{i.e.}\ like +``skyframe2''). We could therefore use the ``cvt'' FrameSet to +calculate the distance between two points (with coordinates in +radians) in the destination coordinate system, using \htmlref{astDistance}{astDistance}: + +\small +\begin{terminalv} +double distance, point1[ 2 ], point2[ 2 ]; + +... + +distance = astDistance( cvt, point1, point2 ); +\end{terminalv} +\normalsize + +and the result would be the same as if the ``skyframe2'' SkyFrame had +been used. + +Another way to see how the FrameSet produced by astConvert retains +information about the coordinate systems involved is to set its \htmlref{Report}{Report} +attribute (inherited from the Mapping class) so that it displays the +coordinates before and after conversion (\secref{ss:transforming}): + +\small +\begin{terminalv} +astSet( cvt, "Report=1" ); +astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); +\end{terminalv} +\normalsize + +The output from this might look like the following: + +\begin{terminalv} +(2:06:03.0, 34:22:39) --> (42.1087, 20.2717) +(2:08:20.6, 35:31:24) --> (43.0197, 21.1705) +(2:10:38.1, 36:40:09) --> (43.9295, 22.0716) +(2:12:55.6, 37:48:55) --> (44.8382, 22.9753) +(2:15:13.1, 38:57:40) --> (45.7459, 23.8814) +(2:17:30.6, 40:06:25) --> (46.6528, 24.7901) +(2:19:48.1, 41:15:11) --> (47.5589, 25.7013) +(2:22:05.6, 42:23:56) --> (48.4644, 26.6149) +(2:24:23.1, 43:32:41) --> (49.3695, 27.5311) +(2:26:40.6, 44:41:27) --> (50.2742, 28.4499) +\end{terminalv} + +Here, we see that the input FK4 equatorial coordinate values (given in +radians) have been formatted automatically in sexagesimal notation +using the conventional hours for right ascension and degrees for +declination. Conversely, the output ecliptic coordinates are shown in +decimal degrees, as is conventional for ecliptic coordinates. Both are +displayed using the default precision of 7 digits.\footnote{The +leading digit is zero and is therefore not seen in this particular +example.} + +In fact, the ``cvt'' FrameSet has access to all the information in the +original SkyFrames which were passed to astConvert. If you had set a +new Digits attribute value for either of these, the formatting above +would reflect the different precision you requested by displaying a +greater or smaller number of digits. + + +\subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems} +The principles described in the previous section for converting between +celestial coordinate systems also apply to the task of converting between +spectral coordinate systems. As an example, let's look at how we might +convert between frequency measured in $GHz$ as measured in the rest frame +of the telescope, and radio velocity measured in $km/s$ measured with +respect the kinematic Local Standard of Rest. + +First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to +describe the required radio velocity system (this is slightly more +convenient, given the relatively large number of attributes, than +specifying the attribute values in a single string such as would be +passed to the SpecFrame constructor). We then take a copy of this +SpecFrame, and change the attribute values so that the copy describes the +original frequency system (modifying a copy, rather than creating a new +SpecFrame from scratch, avoids the need to specify the epoch, reference +position, \emph{etc} a second time since they are all inherited by the copy): + +\small +\begin{terminalv} +#include "ast.h" +AstSpecFrame *specframe1, *specframe2; + +... + +specframe1 = astSpecFrame( "" ); +astSet( specframe1, "System=vradio" ); +astSet( specframe1, "Unit=km/s" ); +astSet( specframe1, "Epoch=1996-Oct-2 12:13:56.985" ); +astSet( specframe1, "ObsLon=W155:28:18" ); +astSet( specframe1, "ObsLat=N19:49:34" ); +astSet( specframe1, "RefRA=18:14:50.6" ); +astSet( specframe1, "RefDec=-4:40:49" ); +astSet( specframe1, "RestFreq=230.538 GHz" ); +astSet( specframe1, "StdOfRest=LSRK" ); + +specframe2 = astCopy( specframe1 ); +astSet( specframe1, "System=freq" ); +astSet( specframe1, "Unit=GHz" ); +astSet( specframe1, "StdOfRest=Topocentric" ); + +\end{terminalv} +\normalsize + +Note, the fact that a SpecFrame has only a single axis means that we were +able to refer to the Unit attribute without an axis index. The other +attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical +position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source +on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the +standard of rest (\htmlref{StdOfRest}{StdOfRest}). + +The next step is to find a way of converting between these SpecFrames. We +use exactly the same code that we did in the previous section where we were +converting between celestial coordinate systems: + +\small +\begin{terminalv} +AstFrameSet *cvt; + +... + +cvt = astConvert( specframe1, specframe2, "" ); +if ( cvt == AST__NULL ) { + <conversion is not possible> +} else { + <conversion is possible> +} +\end{terminalv} +\normalsize + +A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible, +which should always be the case for our example), and we can use the +FrameSet to convert between the two spectral coordinate systems. We use +\htmlref{astTran1}{astTran1} in place of \htmlref{astTran2}{astTran2} +since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two). + +For example, if ``frq'' is an array containing the observed frequency, in +GHz, of N spectral channels (describe by ``specframe1''), then they +could be converted into the new coordinate system (represented by +``specframe2'') as follows: + +\small +\begin{terminalv} +#define N 10 +double frq[ N ]; +double vel[ N ]; + +... + +astTran1( cvt, N, frq, 1, vel ); +\end{terminalv} +\normalsize + +The radio velocity values are returned in the ``vel'' array. + + +\subsection{Converting between Time Coordinate Systems} +All the principles outlined in the previous section about aligning +spectral cocordinate systems (SpecFrames) can be applied directly to the +problem of aligning time coordinate systems (TimeFrames). + +\subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations} + +We can illustrate an important point if we swap the axis order of +either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes}) +before identifying the conversion. Let's assume we use \htmlref{astPermAxes}{astPermAxes} +(\secref{ss:permutingaxes}) to do this to the second SkyFrame, before +applying \htmlref{astConvert}{astConvert}, as follows: + +\small +\begin{terminalv} +int perm[ 2 ] = { 2, 1 }; + +... + +astPermAxes( skyframe2, perm ); +cvt = astConvert( skyframe1, skyframe2, "" ); +\end{terminalv} +\normalsize + +Now, the destination SkyFrame system no longer represents the +coordinate system: + +\begin{quote} +(ecliptic~longitude, ecliptic~latitude) +\end{quote} + +but instead represents the transposed system: + +\begin{quote} +(ecliptic~latitude, ecliptic~longitude) +\end{quote} + +As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by astConvert to +apply a coordinate transformation, we obtain something like the +following: + +\begin{terminalv} +(2:06:03.0, 34:22:39) --> (20.2717, 42.1087) +(2:08:20.6, 35:31:24) --> (21.1705, 43.0197) +(2:10:38.1, 36:40:09) --> (22.0716, 43.9295) +(2:12:55.6, 37:48:55) --> (22.9753, 44.8382) +(2:15:13.1, 38:57:40) --> (23.8814, 45.7459) +(2:17:30.6, 40:06:25) --> (24.7901, 46.6528) +(2:19:48.1, 41:15:11) --> (25.7013, 47.5589) +(2:22:05.6, 42:23:56) --> (26.6149, 48.4644) +(2:24:23.1, 43:32:41) --> (27.5311, 49.3695) +(2:26:40.6, 44:41:27) --> (28.4499, 50.2742) +\end{terminalv} + +When compared to the original (\secref{ss:convertingskyframes}), the +output coordinate order has been swapped to compensate for the +different destination SkyFrame axis order. + +In all, there are four possible axis combinations, corresponding to two +possible axis orders for each of the source and destination SkyFrames, +and astConvert will convert correctly between any of these. +The point to note is that a SkyFrame contains knowledge about how to +convert to and from other SkyFrames. Since its two axes (longitude and +latitude) are distinguishable, the conversion is able to take account +of the axis order. + +If you need to identify the axes of a SkyFrame explicitly, taking into +account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be +used. These are read-only attributes which give the indices of the +latitude and longitude axes respectively. + +\subsection{\label{ss:convertingframes}Converting Between Frames} + +Having seen how clever SkyFrames are (\secref{ss:convertingskyframes} +and \secref{ss:convertingpermutedaxes}), we will next examine how dumb +a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two +2-dimensional Frames and use \htmlref{astConvert}{astConvert} to derive a conversion between +them, as follows: + +\small +\begin{terminalv} +AstFrame *frame1, *frame2; + +... + +frame1 = astFrame( 2, "" ); +frame2 = astFrame( 2, "" ); +cvt = astConvert( frame1, frame2, "" ); +\end{terminalv} +\normalsize + +then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs +will be as follows: + +\begin{terminalv} +(1, 2) --> (1, 2) +(2, 4) --> (2, 4) +(3, 6) --> (3, 6) +(4, 8) --> (4, 8) +(5, 10) --> (5, 10) +\end{terminalv} + +This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap} +(\secref{ss:unitmapexample}). Even if we permute the axis order of our +Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will +fare no better. The conversion between our two basic Frames will +always be an identity transformation. + +The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start +life the same and have axes that are indistinguishable. Therefore, +permuting their axes doesn't make them look any different---they still +represent the same coordinate system. +%Actually, this behaviour isn't as dumb as it seems and can actually be +%very useful, as the following example illustrates. +% +%\subsection{Distinguishable and Indistinguishable Axes} +% +%c+ +%Imagine you have two Frames which represent the pixel coordinates of +%two 2-dimensional images. Let's call their axes ``X'' and ``Y''. +%Suppose you now transpose the second image and swap its Frame axes +%(with \htmlref{astPermAxes}{astPermAxes}) to take account of this. +%c- +%f+ +%Imagine you have two Frames which represent the pixel coordinates of +%two 2-dimensional images. Let's call their axes ``X'' and ``Y''. +%Suppose you now transpose the second image and swap its Frame axes +%(with astPermAxes) to take account of this. +%f- +% +%Next, consider what happens if you want to subtract one image from the +%other. If you have a ``subtract'' program that is intelligent and +%tries to align the two images for you, one of two things could happen: +% +%\begin{enumerate} +%c+ +%\item If the axes are distinguishable, when your program invokes +%astConvert it will derive a transformation between the two images +%which swaps the X and Y coordinates (corresponding to the transposition +%you applied to the second image). However, in aligning X-with-X and +%Y-with-Y, this will completely undo the effects of your transposition! +%c- +%f+ +%\item If the axes are distinguishable, when your program invokes +%AST\_CONVERT it will derive a transformation between the two images +%which swaps the X and Y coordinates (corresponding to the transposition +%you applied to the second image). However, in aligning X-with-X and +%Y-with-Y, this will completely undo the effects of your transposition! +%f- +% +%\item If the axes are indistinguishable, the transformation between +%the two images will always be an identity +%(\secref{ss:convertingframes}). Therefore, your program will align +%X-with-Y and Y-with-X, so that you see the effects of your earlier +%transposition of the second image. +%\end{enumerate} +% +%Clearly, if we are considering pixel coordinates, the latter behaviour +%is preferable, since there would be no point in implementing an image +%transposition program if we could never see the effects of it. This +%indicates that a basic Frame, with is indistinguishable axes, is the +%correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where +%this behaviour is necessary. +% +%Conversely, the former behaviour would be more useful if the axes we +%were considering were, say, wavelength (in nm) and slit position (in +%mm). In this case, we would expect our ``subtract'' program to +%subtract data at corresponding wavelengths and slit positions, not +%just at corresponding pixels. This case requires distinguishable axes, +%so that corresponding axes in the two images can be matched up, just +%as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}). +% +%Of course, there may also be intermediate cases, where some axes are +%distinguishable and others aren't. + +\subsection{\label{ss:alignmentsystem}The Choice of Alignment System} + +In practice, when AST is asked to find a conversion between two Frames +describing two different coordinate systems on a given physical domain, +it uses an intermediate ``alignment'' system. Thus, when finding a +conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from +system A to some alignment system, system C, and then finds the Mapping +from this system C to the required system B. It finally concatenates +these two Mappings to get the Mapping from system A to system B. + +One advantage of this is that it cuts down the number of conversion +algorithms required. If there are $N$ different Systems which may be used +to describe positions within the \htmlref{Domain}{Domain}, then this approach requires +about $2*N$ conversion algorithms to be written. The alternative approach +of going directly from system A to system B would require about $N*N$ +conversion algorithms. + +In addition, the use of an intermediate alignment system highlights the +nature of the conversion process. What do we mean by saying that a +Mapping ``converts a position in one coordinate system into the +corresponding position in another''? In practice, it means that the input +and output coordinates correspond to the same coordinates \emph{in some +third coordinate system}. The choice of this third coordinate system, the +``alignment'' system, can completely alter the nature of the Mapping. The +\htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to +specify the alignment system. + +As an example, consider the case of aligning two spectra calibrated in +radio velocity, but each with a different rest frequency (each spectrum +will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a +given velocity will correspond to different frequencies in the two +spectra. So when we come to ``align'' these two spectra (that is, find a +Mapping which converts positions in one SpecFrame to the corresponding +positions in the other), we have the choice of aligning the frequencies +or aligning the velocities. Different Mappings will be required to +describe these two forms of alignment. If we set AlignSystem to ``Freq'' +then the returned Mapping will align the frequencies described by the two +SpecFrames. On the other hand, if we set AlignSystem to ``Vradio'' +then the returned Mapping will align the velocities. + +Some choices of alignment system are redundant. For instance, in the +above example, changing the alignment system from frequency to wavelength +has no effect on the returned Mapping: if two spectra are aligned in +frequency they will also be aligned in wavelength (assuming the speed of +light doesn't change). + +The default value for AlignSystem depends on the class of Frame. For a +SpecFrame, the default is wavelength (or equivalently, frequency) +since this is the system in which observations are usually made. The +SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which +allows the standard of rest of the alignment system to be specified. +Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale} +which allows the time scale of the alignment system to be specified. +Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since +this is a close approximation to an inertial frame of rest. + +\cleardoublepage +\section{\label{ss:framesets}Coordinate System Networks (FrameSets)} + +We saw in \secref{ss:introducingconversion} how \htmlref{astConvert}{astConvert} could be +used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems +represented by Frames. There is a limitation to this, however, in that +it can only be applied to coordinate systems that are inter-related by +suitable conventions. In the case of celestial coordinates, the +relevant conventions are standards set out by the International +Astronomical Union, and others, that define what these coordinate +systems mean. In practice, however, the relationships between many +other coordinate systems are also of practical importance. + +Consider, for example, the focal plane of a telescope upon which an +image of the sky is falling. We could measure positions in this focal +plane in millimetres or, if there were a detector system such as a CCD +present, we could count pixels. We could also use celestial +coordinates of many different kinds. All of these systems are +equivalent in their effectiveness at specifying positions in the focal +plane, but some are more convenient than others for particular +purposes. + +Although we could, in principle, convert between all of these focal +plane coordinate systems, there is no pre-defined convention for doing +so. This is because the conversions required depend on where the +telescope is pointing and how the CCD is mounted in the focal +plane. Clearly, knowledge about this cannot be built into the AST +library and must be supplied in some other way. Note that this is +exactly the same problem as we met in \secref{ss:framedomains} when +discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that +apply to different physical domains require that extra information be +supplied before we can convert between them. + +What we need, therefore, is a general way to describe how coordinate +systems are inter-related, so that when there is no convention already +in place, we can define our own. We can then look forward to +converting, say, from pixels into galactic coordinates and {\emph{vice +versa.} In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability. + +\subsection{The FrameSet Model} + +Consider a coordinate system (call it number 1) which is represented +by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to +the coordinates in system 1 yields coordinates in another system, +number 2. The Mapping therefore inter-relates coordinate systems 1 and +2. + +Now consider a second Mapping which inter-relates system 1 and a +further coordinate system, number 3. If we wanted to convert +coordinates between systems 2 and 3, we could do so by: + +\begin{enumerate} +\item Applying our first Mapping in reverse, so as to convert between +systems 2 and 1. + +\item Applying the second Mapping, as given, to convert between +systems 1 and 3. +\end{enumerate} + +We are not limited to three coordinate systems, of course. In fact, we +could continue to introduce any number of further coordinate systems, +so long as we have a suitable Mapping for each one which relates it to +one of the Frames already present. Continuing in this way, we can +build up a network in which Frames are inter-related by Mappings in +such a way that there is always a way of converting between any pair +of coordinate systems. + +The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas. It +is a network composed of Frames and associated Mappings, in which +there is always exactly one path, \emph{via} Mappings, between any +pair of Frames. Since we assemble FrameSets ourselves, they can be +used to represent any coordinate systems we choose and to set up the +particular relationships between them that we want. + +\subsection{\label{ss:creatingaframeset}Creating a FrameSet} + +Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to +put into it, so let's create a simple one: + +\small +\begin{terminalv} +#include "ast.h" +AstFrame *frame1; + +... + +frame1 = astFrame( 2, "Domain=A" ); +\end{terminalv} +\normalsize + +We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to +A so that it will be distinct from the others we will be using. We can +now create a new FrameSet containing just this Frame, as follows: + +\small +\begin{terminalv} +AstFrameSet *frameset; + +... + +frameset = astFrameSet( frame1, "" ); +\end{terminalv} +\normalsize + +So far, however, this Frame isn't related to any others. + +\subsection{\label{ss:addingframes}Adding New Frames to a FrameSet} + +We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above +(\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame} +and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that +are already present (there is only one present so far). To keep the +example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates +by 10. The required Objects are created as follows: + +\small +\begin{terminalv} +AstFrame *frame2; +AstMapping *mapping12; + +... + +frame2 = astFrame( 2, "Domain=B" ); +mapping12 = astZoomMap( 2, 10.0, "" ); +\end{terminalv} +\normalsize + +To add the new Frame into our FrameSet, we use the \htmlref{astAddFrame}{astAddFrame} +function: + +\small +\begin{terminalv} +astAddFrame( frameset, 1, mapping12, frame2 ); +\end{terminalv} +\normalsize + +Whenever a Frame is added to a FrameSet, it is assigned an integer +index. This index starts with 1 for the initial Frame used to create +the FrameSet (\secref{ss:creatingaframeset}) and increments by one +every time a new Frame is added. This index is the primary way of +identifying the Frames within a FrameSet. + +When a Frame is added, we also have to specify which of the existing +ones the new Frame is related to. Here, we chose number 1, the only +one present so far, and the new one we added became number 2. + +Note that a FrameSet does not make copies of the Frames and Mappings +that you insert into it. Instead, it holds pointers to them. This +means that if you retain the original pointers to these Objects and +alter them, you will indirectly be altering the FrameSet's +contents. You can, of course, always use \htmlref{astCopy}{astCopy} +(\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if +you need to ensure its independence. + +We could also add a third Frame into our FrameSet, this time defining +a coordinate system which is reached by multiplying the original +coordinates (of ``frame1'') by 5: + +\small +\begin{terminalv} +astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) ); +\end{terminalv} +\normalsize + +Here, we have avoided storing unnecessary pointer values by using +function invocations directly as arguments for astAddFrame. This +assumes that we are using \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} (\secref{ss:contexts}) to +ensure that Objects are correctly deleted when no longer required. + + Our example FrameSet now contains three Frames and two Mappings with + the arrangement shown in Figure~\ref{fig:fsexample}. + \begin{figure} + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/fsexample} + \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to + Frame~1 by multiplying its coordinates by factors of 10 and 5 + respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its + \htmlref{Current}{Current} attribute has the value 3. The transformation performed when + the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to + its current Frame) is shown in bold.} + \label{fig:fsexample} + \end{center} + \end{figure} + The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute. + +\subsection{\label{ss:baseandcurrent}The Base and Current Frames} + +At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its +\emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame +(Figure~\ref{fig:fsexample}). These Frames are identified by two +integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices +of the nominated Frames within the FrameSet. + +The existence of the base and current Frames reflects an important +application of FrameSets, which is to attach coordinate systems to +entities such as data arrays, data files, plotting surfaces (for +graphics), \emph{etc.} In this context, the base Frame represents the +``native'' coordinate system of the attached entity---for example, the +pixel coordinates of an image or the intrinsic coordinates of a +plotting surface. The other Frames within the FrameSet represent +alternative coordinate systems which may also be used to refer to +positions within that entity. The current Frame represents the +particular coordinate system which is currently selected for use. For +instance, if an image were being displayed, you would aim to label it +with coordinates corresponding to the current Frame. In order to see a +different coordinate system, a software user would arrange for a +different Frame to be made current. + +The choice of base and current Frames may be changed at any time, +simply by assigning new values to the FrameSet's Base and Current +attributes. For example, to make the Frame with index 3 become the +current Frame, you could use: + +\small +\begin{terminalv} +astSetI( frameset, "Current", 3 ); +\end{terminalv} +\normalsize + +You can nominate the same Frame to be both the base and current Frame +if you wish. +\label{ss:baseandcurrentdefault} + +By default (\emph{i.e.}\ if the Base or Current attribute is un-set), +the first Frame added to a FrameSet becomes its base Frame and the +last one added becomes its current Frame.\footnote{Although this is +reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a +new Frame is added to a FrameSet, the Current attribute is modified so +that the new Frame becomes the current one. This behaviour is +reflected in the state of the example FrameSet in +Figure~\ref{fig:fsexample}. + +\subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames} + +It is often necessary to refer to the base and current Frames +(\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be +cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current} +attributes on each occasion. To make this easier, two macros, +AST\_\_BASE and AST\_\_CURRENT, are defined in the ``ast.h'' header +file and may be used to represent the indices of the base and current +Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is +required. + +For example, when adding a new Frame to a FrameSet +(\secref{ss:addingframes}), you could use the following to indicate +that the new Frame is related to the existing current Frame, whatever +its index happens to be: + +\small +\begin{terminalv} +AstFrame *frame; +AstMapping *mapping; + +... + +astAddFrame( frameset, AST__CURRENT, mapping, frame ); +\end{terminalv} +\normalsize + +Of course, the Frame you added would then become the new current +Frame. + +\subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping} + +The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame} +class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class +(\secref{ss:mappings}). Its behaviour when used as a Mapping is +particularly important. + +Consider, for instance, passing a FrameSet pointer to a coordinate +transformation function such as \htmlref{astTran2}{astTran2}: + +\small +\begin{terminalv} +#define N 10 +double xin[ N ], yin[ N ], xout[ N ], yout[ N ]; + +... + +astTran2( frameset, N, xin, yin, 1, xout, yout ); +\end{terminalv} +\normalsize + +The coordinate transformation applied by this FrameSet would be the +one which converts between its base and current Frames. Using the +FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates +would be multiplied by a factor of 5. If we instead requested the +FrameSet's inverse transformation, we would be transforming from its +current Frame to its base Frame, so our example FrameSet would then +multiply by a factor of 0.2. + +Whenever the choice of base and current Frames changes, the +transformations which a FrameSet performs when used as a Mapping also +change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in +consequence, because they are determined by the numbers of axes in the +FrameSet's base and current Frames respectively. These numbers need +not necessarily be equal, of course. + +Like any Mapping, a FrameSet may also be inverted by changing the +boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{astInvert}{astInvert} +(\secref{ss:invertingmappings}). If this is happens, the values of the +FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with +its Nin and Nout attributes, so that its base and current Frames swap +places. When used as a Mapping, the FrameSet will therefore perform +the inverse transformation to that which it performed previously. + +To summarise, a FrameSet may be used exactly like any other Mapping +which inter-relates the coordinate systems described by its base and +current Frames. + +\subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet} + +Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is +required (\secref{ss:framesetasmapping}), a FrameSet necessarily +contains additional information and sometimes this might cause +inefficiency or confusion. For example, if you wanted to use a +Mapping contained in one FrameSet and insert it into another, it would +probably not be efficient to insert the whole of the first FrameSet +into the second one, although it would work. + +In such a situation, the \htmlref{astGetMapping}{astGetMapping} function allows you to extract +a Mapping from a FrameSet. You do this by specifying the two Frames +which the Mapping should inter-relate using their indices within the +FrameSet. For example: + +\small +\begin{terminalv} +map = astGetMapping( frameset, 2, 3 ); +\end{terminalv} +\normalsize + +would return a pointer to a Mapping that converted between Frames~2 +and 3 in the FrameSet. Its inverse transformation would then convert +in the opposite direction, \emph{i.e.}\ between Frames~3 and 2. Note +that this Mapping might not be independent of the Mappings contained +within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so +\htmlref{astCopy}{astCopy} should be used to make a copy if you need to guarantee +independence (\secref{ss:copyingobjects}). + +Very often, the Mapping returned by astGetMapping will be a compound +Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that +conversion between the two Frames may need to be done \emph{via} an +intermediate coordinate system so that several stages may be involved. +You can, however, easily simplify this Mapping (where this is possible) +by using the \htmlref{astSimplify}{astSimplify} function (\secref{ss:simplifyingcmpmaps}) and +this is recommended if you plan to use it for transforming a large +amount of data. + +\subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame} + +A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost +always behaves as if its current Frame had been used instead. For +example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using: + +\small +\begin{terminalv} +const char *title; + +... + +title = astGetC( frameset, "Title" ); +\end{terminalv} +\normalsize + +the result will be the Title of the current Frame, or a suitable +default if the current Frame's Title attribute is un-set. The same +also applies to other attribute operations---\emph{i.e.}\ setting, +clearing and testing attributes. Most attributes shared by both +Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)}, +\htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions: + +\begin{quote} +\begin{description} +\item[\htmlref{Class}{Class}]\mbox{}\\ +Has the value ``FrameSet''. + +\item[\htmlref{ID}{ID}]\mbox{}\\ +Identifies the particular FrameSet (not its current Frame). + +\item[\htmlref{Nin}{Nin}]\mbox{}\\ +Equals the number of axes in the FrameSet's base Frame. + +\item[\htmlref{Invert}{Invert}]\mbox{}\\ +Is independent of any of the Objects within the FrameSet. + +\item[\htmlref{Nobject}{Nobject}]\mbox{}\\ +Counts the number of active FrameSets. + +\item[\htmlref{RefCount}{RefCount}]\mbox{}\\ +Counts the number of active pointers to the FrameSet (not to its +current Frame). +\end{description} +\end{quote} + +Note that the set of attributes possessed by a FrameSet can vary, +depending on the nature of its current Frame. For example, if the +current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet +will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired, +\emph{etc.} However, if the current Frame is changed to be a basic +Frame, which does not have an Equinox attribute, then this attribute +will be absent from the FrameSet as well. Any attempt to reference it +will then result in an error. + +\subsection{Extracting a Frame from a FrameSet} + +Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most +situations, it is sometimes convenient to have direct access to a +specified Frame within it. This may be obtained using the \htmlref{astGetFrame}{astGetFrame} +function, as follows: + +\small +\begin{terminalv} +frame = astGetFrame( frameset, AST__BASE ); +\end{terminalv} +\normalsize + +This would return a pointer (not a copy) to the base Frame within the +FrameSet. Note the use of AST\_\_BASE +(\secref{ss:astbaseandastcurrent}) as shorthand for the value of the +FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index. + +\subsection{Removing a Frame from a FrameSet} + +Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed +using the \htmlref{astRemoveFrame}{astRemoveFrame} function. You identify the Frame you wish to +remove in the usual way, by giving its index within the FrameSet. For +example, the following would remove the Frame with index 1: + +\small +\begin{terminalv} +astRemoveFrame( frameset, 1 ); +\end{terminalv} +\normalsize + +The only restriction is that you cannot remove the last remaining +Frame because a FrameSet must always contain at least one Frame. When +a Frame is removed, the Frames which follow it are re-numbered +(\emph{i.e.}\ their indices are reduced by one) so as to preserve the +sequence of consecutive Frame indices. The FrameSet's \htmlref{Nframe}{Nframe} +attribute is also decremented. + +If appropriate, astRemoveFrame will modify the FrameSet's \htmlref{Base}{Base} and/or +\htmlref{Current}{Current} attributes so that they continue to identify the same Frames +as previously. If either the base or current Frame is removed, +however, the corresponding attribute will become un-set, so that it +reverts to its default value (\secref{ss:baseandcurrentdefault}) and +therefore identifies an alternative Frame. + +Note that it is quite permissible to remove any Frame from a FrameSet, +even although other Frames may appear to depend on it. For example, in +Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct +relationship between Frames~2 and 3 would still be preserved, although +they would be re-numbered as Frames~1 and 2. + +\cleardoublepage +\section{\label{ss:fshigher}Higher Level Operations on FrameSets} + +\subsection{\label{ss:framesetsfromconvert}Creating FrameSets with astConvert} + +Before considering the important subject of using FrameSets to convert +between coordinate systems (\secref{ss:framesetconverting}), let us +return briefly to reconsider the output generated by \htmlref{astConvert}{astConvert}. We +used this function earlier (\secref{ss:introducingconversion}), when +converting between the coordinate systems represented by various kinds +of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the +coordinate conversion it identifies. We are now in a position to +examine the structure of this FrameSet. + +Take our earlier example (\secref{ss:convertingskyframes}) of +converting between the celestial coordinate systems represented by two +SkyFrames: + +\small +\begin{terminalv} +#include "ast.h" +AstFrameSet *cvt; +AstSkyFrame *skyframe1, *skyframe2; + +... + +skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); +skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); + +cvt = astConvert( skyframe1, skyframe2, "" ); +\end{terminalv} +\normalsize + + This will produce a pointer, ``cvt'', to the FrameSet shown in + Figure~\ref{fig:fsconvert}. + \begin{figure}[bhtp] + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/fsconvert} + \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when astConvert is used to convert + between the coordinate systems represented by two SkyFrames. The + source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame + becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the + required conversion.} + \label{fig:fsconvert} + \end{center} + \end{figure} + +As can be seen, this FrameSet contains just two Frames. The source +Frame supplied to astConvert becomes its base Frame, while the +destination Frame becomes its current Frame. (The FrameSet, of course, +simply holds pointers to these Frames, rather than making copies.) The +Mapping which relates the base Frame to the current Frame is the one +which implements the required conversion. + +As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet +returned by astConvert may be used both as a Mapping and as a Frame to +perform most of the functions you are likely to need. However, the +Mapping may be extracted for use on its own if necessary, using +\htmlref{astGetMapping}{astGetMapping} (\secref{ss:extractingamapping}), for example: + +\small +\begin{terminalv} +AstMapping *mapping; + +... + +mapping = astGetMapping( cvt, AST__BASE, AST__CURRENT ); +\end{terminalv} +\normalsize + +\subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems} + + We now consider the process of converting between the coordinate + systems represented by two FrameSets. This is a most important + operation, as a subsequent example (\secref{ss:registeringimages}) + will show, and is illustrated in Figure~\ref{fig:fsalign}. + \begin{figure} + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/fsalign} + \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion + between two FrameSets is performed by establishing + a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion + between these two Frames is possible, then a route for converting + between the current Frames of both FrameSets can also be found. In + practice, there may be many ways of pairing Frames to find the + ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to + narrow the choice.} + \label{fig:fsalign} + \end{center} + \end{figure} + +Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave +like its current \htmlref{Frame}{Frame} when necessary, conversion between two +FrameSets is performed using \htmlref{astConvert}{astConvert} +(\secref{ss:convertingskyframes}), but supplying pointers to FrameSets +instead of Frames. The effect of this is to convert between the +coordinate systems represented by the current Frames of each FrameSet: + +\small +\begin{terminalv} +AstFrameSet *frameseta, *framesetb; + +... + +cvt = astConvert( frameseta, framesetb, "SKY" ); +\end{terminalv} +\normalsize + +When using FrameSets, we are presented with considerably more +conversion options than when using Frames alone. This is because each +current Frame is related to all the other Frames in its respective +FrameSet. Therefore, if we can establish a link between any pair of +Frames, one from each FrameSet, we can form a complete conversion path +between the two current Frames (Figure~\ref{fig:fsalign}). + +This expanded range of options is, of course, precisely the +intention. By connecting Frames together within a FrameSet, we have +extended the range of coordinate systems that can be reached from any +one of them. We are therefore no longer restricted to converting +between Frames with the same Domain value (\secref{ss:framedomains}), +but can go \emph{via} a range of intermediate coordinate systems in +order to make the connection we require. Transformation between +different domains has therefore become possible because, in assembling +the FrameSets, we provided the additional information needed to +inter-relate them. + +It is important to appreciate, however, that the choice of ``missing +link'' is crucial in determining the conversion that results. +Although each FrameSet may be perfectly self-consistent internally, +this does not mean that all conversion paths through the combined +network of Mappings are equivalent. Quite the contrary in fact: +everything depends on where the inter-connecting link between the two +FrameSets is made. In practice, there may be a large number of +possible pairings of Frames and hence of possible links. Other factors +must therefore be used to restrict the choice. These are: + +\begin{enumerate} +\item Not every possible pairing of Frames is legitimate. For example, +you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which +belong to different classes, so such pairings will be ignored. + +\item In a similar way, you cannot convert directly between Frames +with different Domain values (\secref{ss:framedomains}). If the Domain +attribute is used consistently (typically only one Frame in each +FrameSet will have a particular Domain value), then this further +restricts the choice. + +\item The third argument of astConvert may then be used to specify +explicitly which Domain value the paired Frames should have. You may +also supply a comma-separated list of preferences here (see below). + +\item If the above steps fail to uniquely identify the link, then the +first suitable pairing of Frames is used, so that any ambiguity is +resolved by the order in which Frames are considered for pairing (see +the description of the astConvert function in +\appref{ss:functiondescriptions} for details of the search +order).\footnote{If you find that how this ambiguity is resolved +actually makes a difference to the conversion that results, then you +have probably constructed a FrameSet which lacks internal +self-consistency. For example, you might have two Frames representing +indistinguishable coordinate systems but inter-related by a non-null +\htmlref{Mapping}{Mapping}.} +\end{enumerate} + +In the example above we supplied the string ``SKY'' as the third +argument of astConvert. This constitutes a request that a pair of +Frames with +the Domain value SKY (\emph{i.e.}\ representing celestial coordinate +systems) should be used to inter-relate the two FrameSets. Note that +this does not specify which celestial coordinate system to use, but is +a general request that the two FrameSets be inter-related using +coordinates on the celestial sphere. + +Of course, it may be that this request cannot be met because there may +not be a celestial coordinate system in both FrameSets. If this is +likely to happen, we can supply a list of preferences, or a +\emph{domain search path}, +as the third argument to astConvert, such as +the following: + +\small +\begin{terminalv} +cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID," ); +\end{terminalv} +\normalsize + +Now, if the two FrameSets cannot be inter-related using the SKY domain, +astConvert will attempt to use the PIXEL domain instead. If this +also fails, it will try the GRID domain. A blank field in the domain +search path (here indicated by the final comma) allows any Domain +value to be used. This can be employed as a last resort when all else +has failed. + +If astConvert succeeds in identifying a conversion, it will return a +pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the +source and destination Frames are inter-connected by the required +Mapping. In this case, of course, these Frames will be the current +Frames of the two FrameSets, but in all other respects the returned +FrameSet is the same as when converting between Frames. + +Very importantly, however, astConvert may modify the FrameSets you are +converting between. It does this, in order to indicate which pairing +of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base} +attribute for each FrameSet so that the Frame used in the pairing +becomes its base Frame (\secref{ss:baseandcurrent}). + +Finally, note that astConvert may also be used to convert between a +FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is +supplied for either the first or second argument, it will behave like +a FrameSet containing only a single Frame. + +\subsection{\label{ss:registeringimages}Example---Registering Two Images} + +Consider two images which have been calibrated by attaching FrameSets +to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the +raw data grid coordinates of each image (the GRID domain of +\secref{ss:domainconventions}). Suppose, also, that these FrameSets +contain an unknown number of other Frames, representing alternative +world coordinate systems. What we wish to do is register these two +images, such that we can transform from a position in the data grid of +one into the corresponding position in the data grid of the other. +This is a very practical example because images will typically be +calibrated using FrameSets in precisely this way. + +The first step will probably involve making a copy of both FrameSets +(using \htmlref{astCopy}{astCopy}---\secref{ss:copyingobjects}), since we will be +modifying them. Let ``frameseta'' and ``framesetb'' be pointers to +these copies. Since we want to convert between the base Frames of +these FrameSets (\emph{i.e.}\ their data grid coordinates), the next +step is to make these Frames current. This is simply done by inverting +both FrameSets, which interchanges their base and current +Frames. \htmlref{astInvert}{astInvert} will perform this task: + +\small +\begin{terminalv} +astInvert( frameseta ); +astInvert( framesetb ); +\end{terminalv} +\normalsize + +To identify the required conversion, we now use \htmlref{astConvert}{astConvert}, supplying +a suitable domain search path with which we would like our two images +to be registered: + +\small +\begin{terminalv} +cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID" ); +if ( cvt == AST__NULL ) { + <no conversion was possible> +} else { + <conversion was possible> +} +\end{terminalv} +\normalsize + +The effects of this are: + +\begin{enumerate} +\item astConvert first attempts to register the two images on the +celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it +searches for a celestial coordinate system, although not necessarily +the same one, attached to each image. If it finds a suitable pair of +coordinate systems, it then registers the images by matching +corresponding positions on the sky. + +\item If this fails, astConvert next tries to match positions in the +PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two +images will then be registered so that their corresponding pixel +positions correspond. If the PIXEL domain is offset from the data grid +(as typically happens in data reduction systems which implement a +``pixel origin''), then this will be correctly accounted for. + +\item If this also fails, the GRID domain is finally used. This will +result in image registration by matching corresponding points in the +data grids used by both images. This means they will be +aligned so that the first element their data arrays correspond. + +\item If all of the above fail, astConvert will return the value +AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned. +\end{enumerate} + +The resulting ``cvt'' FrameSet may then be used directly +(\secref{ss:convertingskyframes}) to convert between positions in the +data grid of the first image and corresponding positions in the data +grid of the second image. + +To determine which domain was used to achieve registration, +we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by +astConvert to indicate which intermediate Frames were used. We +can therefore simply invert either FrameSet (to make its base Frame +become the current one) and then enquire the \htmlref{Domain}{Domain} value: + +\small +\begin{terminalv} +const char *domain; + +... + +astInvert( frameseta ); +domain = astGetC( frameseta, "Domain" ); +\end{terminalv} +\normalsize + +If conversion was successful, the result will be one of the strings +``SKY'', ``PIXEL'' or ``GRID''. + +\subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System} + +As discussed earlier (\secref{ss:baseandcurrent}), an important +application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to +be attached to entities such as images in order to calibrate them. In +addition, one of the main objectives of AST is to simplify the +propagation of such information through successive stages of data +processing, so that it remains consistent with the associated image +data. + +In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with +the image's data grid coordinates and its other Frames (if any) with +the various alternative world coordinate systems associated with the +image. If the data processing being performed does not change the +relationship between the image's data grid coordinates and any of the +associated world coordinate systems, then propagation of the WCS +information is straightforward and simply involves copying the +FrameSet associated with the image. + +If any of these relationships change, however, then corresponding +changes must be made to the way Frames within the FrameSet are +inter-related. By far the most common case occurs when the image +undergoes some geometrical transformation resulting in ``re-gridding'' +on to another data grid, but the same principles can be applied to any +re-definition of a coordinate system. + +To pursue the re-gridding example, we would need to modify our +FrameSet to account for the fact that the image's data grid coordinate +system (corresponding to the FrameSet's base Frame) has +changed. Looking at the steps needed in detail, we might proceed as +follows: + +\begin{enumerate} +\item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the +original data grid coordinate system and the new one. + +\item Obtain a Frame to represent the new data grid coordinate system +(we could re-use the original base Frame here, using \htmlref{astGetFrame}{astGetFrame} to +obtain a pointer to it). + +\item Add the new Frame to the FrameSet, related to the original base +Frame by the new Mapping. This Frame now represents the new data grid +coordinate system and is correctly related to all the other Frames +present.\footnote{This is because any transformation to or from this +new Frame must go \emph{via} the base Frame representing the original +data grid coordinate system, which we assume was correctly related to +all the other Frames present.} + +\item Remove the original base Frame (representing the old data grid +coordinate system). + +\item Make the new Frame the base Frame and restore the original +current Frame. +\end{enumerate} + + The effect of these steps is to change the relationship between the + base Frame and all the other Frames present. It is as if a new Mapping + has been interposed between the Frame we want to alter and all the + other Frames within the FrameSet (Figure~\ref{fig:fsremap}). + \begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/fsremap} +\caption[Interposing a Mapping into a FrameSet]{The effect + of \htmlref{astRemapFrame}{astRemapFrame} is to interpose a Mapping between + a nominated Frame within a FrameSet and the remaining contents of the + FrameSet. This effectively ``re-defines'' the coordinate system + represented by the affected Frame. It may be used to compensate (say) + for geometrical changes made to an associated image. The + inter-relationships between all the other Frames within the FrameSet + remain unchanged.} + \label{fig:fsremap} + \end{center} + \end{figure} + +Performing the steps above is rather lengthy, however, so the +astRemapFrame function is provided to perform all of these operations +in one go. A practical example of its use is given below +(\secref{ss:wcsprocessingexample}). + +\subsection{\label{ss:wcsprocessingexample}Example---Binning an Image} + +As an example of using \htmlref{astRemapFrame}{astRemapFrame}, consider a case where the pixels +of a 2-dimensional image have been binned 2$\times$2, so as to reduce +the image size by a factor of two in each dimension. We must now +modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the +image. Much the same process would be needed for any other geometrical +change the image might undergo. + +We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the +data grid coordinates in the original image to those in the new one: + +\small +\begin{terminalv} +AstWinMap *winmap; +double ina[ 2 ] = { 0.5, 0.5 }; +double inb[ 2 ] = { 2.5, 2.5 }; +double outa[ 2 ] = { 0.5, 0.5 }; +double outb[ 2 ] = { 1.5, 1.5 }; + +... + +winmap = astWinMap( 2, ina, inb, outa, outb, "" ); +\end{terminalv} +\normalsize + +Here, we have simply set up arrays containing the data grid +coordinates of the bottom left and top right corners of the first +element in the output image (``outa'' and ``outb'') and the +corresponding coordinates in the input image (``ina'' and +``inb''). \htmlref{astWinMap}{astWinMap} then creates a WinMap which performs the required +transformation. We do not need to know the size of the image. + +We can then pass this WinMap to astRemapFrame. This modifies the +relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in +the FrameSet, so that the base Frame represents the data grid +coordinate system of the new image rather than the old one: + +\small +\begin{terminalv} +AstFrameSet *frameset; + +... + +astRemapFrame( frameset, AST__BASE, winmap ); +\end{terminalv} +\normalsize + +Any other coordinate systems described by the FrameSet, no matter how +many of these there might be, are now correctly associated with the +new image. + +\subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets} + +When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into +which you can place any combination of Frames and Mappings that you +wish. There are relatively few constraints on this process and no +checks are performed to see whether the FrameSet you construct makes +physical sense. It is quite possible, for example, to construct a +FrameSet containing two identical SkyFrames which are inter-related by +a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes +no sense, because applying a non-unit Mapping to any set of celestial +coordinates cannot yield positions that are still in the original +coordinate system. If you use such a FrameSet to perform coordinate +conversions, you are likely to get unpredictable results because the +information in the FrameSet is corrupt. + +It is, of course, your responsibility as a programmer to ensure the +validity of any information which you insert into a +FrameSet. Normally, this is straightforward and simply consists of +formulating your problem correctly (a diagram can often help to +clarify how coordinate systems are inter-related) and writing the +appropriate bug-free code to construct the FrameSet. However, once you +start to modify an existing FrameSet, there are new opportunities for +corrupting it! + +Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a +\htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute +simply by using \htmlref{astSet}{astSet} on the FrameSet, as follows: + +\small +\begin{terminalv} +astSet( frameset, "Equinox=J2010" ); +\end{terminalv} +\normalsize + +The effect of this will be to change the celestial coordinate system +which the current Frame represents. You can see, however, that this +has the potential to make the FrameSet corrupt unless corresponding +changes are also made to the Mapping which relates this SkyFrame to +the other Frames within the FrameSet. In fact, it is a general rule +that any change to a FrameSet which affects its current Frame can +potentially require corresponding changes to the FrameSet's Mappings +in order to maintain its overall integrity. + +Fortunately, once you have stored valid information in a FrameSet, AST +will look after these details for you automatically, so that the +FrameSet's integrity is maintained. In the example above, it would do +this by appropriately re-mapping the current Frame (as if +\htmlref{astRemapFrame}{astRemapFrame} had been used---\secref{ss:remapframe}) in response to +the use of astSet. One way of illustrating this process is as follows: + +\small +\begin{terminalv} +AstSkyFrame *skyframe; + +... + +skyframe = astSkyFrame( "" ); +frameSet = astFrameSet( skyframe ); +astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe ); +\end{terminalv} +\normalsize + +This constructs a trivial FrameSet whose base and current Frames are +both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this +as a ``pipe'' connecting two coordinate systems. At present, these two +systems represent identical ICRS coordinates, so the FrameSet +implements a unit Mapping. We can change the coordinate system on the +current end of this pipe as follows: + +\small +\begin{terminalv} +astSet( frameset, "System=Ecliptic, Equinox=J2010" ); +\end{terminalv} +\normalsize + +and the Mapping which the FrameSet implements would change +accordingly. To change the coordinate system on the base end of the +pipe, we might use: + +\small +\begin{terminalv} +astInvert( frameset ); +astSet( frameset, "System=Galactic" ); +astInvert( frameset ); +\end{terminalv} +\normalsize + +The FrameSet would then convert between galactic and ecliptic +coordinates. + +Note that astSet is not the only function which has this effect: +\htmlref{astClear}{astClear} behaves similarly, as also does \htmlref{astPermAxes}{astPermAxes} +(\secref{ss:permutingaxes}). If you need to circumvent this mechanism +for any reason, this can be done by going behind the scenes and +obtaining a pointer directly to the Frame you wish to modify. Consider +the following, for example: + +\small +\begin{terminalv} +skyframe = astGetFrame( frameset, AST__CURRENT ); +astSet( skyframe, "Equinox=J2010" ); +skyframe = astAnnul( skyframe ); +\end{terminalv} +\normalsize + +Here, astSet is applied to the SkyFrame pointer rather than the +FrameSet pointer, so the usual checks on FrameSet integrity do not +occur. The SkyFrame's Equinox attribute will therefore be modified +without any corresponding change to the FrameSet's Mappings. In this +case you must take responsibility yourself for maintaining the +FrameSet's integrity, perhaps through appropriate use of +astRemapFrame. + +\subsection{Merging FrameSets} + + As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet} + (\secref{ss:addingframes}), it is also possible to add complete sets of + inter-related Frames which are contained within another + FrameSet. This, of course, corresponds to the process of merging two + FrameSets (Figure~\ref{fig:fsmerge}). + \begin{figure}[hbtp] + \begin{center} + \includegraphics[width=0.7\textwidth]{sun211_figures/fsmerge} + \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using + \htmlref{astAddFrame}{astAddFrame}. FrameSet~B is being added to FrameSet~A by supplying a + new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1) + and the current Frame of B. In the merged FrameSet, the Frames + contributed by B will be re-numbered to become Frames~4, 5 and 6. The + base Frame will remain unchanged, but the current Frame of B becomes + the new current Frame. Note that FrameSet~B itself is not + altered by this process.} + \label{fig:fsmerge} + \end{center} + \end{figure} + + + +This process is performed by adding one FrameSet to another using +astAddFrame, in much the same manner as when adding a new Frame to an +existing FrameSet (\secref{ss:addingframes}). It is simply a matter of +providing a FrameSet pointer, instead of a Frame pointer, for the 4th +argument. In performing the merger you must, as usual, supply a +Mapping, but in this case the Mapping should relate the current Frame +of the FrameSet being added to one of the Frames already present. For +example, you might perform the merger shown in +Figure~\ref{fig:fsmerge} as follows: + +\small +\begin{terminalv} +AstMapping *mapping; + +... + +astAddFrame( frameseta, 1, mapping, framesetb ); +\end{terminalv} +\normalsize + +The Frames acquired by ``frameseta'' from the FrameSet being added +(``framesetb'') are re-numbered so that they retain their original +order and follow on consecutively after the Frames that were already +present, whose indices remain unchanged. The base Frame of +``frameseta'' remains unchanged, but the current Frame of +``framesetb'' becomes its new current Frame. All the +inter-relationships between Frames in both FrameSets remain in place +and are preserved in the merged FrameSet. + +Note that while this process modifies the first FrameSet +(``frameseta''), it leaves the original contents of the one being +added (``framesetb'') unchanged. + +%\cleardoublepage +%\section{\label{ss:searching}TBW - Searching for Coordinate Systems} + +\cleardoublepage +\section{\label{ss:channels}Saving and Restoring Objects (Channels)} + +Facilities are provided by the AST library for performing input and +output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible +to write any Object into various external representations for +storage, and then to read these representations back in, so as to +restore the original Object. Typically, an Object would be written by +one program and read back in by another. + +We refer to ``external representations'' in the plural because AST is +designed to function independently of any particular data storage +system. This means that Objects may need converting into a number of +different external representations in order to be compatible with +(say) the astronomical data storage system in which they will reside. + +In this section, we discuss the basic I/O facilities which support +external representations based on a textual format referred to as the AST +``native format''. These are implemented using a new kind of Object---a +\htmlref{Channel}{Channel}. We will examine later how to use other representations, based on +an XML format or on the use of FITS headers, for storing Objects. These +are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan} +(\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}). + +\subsection{The Channel Model} + +The best way to start thinking about a \htmlref{Channel}{Channel} is like a C file +stream, and to think of the process of creating a Channel as that +of opening a file and obtaining a FILE pointer. Subsequently, you can +read and write Objects \emph{via} the Channel. + +This analogy is not quite perfect, however, because a Channel has, in +principle, two ``files'' attached to it. One is used when reading, and +the other when writing. These are termed the Channel's \emph{source} +and \emph{sink} respectively. In practice, the source and sink may +both be the same, in which case the analogy with the C file stream is +correct, but this need not always be so. It is not necessarily so with +the basic Channel, as we will now see (\secref{ss:creatingachannel}). + +\subsection{\label{ss:creatingachannel}Creating a Channel} + +The process of creating a \htmlref{Channel}{Channel} is straightforward. As you +might expect, it uses the constructor function \htmlref{astChannel}{astChannel}: + +\small +\begin{terminalv} +#include "ast.h" +AstChannel *channel; + +... + +channel = astChannel( NULL, NULL, "" ); +\end{terminalv} +\normalsize + +The first two arguments to astChannel specify the external source and +sink that the Channel is to use. There arguments are pointers to C +functions and we will examine their use in more detail later +(\secref{ss:channelsource} and \secref{ss:channelsink}). + +In this very simple example we have supplied NULL pointers for both +the source and sink functions. This requests the default behaviour, +which means that textual input will be read from the program's +standard input stream (typically, this means your keyboard) while +textual output will go to the standard output stream (typically +appearing on your screen). On UNIX systems, of course, either of these +streams can easily be redirected to files. This default behaviour can be +changed by assigning values to the Channel's \htmlref{SinkFile}{SinkFile} and/or \htmlref{SourceFile}{SourceFile} +attributes. These attributes specify the paths to text files that are to +be used in place of the standard input and output streams. + +\subsection{\label{ss:writingtoachannel}Writing Objects to a Channel} + +The process of saving Objects is very straightforward. You can +simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{astWrite}{astWrite} +function, as follows: + +\small +\begin{terminalv} +int nobj; +AstObject *object; + +... + +nobj = astWrite( channel, object ); +\end{terminalv} +\normalsize + +The effect of this will be to produce a textual description of the +Object which will appear, by default, on your program's standard +output stream. Any class of Object may be converted into text in this +way. + +astWrite returns a count of the number of Objects written. Usually, +this will be one, unless the Object supplied cannot be +represented. With a basic Channel all Objects can be represented, so a +value of one will always be returned unless there has been an +error. We will see later, however, that more specialised forms of +Channel may impose restrictions on the kind of Object you can write +(\secref{ss:foreignfitslimitations}). In such cases, astWrite may +return zero to indicate that the Object was not acceptable. + +\subsection{\label{ss:readingfromachannel}Reading Objects from a Channel} + +Before discussing the format of the output produced above +(\secref{ss:writingtoachannel}), let us consider how to read it back, +so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first +need to save the output in a file. We can do that either by using the +\htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output +to a file using a shell command like: + +\small +\begin{terminalv} +program1 >file +\end{terminalv} +\normalsize + +Within a subsequent program, we can read this Object back in by +using the \htmlref{astRead}{astRead} function, having first created a suitable +\htmlref{Channel}{Channel}: + +\small +\begin{terminalv} +object = astRead( channel ); +\end{terminalv} +\normalsize + +By default, this function will read from the standard input stream +(the default source for a basic Channel), so we would need to ensure +that our second program reads its input from the file in which the +Object description is stored. On UNIX systems, we could again use a +shell redirection command such as: + +\small +\begin{terminalv} +program2 <file +\end{terminalv} +\normalsize + +Alternatively, we could have assigned a value to the SinkFile attribute +before invoking +astRead. + +\subsection{Saving and Restoring Multiple Objects} + +I/O operations performed on a basic \htmlref{Channel}{Channel} are sequential. This +means that if you write more than one \htmlref{Object}{Object} to a Channel, +each new Object's textual description is simply appended to the +previous one. You can store any number of Objects in this way, +subject only to the storage space you have available. + +After you read an Object back from a basic Channel, the +Channel is ``positioned'' at the end of that Object's +textual description. If you then perform another read, you will +read the next Object's textual description and therefore +retrieve the next Object. This process may be repeated to read +each Object in turn. When there are no more Objects to be +read, \htmlref{astRead}{astRead} will return the value AST\_\_NULL to indicate an +\emph{end-of-file}. + +\subsection{\label{ss:validatinginput}Validating Input} + +The pointer returned by \htmlref{astRead}{astRead} (\secref{ss:readingfromachannel}) could +identify any class of \htmlref{Object}{Object}---this is determined entirely by the +external data being read. If it is necessary to test for a particular +class (say a \htmlref{Frame}{Frame}), this may be done as follows using the appropriate +member of the \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$} family of functions: + +\small +\begin{terminalv} +int ok; + +... + +ok = astIsAFrame( object ); +\end{terminalv} +\normalsize + +Note, however, that this will accept any Frame, so would be equally +happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}. An alternative validation +strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute +and then test this character string, as follows: + +\small +\begin{terminalv} +#include <string.h> + +... + +ok = !strcmp( astGetC( object, "Class" ), "Frame" ); +\end{terminalv} +\normalsize + +This would only accept a basic Frame and would reject a SkyFrame. + +\subsection{Storing an ID String with an Object} + +Occasionally, you may want to store a number of Objects and later +retrieve them and use each for a different purpose. If the Objects are +of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish +them when you read them back +(\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the +order in which they are stored is a possible solution, this becomes +complicated if some of the Objects are optional and may not always be +present. It also makes extending your data format in future more +difficult. + +To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident} +attribute, both of which allows you, in effect, to attach a textual +identification label to it. You simply set the ID or Ident attribute before +writing the Object: + +\small +\begin{terminalv} +astSet( object, "ID=Calibration" ); +nobj = astWrite( channel, object ); +\end{terminalv} +\normalsize + +You can then test its value after you read the Object back: + +\small +\begin{terminalv} +object = astRead( channel ); +if ( !strcmp( astGetC( object, "ID" ), "Calibration" ) ) { + <the Calibration Object has been read> +} else { + <some other Object has been read> +} +\end{terminalv} +\normalsize + +The only difference between the ID and Ident attributes is that the ID +attribute is unique to a particular Object and is lost if, for example, +you make a copy of the Object. The Ident attrubute, on the other hand, is +transferred to the new Object when a copy is made. Consequently, it is +safest to set the value of the ID attribute immediately before you +perform the write. + +\subsection{\label{ss:textualoutputformat}The Textual Output Format} + +Let us now examine the format of the textual output produced by +writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel} +(\secref{ss:writingtoachannel}). To give a concrete example, suppose +the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows: + +\small +\begin{terminalv} +AstSkyFrame *skyframe; + +... + +nobj = astWrite( channel, skyframe ); +\end{terminalv} +\normalsize + +The output should then look like the following: + +\small +\begin{terminalv} + Begin SkyFrame # Description of celestial coordinate system +# Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system + Naxes = 2 # Number of coordinate axes +# Domain = "SKY" # Coordinate system domain +# Lbl1 = "Right Ascension" # Label for axis 1 +# Lbl2 = "Declination" # Label for axis 2 +# Uni1 = "hh:mm:ss.s" # Units for axis 1 +# Uni2 = "ddd:mm:ss" # Units for axis 2 +# Dir1 = 0 # Plot axis 1 in reverse direction (hint) + Ax1 = # Axis number 1 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + Ax2 = # Axis number 2 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + IsA Frame # Coordinate system description + System = "FK4-NO-E" # Celestial coordinate system type + Epoch = 1958 # Besselian epoch of observation +# Eqnox = 1950 # Besselian epoch of mean equinox + End SkyFrame +\end{terminalv} +\normalsize + +You will notice that this output is designed both for a human reader, +in that it is formatted, and also to be read back by a computer in +order to reconstruct the SkyFrame. In fact, this is precisely the way +that \htmlref{astShow}{astShow} works (\secref{ss:displayingobjects}), this function being +roughly equivalent to the following use of a Channel: + +\small +\begin{terminalv} +channel = astChannel( NULL, NULL, "" ); +(void) astWrite( channel, object ); +channel = astAnnul( channel ); +\end{terminalv} +\normalsize + +Some lines of the output start with a ``\verb?#?'' comment character, +which turns the rest of the line into a comment. These lines will be +ignored when read back in by \htmlref{astRead}{astRead}. They typically contain default +values, or values that can be derived in some way from the other data +present, so that they do not actually need to be stored in order to +reconstruct the original Object. They are provided purely for human +information. The same comment character is also used to append +explanatory comments to most output lines. + +It is not sensible to attempt a complete description of this output +format because every class of Object is potentially different and each +can define how its own data should be represented. However, there are +some basic rules, which mean that the following common features will +usually be present: + +\begin{enumerate} +\item Each Object is delimited by matching ``Begin'' and ``End'' +lines, which also identify the class of Object involved. + +\item Within each Object description, data values are represented +by a simple ``keyword~$=$~value'' syntax, with one value to a line. + +\item Lines beginning ``IsA'' are used to mark the divisions between +data belonging to different levels in the class hierarchy +(\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data +associated with the Frame class and the start of data associated with +some derived class (a SkyFrame in the above example). ``IsA'' lines +may be omitted if associated data values are absent and no confusion +arises. + +\item Objects may contain other Objects as data. This is +indicated by an absent value, with the description of the data +Object following on subsequent lines. + +\item Indentation is used to clarify the overall structure. +\end{enumerate} + +Beyond these general principles, the best guide to what a particular +line of output represents will generally be the comment which +accompanies it together with a general knowledge of the class of +Object being described. + +\subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output} + +It is not always necessary for the output from \htmlref{astWrite}{astWrite} +(\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has +attributes that allow the amount of detail in the output to be +controlled. + +The first of these is the integer attribute \htmlref{Full}{Full}, which controls the +extent to which optional, commented out, output lines are produced. By +default, Full is zero, and this results in the standard style of +output (\secref{ss:textualoutputformat}) where default values that may +be helpful to humans are included. To suppress these optional lines, +Full should be set to $-$1. This is most conveniently done when the +Channel is created, so that: + +\small +\begin{terminalv} +channel = astChannel( NULL, NULL, "Full=-1" ); +(void) astWrite( channel, skyframe ); +channel = astAnnul( channel ); +\end{terminalv} +\normalsize + +would result in output containing only the essential information, such +as: + +\small +\begin{terminalv} + Begin SkyFrame # Description of celestial coordinate system + Naxes = 2 # Number of coordinate axes + Ax1 = # Axis number 1 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + Ax2 = # Axis number 2 + Begin SkyAxis # Celestial coordinate axis + End SkyAxis + IsA Frame # Coordinate system description + System = "FK4-NO-E" # Celestial coordinate system type + Epoch = 1958 # Besselian epoch of observation + End SkyFrame +\end{terminalv} +\normalsize + +In contrast, setting Full to $+$1 will result in additional output +lines which will reveal every last detail of the \htmlref{Object}{Object}'s +construction. Often this will be rather more than you want, especially +for more complex Objects, but it can sometimes help when debugging +programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail: + +\small +\begin{terminalv} + Begin SkyFrame # Description of celestial coordinate system +# RefCnt = 1 # Count of active Object pointers +# Nobj = 1 # Count of active Objects in same class + IsA Object # Astrometry Object +# Nin = 2 # Number of input coordinates +# Nout = 2 # Number of output coordinates +# Invert = 0 # Mapping not inverted +# Fwd = 1 # Forward transformation defined +# Inv = 1 # Inverse transformation defined +# Report = 0 # Don't report coordinate transformations + IsA Mapping # Mapping between coordinate systems +# Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system + Naxes = 2 # Number of coordinate axes +# Domain = "SKY" # Coordinate system domain +# Lbl1 = "Right Ascension" # Label for axis 1 +# Lbl2 = "Declination" # Label for axis 2 +# Sym1 = "RA" # Symbol for axis 1 +# Sym2 = "Dec" # Symbol for axis 2 +# Uni1 = "hh:mm:ss.s" # Units for axis 1 +# Uni2 = "ddd:mm:ss" # Units for axis 2 +# Dig1 = 7 # Individual precision for axis 1 +# Dig2 = 7 # Individual precision for axis 2 +# Digits = 7 # Default formatting precision +# Fmt1 = "hms.1" # Format specifier for axis 1 +# Fmt2 = "dms" # Format specifier for axis 2 +# Dir1 = 0 # Plot axis 1 in reverse direction (hint) +# Dir2 = 1 # Plot axis 2 in conventional direction (hint) +# Presrv = 0 # Don't preserve target axes +# Permut = 1 # Axes may be permuted to match +# MinAx = 2 # Minimum number of axes to match +# MaxAx = 2 # Maximum number of axes to match +# MchEnd = 0 # Match initial target axes +# Prm1 = 1 # Axis 1 not permuted +# Prm2 = 2 # Axis 2 not permuted + Ax1 = # Axis number 1 + Begin SkyAxis # Celestial coordinate axis +# RefCnt = 1 # Count of active Object pointers +# Nobj = 2 # Count of active Objects in same class + IsA Object # Astrometry Object +# Label = "Angle on Sky" # Axis Label +# Symbol = "delta" # Axis symbol +# Unit = "ddd:mm:ss" # Axis units +# Digits = 7 # Default formatting precision +# Format = "dms" # Format specifier +# Dirn = 1 # Plot in conventional direction + IsA Axis # Coordinate axis +# Format = "dms" # Format specifier +# IsLat = 0 # Longitude axis (not latitude) +# AsTime = 0 # Display values as angles (not times) + End SkyAxis + Ax2 = # Axis number 2 + Begin SkyAxis # Celestial coordinate axis +# RefCnt = 1 # Count of active Object pointers +# Nobj = 2 # Count of active Objects in same class + IsA Object # Astrometry Object +# Label = "Angle on Sky" # Axis Label +# Symbol = "delta" # Axis symbol +# Unit = "ddd:mm:ss" # Axis units +# Digits = 7 # Default formatting precision +# Format = "dms" # Format specifier +# Dirn = 1 # Plot in conventional direction + IsA Axis # Coordinate axis +# Format = "dms" # Format specifier +# IsLat = 0 # Longitude axis (not latitude) +# AsTime = 0 # Display values as angles (not times) + End SkyAxis + IsA Frame # Coordinate system description + System = "FK4-NO-E" # Celestial coordinate system type + Epoch = 1958 # Besselian epoch of observation +# Eqnox = 1950 # Besselian epoch of mean equinox + End SkyFrame +\end{terminalv} +\normalsize + +\subsection{\label{ss:channelcommenting}Controlling Commenting} + +Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the +boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments +are appended to describe the purpose of each value. Comment has the +value 1 by default but, if set to zero, will suppress these +comments. This is normally appropriate only if you wish to minimise +the amount of output, for example: + +\small +\begin{terminalv} +astSet( channel, "Full=-1, Comment=0" ); +nobj = astWrite( channel, skyframe ); +\end{terminalv} +\normalsize + +might result in the following more compact output: + +\small +\begin{terminalv} + Begin SkyFrame + Naxes = 2 + Ax1 = + Begin SkyAxis + End SkyAxis + Ax2 = + Begin SkyAxis + End SkyAxis + IsA Frame + System = "FK4-NO-E" + Epoch = 1958 + End SkyFrame +\end{terminalv} +\normalsize + +\subsection{Editing Textual Output} + +The safest advice about editing the textual output from \htmlref{astWrite}{astWrite} (or +\htmlref{astShow}{astShow}) is ``don't!''---unless you know what you are doing. + +Having given that warning, however, it is sometimes possible to make +changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from +scratch, and to read the results back in to construct new +Objects. Normally, simple changes to numerical values are safest, but +be aware that this is a back door method of creating Objects, so +you are on your own! There are a number of potential pitfalls. In +particular: + +\begin{itemize} +\item \htmlref{astRead}{astRead} is intended for retrieving data written by astWrite and +not for reading data input by humans. As such, the data validation +provided is very limited and is certainly not foolproof. This makes it +quite easy to construct Objects that are internally inconsistent by +this means. In contrast, the normal programming interface incorporates +numerous checks designed to make it impossible to construct invalid +Objects. You should not necessarily think you have found a bug if your +changes to an Object's textual description fail to produce the results +you expected! + +\item In many instances the names associated with values in textual +output will correspond with Object attributes. Sometimes, however, +these names may differ from the attribute name. This is mainly because +of length restrictions imposed by other common external formats, such +as FITS headers. Some of the names used do not correspond with +attributes at all. + +\item It is safest to change single numerical or string values. +Beware of changing the size or shape of Objects (\emph{e.g.}\ the +number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others +stored elsewhere within the Object and changing them in a haphazard +fashion will not produce useful results. + +\item Be wary about un-commenting default values. Sometimes this will +work, but often these values are derived from other Objects stored +more deeply in the structure and the proper place to insert a new +value is not where the default itself appears. +\end{itemize} + +\subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text} + +By default, when you use \htmlref{astRead}{astRead} to read from a basic \htmlref{Channel}{Channel} +(\secref{ss:readingfromachannel}), it is assumed that you are reading a +stream of text containing only AST Objects, which follow each other +end-to-end. If any extraneous input data are encountered which do not +appear to form part of the textual description of an \htmlref{Object}{Object}, then an +error will result. In particular, the first input line must identify +the start of an Object description, so you cannot start reading half +way through an Object. + +Sometimes, however, you may want to store AST Object descriptions +intermixed with other textual data. You can do this by setting the +Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every +read to skip over extraneous data until the start of a new AST Object +description, if any, is found. So long as your other data do not mimic +the appearance of an AST Object description, the two sets of data can +co-exist. + +For example, by setting Skip to 1, the following complete C program +will read all the AST Objects whose descriptions appear in the source +of this document, ignoring the other text. \htmlref{astShow}{astShow} is used to display +those found: + +\small +\begin{terminalv} +#include "ast.h" +main() { + AstChannel *channel; + AstObject *object; + + channel = astChannel( NULL, NULL, "Skip=1" ); + while ( ( object = astRead( channel ) ) != AST__NULL ) { + astShow( object ); + object = astAnnul( object ); + } + channel = astAnnul( channel ); +} +\end{terminalv} +\normalsize + +\subsection{\label{ss:channelsource}Reading Objects from Files} + +Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel} +in reading and writing Objects through a program's standard input and +output streams. We will now consider how to access Objects stored in +files more directly. + +The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of +the Channel. For instance, the following will read a pair of Objects from +a text file called ``fred.txt'': + +\small +\begin{terminalv} +astSet( channel, "SourceFile=fred.txt" ); +obj1 = astRead( channel ); +obj2 = astRead( channel ); +astClear( channel, "SourceFile" ); +\end{terminalv} +\normalsize + +Note, the act of clearing the attribute tells AST that no more Objects +are to be read from the file and so the file is then closed. If the +attribute is not cleared, the file will remain open and further Objects +can be read from it. The file will always be closed when the Channel is +deleted. + +This simple approach will normally be sufficient. However, because the +AST library is designed to be used from more than one language, it has +to be a little careful about reading and writing to files. This is due +to incompatibilities that may exist between the file I/O facilities +provided by different languages. If such incompatibilities prevent the +above simple system being used, we need to adopt a system that off-loads +all file I/O to external code. + +What this means in practice is that if the above simple approach cannot +be used, you must instead provide some simple C +functions that perform the actual transfer of data to and from files +and similar external data stores. The functions you provide are +supplied as the source and/or sink function arguments to \htmlref{astChannel}{astChannel} +when you create a Channel (\secref{ss:creatingachannel}). An example is +the best way to illustrate this. + +Consider the following simple function called Source. It reads a +single line of text from a C input stream and returns a pointer to it, +or NULL if there is no more input: + +\small +\begin{terminalv} +#include <stdio.h> +#define LEN 200 +static FILE *input_stream; + +const char *Source( void ) { + static char buffer[ LEN + 2 ]; + return fgets( buffer, LEN + 2, input_stream ); +} +\end{terminalv} +\normalsize + +Note that the input stream is a static variable which we will also +access from our main program. This might look something like this +(omitting error checking for brevity): + +\small +\begin{terminalv} +/* Open the input file. */ +input_stream = fopen( "infile.ast", "r" ); + +/* Create a Channel and read an Object from it. */ +channel = astChannel( Source, NULL, "" ); +object = astRead( channel ); + +... + +/* Annul the Channel and close the file when done. */ +channel = astAnnul( channel ); +(void) fclose( input_stream ); +\end{terminalv} +\normalsize + +Here, we first open the required input file, saving the resulting FILE +pointer. We then pass a pointer to our Source function as the first +argument to astChannel when creating a new Channel. When we read +an \htmlref{Object}{Object} from this Channel with \htmlref{astRead}{astRead}, the Source +function will be called to obtain the textual data from the file, the +end-of-file being detected when this function returns NULL. + +Note, if a value is set for the SourceFile attribute, +the astRead function will ignore any source function +specified when the Channel was created. + +\subsection{\label{ss:channelsink}Writing Objects to Files} + +As for reading, writing Objects to files can be done in two different ways. +Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}. +For instance, the following will write a pair of Objects to a text file +called ``fred.txt'': + +\small +\begin{terminalv} +astSet( channel, "SinkFile=fred.txt" ); +nobj = astWrite( channel, object1 ); +nobj = astWrite( channel, object2 ); +astClear( channel, "SinkFile" ); +\end{terminalv} +\normalsize + +Note, the act of clearing the attribute tells AST that no more output +will be written to the file and so the file is then closed. If the +attribute is not cleared, the file will remain open and further Objects +can be written to it. The file will always be closed when the Channel is +deleted. + +If the details of the language's I/O system on the computer you are using +means that the above approach cannot be used, then we can write a Sink function, +that writes a line of output text to a file, and use it in basically the same +way as the Source function in the previous section (\secref{ss:channelsource}): + +\small +\begin{terminalv} +static FILE *output_stream; + +void Sink( const char *line ) { + (void) fprintf( output_stream, "%s\n", line ); +} +\end{terminalv} +\normalsize + +Note that we must supply the final newline character ourselves. + +In this case, our main program would supply a pointer to this Sink +function as the second argument to \htmlref{astChannel}{astChannel}, as follows: + +\small +\begin{terminalv} +/* Open the output file. */ +output_stream = fopen( "outfile.ast", "w" ); + +/* Create a Channel and write an Object to it. */ +channel = astChannel( Source, Sink, "" ); +nobj = astWrite( channel, object ); + + ... + +/* Annul the Channel and close the file when done. */ +channel = astAnnul( channel ); +(void) fclose( output_stream ); +\end{terminalv} +\normalsize + +Note that we can specify a source and/or a sink function for the +Channel, and that these may use either the same file, or different +files according to whether we are reading or writing. AST has no +knowledge of the underlying file system, nor of file positioning. It +just reads and writes sequentially. If you wish, for example, to +reposition a file at the beginning in between reads and writes, then +this can be done directly (and completely independently of AST) using +standard C functions. + +If an error occurs in your source or sink function, you can +communicate this to the AST library by setting its error status to any +error value using \htmlref{astSetStatus}{astSetStatus} (\secref{ss:errordetection}). This will +immediately terminate the read or write operation. + +Note, if a value is set for the SinkFile attribute, +the \htmlref{astWrite}{astWrite} function will ignore any sink function +specified when the Channel was created. + +\subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places} + +It should be obvious from the above (\secref{ss:channelsource} and +\secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink functions +provide a flexible means of intercepting textual data that describes +AST Objects as it flows in and out of your program. In fact, you might +like to regard a Channel simply as a filter for converting AST Objects +to and from a stream of text which is then handled by your source and +sink functions, where the real I/O occurs. + +This gives you the ability to store AST Objects in virtually any data +system, so long as you can convert a stream of text into something +that can be stored (it need no longer be text) and retrieve it +again. There is generally no need to retain comments. Other +possibilities, such as inter-process and network communication, could +also be implemented \emph{via} source and sink functions in basically +the same way. + +\cleardoublepage +\section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)} + +A FITS header is a sequence of 80-character strings, formatted +according to particular rules defined by the Flexible Image Transport +\htmlref{System}{System} +(FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/} +is a widely-used standard for data interchange in astronomy and has +also been adopted as a data processing format in some astronomical +data reduction systems. The individual 80-character strings in a FITS +header are usually called \emph{cards} or \emph{header cards} (for +entirely anachronistic reasons). + +A sequence of FITS cards appears as a header at the start of every +FITS data file, and sometimes also at other points within it, and is +used to provide ancillary information which qualifies or describes the +main array of data stored in the file. As such, FITS headers are prime +territory for storing information about the coordinate systems +associated with data held in FITS files. + +In this section, we will examine how to store information in FITS +headers directly in the form of AST Objects---a process which is +supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our +discussion here will turn out to be a transitional step that +emphasises the similarities between a FitsChan and a Channel +(\secref{ss:channels}). At the same time, it will prepare us for the +next section (\secref{ss:foreignfits}), where we will examine how to +use a FitsChan to tackle some of the more difficult problems that FITS +headers can present. + +\subsection{\label{ss:nativeencoding}The Native FITS Encoding} + +As it turns out, we are not the first to have thought of storing WCS +information in FITS headers. In fact, the original FITS standard (1981 +vintage) defined a set of header keywords for this purpose which have +been widely used, although they have proved too limited for many +practical purposes. + +At the time of writing, a number of different ways of using FITS +headers for storing WCS information are in use, most (although not +all) based on the original standard. We will refer to these +alternative ways of storing the information as FITS \emph{encodings} +but will defer a discussion of their advantages and limitations until +the next section (\secref{ss:foreignfits}). + +Here, we will examine how to store AST Objects directly in FITS +headers. In effect, this defines a new encoding, which we will term +the \emph{native encoding}. This is a special kind of encoding, +because not only does it allow us to associate conventional +WCS calibration information with FITS data, but it also allows any other +information that can be expressed in terms of AST Objects to be stored +as well. In fact, the native encoding provides us with facilities +roughly analogous to those of the \htmlref{Channel}{Channel} +(\secref{ss:channels})---\emph{i.e.}\ a lossless way of +transferring AST Objects from program to program---but based on FITS +headers instead of free-format text. + +\subsection{The FitsChan Model} + +I/O between AST Objects and FITS headers is supported by a specialised +form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which +may hold any number, including zero, of FITS header cards. This buffer +forms a workspace in which you can assemble FITS cards and manipulate +them before writing them out to a file. + +By default, when a FitsChan is first created, it contains no cards and +there are five ways of inserting cards into it: + +\begin{enumerate} +\item You may add cards yourself, one at a time, using \htmlref{astPutFits}{astPutFits} +(\secref{ss:addingfitscards}). + +\item You may add cards yourself, supplying all cards concatenated into a +single string, using \htmlref{astPutCards}{astPutCards} +(\secref{ss:addingmulticards}). + +\item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{astWrite}{astWrite}), +which will have the effect of creating new cards within the FitsChan +which describe the Object (\secref{ss:writingnativefits}). + +\item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan. +The value should be the path to a text file holding a set of FITS header +cards, one per line. When the SourceFile value is set (using +astSetC or \htmlref{astSet}{astSet}), +the file is opened and the headers copied from it into the FitsChan. +The file is then immediately closed. + +\item You may specify a source function which reads data from some +external store of FITS cards, just like the source associated with a +basic Channel (\secref{ss:channelsource}). If you supply a source +function, it will be called when the FitsChan is created in order to +fill it with an initial set of cards (\secref{ss:fitssourceandsink}). +\end{enumerate} + +There are also four ways of removing cards from a FitsChan: + +\begin{enumerate} +\item You may delete cards yourself, one at a time, using \htmlref{astDelFits}{astDelFits} +(\secref{ss:findingandchangingfits}). + +\item You may read an AST Object from the FitsChan (using \htmlref{astRead}{astRead}), +which will have the effect of removing those cards from the FitsChan +which describe the Object (\secref{ss:readingnativefits}). + +\item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When +the FitsChan is deleted, any remaining headers are written out to a text +file with path equal to the value of the SinkFile attribute. + +\item Alternatively, you may specify a sink function which writes data to some +external store of FITS cards, just like the sink associated with a +basic Channel (\secref{ss:channelsink}). If you supply a sink function, +it will be called when the FitsChan is deleted in order to write out +any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note, +the sink function is not called if the SinkFile attribute has been set. +\end{enumerate} + +Note, in particular, that reading an AST Object from a FitsChan is +\emph{destructive}. That is, it deletes the FITS cards that describe the +Object. The reason for this is explained in +\secref{ss:destructiveread}. + +In addition to the above, you may also read individual cards from a +FitsChan using the function \htmlref{astFindFits}{astFindFits} (which is not +destructive). This is the main means of writing out FITS cards if you +have not supplied a sink function. astFindFits also provides a means +of searching for particular FITS cards (by keyword, for example) and +there are other facilities for overwriting cards when required +(\secref{ss:findingandchangingfits}). + +\subsection{\label{ss:creatingafitschan}Creating a FitsChan} + +The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{astFitsChan}{astFitsChan}, is straightforward to +use: + +\small +\begin{terminalv} +#include "ast.h" +AstFitsChan *fitschan; + +... + +fitschan = astFitsChan( NULL, NULL, "Encoding=NATIVE" ); +\end{terminalv} +\normalsize + +Here, we have omitted any source or sink functions by supplying NULL +pointers for the first two arguments. +We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to +NATIVE. This indicates that we will be using the native encoding +(\secref{ss:nativeencoding}) to store and retrieve Objects. If this +was left unspecified, the default would depend on the FitsChan's +contents. An attempt is made to use whatever encoding appears to have +been used previously. For an empty FitsChan, the default is NATIVE, +but it does no harm to be sure. + +\subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan} + +Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a +mechanism is needed for addressing them. This allows you to specify +where new cards are to be added, for example, or which card is to be +deleted. + +This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which +gives the index of the \emph{current card} in the FitsChan. You can +nominate any card you like to be current, simply by setting a new +value for the Card attribute, for example: + +\small +\begin{terminalv} +int icard; + +... + +astSetI( fitschan, "Card", icard ) +\end{terminalv} +\normalsize + +where ``icard'' contains the index of the card on which you wish to +operate next. Some functions will update the Card attribute as a +means of advancing through the sequence of cards, when reading them +for example, or to indicate which card matches a search criterion. + +The default value for Card is one, which is the index of the first +card. This means that you can ``rewind'' a FitsChan to access its +first card by clearing the Card attribute: + +\small +\begin{terminalv} +astClear( fitschan, "Card" ); +\end{terminalv} +\normalsize + +The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard} +attribute. This is a read-only attribute whose value is automatically +updated as you add or remove cards. It means you can address all the +cards in sequence using a loop such as the following: + +\small +\begin{terminalv} +int ncard; + +... + +ncard = astGetI( fitschan, "Ncard" ); +for ( icard = 1; icard <= ncard; icard++ ) { + astSetI( fitschan, "Card", icard ); + <access the current card> +} +\end{terminalv} +\normalsize + +However, it is usually possible to write slightly tidier loops based +on the \htmlref{astFindFits}{astFindFits} function described later +(\secref{ss:extractingfitscards} and +\secref{ss:findingandchangingfits}). + +If you set the Card attribute to a value larger than Ncard, the +FitsChan is regarded as being positioned at its \emph{end-of-file}. In +this case there is no current card and an attempt to obtain a value +for the Card attribute will always return the value Ncard~$+$~1. When +a FitsChan is empty, it is always at the end-of-file. + +\subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan} + +Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you +can write any AST \htmlref{Object}{Object} to it in the native encoding using the +\htmlref{astWrite}{astWrite} function. Let us assume we are writing a +\htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet}, +but for purposes of illustration a SkyFrame contains a more manageable +amount of data.} as follows: + +\small +\begin{terminalv} +AstSkyFrame *skyframe; +int nobj; + +... + +nobj = astWrite( fitschan, skyframe ); +\end{terminalv} +\normalsize + +Since we have selected the native encoding +(\secref{ss:nativeencoding}), there are no restrictions on the class +of Object we may write, so astWrite should always return a value of +one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel} +(\secref{ss:writingtoachannel}), this write operation will not produce +any output from our program. The FITS headers produced are simply +stored inside the FitsChan. + +After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to +reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card} +attribute will point at the card immediately after the last one +written. Since our FitsChan was initially empty, the Card attribute +will, in this example, point at the end-of-file +(\secref{ss:addressingfitscards}). + +The FITS standard imposes a limit of 68 characters on the length of +strings which may be stored in a single header card. Sometimes, a +description of an AST Object involves the use of strings which exceed +this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If +this occurs, the long string will be split over two or more header cards. +Each ``continuation'' card will have the keyword \texttt{CONTINUE} in +columns 1 to 8, and will contain a space in column 9 (instead of the +usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of +each of the strings (except the last one) to indicate that the string is +continued on the next card. + +Note, this splitting of long strings over several cards only occurs when +writing AST Objects to a FitsChan using the astWrite function and the +\emph{native} encoding. If a long string is stored in a FitsChan using +(for instance) the \htmlref{astPutFits}{astPutFits} or \htmlref{astPutCards}{astPutCards} function, it will simply be truncated. + + +\subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan} + +To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame} +above (\secref{ss:writingnativefits}), we must write a simple loop to +extract each card in turn and print it out. We must also remember to +rewind the FitsChan first, \emph{e.g.}\ using \htmlref{astClear}{astClear}. The following +loop would do: + +\small +\begin{terminalv} +#include <stdio.h> +char card[ 81 ]; + +... + +astClear( fitschan, "Card" ); +while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); +\end{terminalv} +\normalsize + +Here, we have used the \htmlref{astFindFits}{astFindFits} function to find a FITS card by +keyword. It is given a keyword template of ``\%f'', which matches any +FITS keyword, so it always finds the current card, which it +returns. Its fourth argument is set to 1, to indicate that the \htmlref{Card}{Card} +attribute should be incremented afterwards so that the following card +will be found the next time around the loop. astFindFits returns zero +when it reaches the end-of-file and this terminates the loop. + +If we were storing the FITS headers in an output FITS file instead of +printing them out, we might use a loop like this but replace +``printf'' with a suitable data storage operation. This would only be +necessary if we had not provided a sink function for the FitsChan +(\secref{ss:fitssourceandsink}). + +\subsection{The Native FitsChan Output Format} + +If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote +earlier (\secref{ss:writingnativefits}), we should obtain something +like the following: + +\small +\begin{terminalv} +COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST +COMMENT AST Beginning of AST data for SkyFrame object AST +COMMENT AST ................................................................ AST +BEGAST_A= 'SkyFrame' / Description of celestial coordinate system +NAXES_A = 2 / Number of coordinate axes +AX1_A = ' ' / Axis number 1 +BEGAST_B= 'SkyAxis ' / Celestial coordinate axis +ENDAST_A= 'SkyAxis ' / End of object definition +AX2_A = ' ' / Axis number 2 +BEGAST_C= 'SkyAxis ' / Celestial coordinate axis +ENDAST_B= 'SkyAxis ' / End of object definition +ISA_A = 'Frame ' / Coordinate system description +SYSTEM_A= 'FK4-NO-E' / Celestial coordinate system type +EPOCH_A = 1958.0 / Besselian epoch of observation +ENDAST_C= 'SkyFrame' / End of object definition +COMMENT AST ................................................................ AST +COMMENT AST End of AST data for SkyFrame object AST +COMMENT AST ---------------------------------------------------------------- AST +\end{terminalv} +\normalsize + +As you can see, this resembles the information that would be written +to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame +(\secref{ss:textualoutputformat}), except that it has been formatted +into 80-character header cards according to FITS conventions. + +There are also a number of other differences worth noting: + +\begin{enumerate} +\item There is no unnecessary information about default values +provided for the benefit of the human reader. This is because the \htmlref{Full}{Full} +attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this +information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You +can restore the information if you wish by setting Full to 0 or $+$1, +in which case additional COMMENT cards will be generated to hold it. + +\item The information is not indented, because FITS does not allow +this. However, if you change the Full attribute to 0 or $+$1, comments +will be included that are intended to help break up the sequence of +headers and highlight its structure. This will probably only be of use +if you are attempting to track down a problem by examining the FITS +cards produced in detail. + +\item The FITS keywords which appear to the left of the ``$=$'' signs +have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to +them. This is done in order to make each keyword unique. +\end{enumerate} + +This last point is worth further comment and is necessary because the +FITS standard only allows for certain keywords (such as COMMENT and +HISTORY) to appear more than once. \htmlref{astWrite}{astWrite} therefore appends an +arbitrary sequence of two characters to each new keyword it generates +in order to ensure that it does not duplicate any already present in +the FitsChan. + +The main risk from not following this convention is that some software +might ignore (say) all but the last occurrence of a keyword before +passing the FITS headers on. Such an event is unlikely, but would +obviously destroy the information present, so astWrite enforces the +uniqueness of the keywords it uses. The extra characters added are +ignored when the information is read back. + +As with a basic Channel, you can also suppress the comments produced +in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to +zero (\secref{ss:channelcommenting}). However, FITS headers are +traditionally generously commented, so this is not recommended. + +\subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan} + +To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back +as Objects for example, you should use the \htmlref{astPutFits}{astPutFits} function. You +can insert a card in front of the current one as follows: + +\small +\begin{terminalv} +astPutFits( fitschan, card, 0 ); +\end{terminalv} +\normalsize + +where the third argument of zero indicates that the current card +should not be overwritten. Note that facilities are not provided by +AST for formatting the card contents. + +After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the +original Card, or at the end-of-file if the FitsChan was originally +empty. Entering a sequence of cards is therefore straightforward. If +``cards'' is an array of pointers to strings containing FITS header +cards and ``ncards'' is the number of cards, then a loop such as the +following will insert the cards in sequence into a FitsChan: + +\small +\begin{terminalv} +#define MAXCARD 100 +char *cards[ MAXCARD ]; +int ncard; + +... + +for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); +\end{terminalv} +\normalsize + +The string containing a card need not be null terminated if it is at +least 80 characters long (we have not allocated space for the strings +themselves in this brief example). + +Note that astPutFits enforces the validity of a FitsChan by rejecting +any cards which do not adhere to the FITS standard. If any such cards +are detected, an error will result. + +\subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan} + +If you have all your cards concatenated together into a single long string, +each occupying 80 characters (with no delimiters), you can insert them +into a \htmlref{FitsChan}{FitsChan} in a single call using +\htmlref{astPutCards}{astPutCards}. +This call first empties the supplied FitsChan of any existing cards, then +inserts the new cards, and finally rewinds the FitsChan so that a +subsequent call to +\htmlref{astRead}{astRead} +will start reading from the first supplied card. The +astPutCards function uses \htmlref{astPutFits}{astPutFits} +internally to interpret and store each individual card, and so the +caveats in \secref{ss:addingfitscards} should be read. + +For instance, if you are using the CFITSIO library for access to FITS +files, you can use the CFITSIO fits\_hdr2str function to obtain a string suitable +for passing to astPutCards: + +\small +\begin{terminalv} + + +if( !fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) + fitschan = astFitsChan( NULL, NULL, "" ); + astPutCards( fitschan, header ); + header = free( header ); + wcsinfo = astRead( fitschan ); + + ... +} +\end{terminalv} +\normalsize + + + +\subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan} + +Once you have stored a FITS header description of an \htmlref{Object}{Object} in a +\htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}), +you can read it back using \htmlref{astRead}{astRead} in much the same way as with a +basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments +about validating the Object you read also apply +(\secref{ss:validatinginput}). If you have just written to the +FitsChan, you must remember to rewind it first: + +\small +\begin{terminalv} +AstObject *object; + +... + +astClear( fitschan, "Card" ); +object = astRead( fitschan ); +\end{terminalv} +\normalsize + +An important feature of a FitsChan is that read operations are +destructive. This means that if an Object description is found, it +will be consumed by astRead which will remove all the cards involved, +including associated COMMENT cards, from the FitsChan. Thus, if you +write an Object to a FitsChan, rewind, and read the same Object back, +you should end up with the original FitsChan contents. If you need to +circumvent this behaviour for any reason, it is a simple matter to +make a copy of a FitsChan using \htmlref{astCopy}{astCopy} +(\secref{ss:copyingobjects}). If you then read from the copy, the +original FitsChan will remain untouched. + +After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the +card immediately following the last card read, or the end-of-file of +there are no more cards. + +Since the \emph{native} encoding is being used, any long strings involved +in the object description will have been split into two or more adjacent +contuation cards when the Object was stored in the header using function +\htmlref{astWrite}{astWrite}. The astRead function reverses this process by concatenating any +such adjacent continuation cards to re-create the original long string. + + +\subsection{Saving and Restoring Multiple Objects in a FitsChan} + +When using the native FITS encoding, multiple Objects may be stored +and all I/O operations are sequential. This means that you can simply +write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation, +the \htmlref{Card}{Card} attribute will be updated so that the next write appends the +next \htmlref{Object}{Object} description to the previous one. + +If you then rewind the FitsChan, you can read the Objects back in the +original order. Reading them back will, of course, remove their +descriptions from the FitsChan (\secref{ss:readingnativefits}) but the +behaviour of the Card attribute is such that successive reads will +simply return each Object in sequence. + +The only thing that may require care, given that a FitsChan can always +be addressed randomly by setting its Card attribute, is to avoid +writing one Object on top of another. For obvious reasons, the Object +descriptions in a FitsChan must remain separate if they are to make +sense when read back. + +\subsection{Mixing Native Objects with Other FITS Cards} + +Of course, any real FITS header will contain other information besides +AST Objects, if only the mandatory FITS cards that must accompany all +FITS data. When FITS headers are read in from a real dataset, +therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with +many other cards. + +Because this is the normal state of affairs, the boolean (integer) +\htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when +you read an Object From a FitsChan, any irrelevant cards will simply +be skipped over until the start of the next Object description, if +any, is found. If you start reading part way through an Object +description, no error will result. The remainder of the description +will simply be skipped. + +Setting Skip to zero will change this behaviour to resemble that of a +basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data +are not permitted by default, but this will probably rarely be useful. + +\subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan} + +You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by +keyword, using the function \htmlref{astFindFits}{astFindFits}. This performs a search, +starting at the current card, until it finds a card whose keyword +matches the template you supply, or the end-of-file is reached. + +If a suitable card is found, astFindFits optionally returns the card's +contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to +identify the card found, or the one following it. The way you want the +Card attribute to be set is indicated by the final boolean (int) +argument to astFindFits. A value of one is returned to indicate +success. If a suitable card cannot be found, astFindFits returns a +value of zero to indicate failure and sets the FitsChan's Card +attribute to the end-of-file. + +Requesting that the Card attribute be set to indicate the card that +astFindFits finds is useful if you want to replace that card with a +new one, as in this example: + +\small +\begin{terminalv} +char newcard[ 81 ]; + +... + +(void) astFindFits( fitschan, "AIRMASS", NULL, 0 ); +astPutFits( fitschan, newcard, 1 ); +\end{terminalv} +\normalsize + +Here, astFindFits is used to search for a card with the keyword +AIRMASS, with a NULL pointer being given to indicate that we do not +want the card's contents returned. If the card is found, \htmlref{astPutFits}{astPutFits} +then overwrites it with a new card. Otherwise, the Card attribute +ends up pointing at the end-of-file and the new card is simply +appended to the end of the FitsChan. + +A similar approach can be used to delete selected cards from a +FitsChan using \htmlref{astDelFits}{astDelFits}, which deletes the current card: + +\small +\begin{terminalv} +if ( astFindFits( fitschan, "BSCALE", NULL, 0 ) ) astDelFits( fitschan ); +\end{terminalv} +\normalsize + +This deletes the first card, if any, with the BSCALE keyword. + +Requesting that astFindFits increments the Card attribute to identify +the card following the one found is more useful when writing loops. +For example, the following loop extracts each card whose keyword +matches the template ``CD\%6d'' (that is, ``CD'' followed by six +decimal digits): + +\small +\begin{terminalv} +while ( astFindFits( fitschan, "CD%6d", card, 1 ) { + <process the card's contents> +} +\end{terminalv} +\normalsize + +For further details of keyword templates, see the description of +astFindFits in \appref{ss:functiondescriptions}. + +\subsection{\label{ss:fitssourceandsink}Source and Sink Functions for FitsChans} + +The use of source and sink functions with a \htmlref{FitsChan}{FitsChan} is optional. This +is because you can always arrange to explicitly fill a FitsChan with +FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards}) +and you can also extract any +cards that remain and write them out yourself +(\secref{ss:extractingfitscards}) before you delete the FitsChan. + +If you choose to use these functions, however, they behave in a very +similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource} +and \secref{ss:channelsink}). You supply pointers to these functions, +as arguments to the constructor function \htmlref{astFitsChan}{astFitsChan} when you create +the FitsChan (\secref{ss:creatingafitschan}). The source function is +invoked implicitly at this point to fill the FitsChan with FITS cards +and the FitsChan is then rewound, so that the first card becomes +current. The sink function is automatically invoked later, when the +FitsChan is deleted, in order to write out any cards that remain in +it. + +The only real difference between the source and sink functions for a +FitsChan and a basic Channel is that FITS cards are limited in length +to 80~characters, so the choice of buffer size is simplified. The +``Source'' and ``Sink'' functions in \secref{ss:channelsource} and +\secref{ss:channelsink} could therefore be used to access FITS headers +stored in text files simply by changing LEN to be 80. If you were not +accessing a text file, however, appropriate changes to the I/O +statements would be needed since the separating newline characters +would be absent. The details obviously depend on the format of the +file you are handling, which need not necessarily be a true FITS file. + + +\cleardoublepage +\section{\label{ss:foreignfits}Using Foreign FITS Encodings} + +We saw in the previous section (\secref{ss:nativefits}) how to store +and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a +\htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to +NATIVE. However, the Objects we wrote could then only be read back by +other programs that use AST. + +In practice, we will also encounter FITS headers containing WCS +information written by other software systems. We will probably also +need to write FITS headers in a format that can be understood by these +systems. Indeed, this interchange of data is one of the main reasons +for the existence of FITS, so in this section we will examine how to +accommodate these requirements. + +\subsection{\label{ss:foreignencodings}The Foreign FITS Encodings} + +As mentioned previously (\secref{ss:nativeencoding}), there are a +number of conventions currently in use for storing WCS information in +FITS headers, which we call \emph{encodings}. Here, we are concerned +with those encodings defined by software systems other than AST, which +we term \emph{foreign encodings}. + +Currently, AST supports six foreign encodings, which may be selected +by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the +following (character string) values: + +\begin{quote} +\begin{description} +\item[DSS]\mbox{}\\ +This encoding stores WCS information using the convention developed at +the Space Telescope Science Institute for the Digitised Sky Survey +(DSS) astrometric plate calibrations. DSS images which use this +convention are widely available and it is understood by a number of +important and well-established astronomy applications. + +However, the calibration model used (based on a polynomial fit) is not +easily applicable to other types of data and creating the polynomial +coefficients needed to calibrate your own images can prove +difficult. For this reason, the DSS encoding is probably best viewed +as a ``read-only'' format. It is possible, however, to read in WCS +information using this encoding and then to write it back out again, +so long as only minor changes have been made. + +\item[FITS-WCS]\mbox{}\\ +This encoding is very important because it is based on a new FITS standard +which should, for the first time, address the problem of celestial coordinate +systems in a proper manner, by considerably extending the original FITS +standard. + +The conventions used are described in a series of papers by +E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the +``FITS-WCS papers''. They are described at +\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers +in this series have been agreed, this encoding should be understood by any +FITS-WCS compliant software and it is likely to be adopted widely for FITS +data in future. For details of the coverage of these conventions provided +by the FitsChan class, see \appref{ss:fitswcscoverage}. + +\item[FITS-IRAF]\mbox{}\\ +This encoding is based on the conventions described in the document +``World Coordinate Systems Representations Within the FITS Format'' by R.J. +Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from +fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed +by the IRAF data analysis facility, so its use will facilitate data +exchange with IRAF. This encoding is in effect a sub-set of the current +FITS-WCS encoding. + +\item[FITS-PC]\mbox{}\\ +This encoding is based on a previous version of the proposed new FITS WCS +standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe +axis rotation and scaling. Versions of AST prior to V1.5 used this scheme +for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j} +keywords instead.\footnote{There are many other differences between the +previous and the current FITS-WCS encodings. The keywords to describe +axis rotation and scaling is used purely as a label to identify the +scheme.} The FITS-PC encoding is included in AST V1.5 only to allow +FITS-WCS data created with previous versions to be read. It should not, +in general, be used to create new data sets. + +\item[FITS-AIPS]\mbox{}\\ +This encoding is based on the conventions described in the document +``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th +September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu +/fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS +data analysis facility, so its use will facilitate data exchange with +AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to +describe axis rotation and scaling. + +\item[FITS-AIPS++]\mbox{}\\ +Encodes coordinate system information in FITS +header cards using the conventions used by the AIPS++ project. +This is an extension of FITS-AIPS which includes some of the +features of FITS-PC and FITS-IRAF. +\end{description} +\end{quote} + +For more detail about the above encodings, see the description of the +Encoding attribute in \appref{ss:attributedescriptions}. + +\subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings} + +The foreign encodings available for storing WCS information in FITS +headers have a number of limitations when compared with the native +encoding of AST Objects (\secref{ss:nativefits}). The main ones are: + +\begin{enumerate} +\item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented +using a foreign FITS encoding. This should not come as a surprise, +because the purpose of storing WCS information in FITS headers is to +attach coordinate systems to an associated array of data. Since the +FrameSet is the AST Object designed for the same purpose +(\secref{ss:baseandcurrent}), there is a natural correspondence. + +The way in which a FrameSet is translated to and from the foreign +encoding also follows from this correspondence. The FrameSet's base +\htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS +data. These are the same as FITS pixel coordinates, in which the first +pixel (in 2 dimensions) has coordinates (1,1) at its +centre. Similarly, the current Frame of the FrameSet identifies the +FITS world coordinate system associated with the data. + +\item You may store a representation of only a single FrameSet in any +individual set of FITS header cards (\emph{i.e.}\ in a single +\htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may +over-write the previous one or generate an invalid representation of +your WCS information. + +This is mainly a consequence of the use of fixed FITS keywords by +foreign encodings and the fact that you cannot, in general, have +multiple FITS cards with the same keyword. + +\item In general, it will not be possible to store every possible +FrameSet that you might construct. Depending on the encoding, only +certain FrameSets that conform to particular restrictions can be +represented and, even then, some of their information may be lost. See +the description of the \htmlref{Encoding}{Encoding} attribute in +\appref{ss:attributedescriptions} for more details of these +limitations. +\end{enumerate} + +It should be understood that using foreign encodings to read and write +information held in AST Objects is essentially a process of converting +the data format. As such, it potentially suffers from the same +problems faced by all such processes, \emph{i.e.}\ differences between +the AST data model and that of the foreign encoding may cause some +information to be lost. Because the AST model is extremely flexible, +however, any data loss can largely be eliminated when reading. +Instead, this effect manifests itself in the form of the above +encoding-dependent restrictions on the kind of AST Objects which may +be written. + +One of the aims of the AST library, of course, is to insulate you from +the details of these foreign encodings and the restrictions they +impose. We will see shortly, therefore, how AST provides a mechanism +for determining whether your WCS information satisfies the necessary +conditions and allows you to make an automatic choice of which +encoding to use. + +\subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input} + +Let us now examine the practicalities of extracting WCS information +from a set of FITS header cards which have been written by some other +software system. We will pretend that our program does not know which +encoding has been used for the WCS information and must discover this +for itself. In order to have a concrete example, however, we will use +the following set of cards. These use the FITS-AIPS encoding and +contain a typical mix of other FITS cards which are irrelevant to the +WCS information in which we are interested: + +\small +\begin{terminalv} +SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 +BITPIX = -32 / Bits per pixel. +NAXIS = 2 / Number of dimensions +NAXIS1 = 300 / Length of x axis. +NAXIS2 = 300 / Length of y axis. +CTYPE1 = 'GLON-ZEA' / X-axis type +CTYPE2 = 'GLAT-ZEA' / Y-axis type +CRVAL1 = -149.56866 / Reference pixel value +CRVAL2 = -19.758201 / Reference pixel value +CRPIX1 = 150.500 / Reference pixel +CRPIX2 = 150.500 / Reference pixel +CDELT1 = -1.20000 / Degrees/pixel +CDELT2 = 1.20000 / Degrees/pixel +CROTA1 = 0.00000 / Rotation in degrees. +SURVEY = 'COBE DIRBE' +BUNITS = 'MJy/sr ' / +ORIGIN = 'CDAC ' / Cosmology Data Analysis Center +TELESCOP= 'COBE ' / COsmic Background Explorer satellite +INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] +PIXRESOL= 9 / Quad tree pixel resolution [6, 9] +DATE = '27/09/94' / FITS file creation date (dd/mm/yy) +DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) +COMMENT COBE specific keywords +DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) +DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) +\end{terminalv} +\normalsize + +The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into +it. If ``cards'' is an array of pointers to character strings holding +the header cards and ``ncards'' is the number of cards, this could be +done as follows: + +\small +\begin{terminalv} +#include "ast.h" +#define MAXCARD 100 +AstFitsChan *fitschan; +char *cards[ MAXCARD ]; +int icard, ncard; + +... + +fitschan = astFitsChan( NULL, NULL, "" ); +for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); +\end{terminalv} +\normalsize + +Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the +FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to +use the native encoding. This is because we are pretending not to know +which encoding to use and want AST to determine this for us. By +leaving the Encoding attribute un-set, its default value will adjust +to whichever encoding AST considers to be most appropriate, according +to the FITS header cards present. For details of how this choice is +made, see the description of the Encoding attribute in +\appref{ss:attributedescriptions}. + +This approach has the obvious advantages of making our program simpler +and more flexible and of freeing us from having to know about the +different encodings available. As a bonus, it also means that the +program will be able to read any new encodings that AST may support in +future, without needing to be changed. + +At this point, we could enquire the default value of the Encoding +attribute, which indicates which encoding AST intends to use, as +follows: + +\small +\begin{terminalv} +const char *encode; + +... + + +encode = astGetC( fitschan, "Encoding" ); +\end{terminalv} +\normalsize + +The result of this enquiry would be the string ``FITS-AIPS''. Note +that we could also have set the FitsChan's Encoding attribute +explicitly, such as when creating it: + +\small +\begin{terminalv} +fitschan = astFitsChan( NULL, NULL, "Encoding=FITS-AIPS" ); +\end{terminalv} +\normalsize + +If we tried to read information using this encoding +(\secref{ss:readingforeignfits}), but failed, we could then change the +encoding and try again. This would allow our program to take control +of how the optimum choice of encoding is arrived at. However, it would +also involve using explicit knowledge of the encodings available and +this is best avoided if possible. + +\subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header} + +Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined +how the WCS information is encoded +(\secref{ss:identifyingfitsencoding}), the next step is to read an AST +\htmlref{Object}{Object} from the FitsChan using \htmlref{astRead}{astRead}. We must also remember to +rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card} +attribute, which defaults to 1: + +\small +\begin{terminalv} +AstObject *wcsinfo; + +... + +astClear( fitschan, "Card" ); +wcsinfo = astRead( fitschan ); +\end{terminalv} +\normalsize + +If the pointer returned by astRead is not equal to AST\_\_NULL, then +an Object has been read successfully. Otherwise, there was either no +information to read or the choice of FITS encoding +(\secref{ss:identifyingfitsencoding}) was inappropriate. + +At this point you might like to indulge in a little data validation +along the lines described in \secref{ss:validatinginput}, for example: + +\small +\begin{terminalv} +if ( !strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { + <the Object is a FrameSet, so use it> +} else { + <something unexpected was read> +} +\end{terminalv} +\normalsize + +If a foreign encoding has definitely been used, then the Object will +automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so +this stage can be omitted. However, if the native encoding +(\secref{ss:nativeencoding}) might have been employed, which is a +possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then +any class of Object might have been read and a quick check would be +worthwhile. + +If you used \htmlref{astShow}{astShow} (\secref{ss:displayingobjects}) to examine the +FrameSet which results from reading our example FITS header +(\secref{ss:identifyingfitsencoding}), you would find that its base +\htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its +current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These +two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which +incorporates the effects of various rotations, scalings and a +``zenithal equal area'' sky projection, so that each pixel of the FITS +image is mapped on to a corresponding sky position in galactic +coordinates. + +Because this FrameSet may be used both as a Mapping +(\secref{ss:framesetasmapping}) and as a Frame +(\secref{ss:framesetasframe}), it may be employed directly to perform +many useful operations without any need to decompose it into its +component parts. These include: + +\begin{itemize} +\item Transforming data grid (FITS pixel) coordinates into galactic +coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}). + +\item Formatting coordinate values (either pixel or galactic +coordinates) ready for display to a user +(\secref{ss:formattingaxisvalues} and \secref{ss:normalising}). + +\item Enquiring about axis labels (or other axis +information---\secref{ss:frameattributes}) which might be used, for +example, to label columns of coordinates in a table +(\secref{ss:frameaxisattributes}). + +\item Aligning the image with another image from which a similar +FrameSet has been obtained (\secref{ss:registeringimages}). + +\item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay +a variety of graphical information (including a coordinate +grid---Figure~\ref{fig:gridplot}) on the displayed image. + +\item Generating a new FrameSet which reflects any geometrical +processing you perform on the associated image data +(\secref{ss:wcsprocessingexample}). This new FrameSet could then be +written out as FITS headers to describe the modified image +(\secref{ss:writingforeignfits}). +\end{itemize} + +If the FrameSet contains other Frames (apart from the base and current +Frames), then you would also have access to information about other +coordinate systems associated with the image. + +\subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read} + +It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan} +after we have read a \htmlref{FrameSet}{FrameSet} from it +(\secref{ss:readingforeignfits}). The following would rewind our +FitsChan and display its contents: + +\small +\begin{terminalv} +#include <stdio.h> +char card[ 81 ]; + +... + +astClear( fitschan, "Card" ); +while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); +\end{terminalv} +\normalsize + +The output, if we started with the example FITS header in +\secref{ss:identifyingfitsencoding}, might look like this: + +\small +\begin{terminalv} +SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 +BITPIX = -32 / Bits per pixel. +NAXIS = 2 / Number of dimensions +NAXIS1 = 300 / Length of x axis. +NAXIS2 = 300 / Length of y axis. +SURVEY = 'COBE DIRBE' +BUNITS = 'MJy/sr ' +ORIGIN = 'CDAC ' / Cosmology Data Analysis Center +TELESCOP= 'COBE ' / COsmic Background Explorer satellite +INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] +PIXRESOL= 9 / Quad tree pixel resolution [6, 9] +DATE = '27/09/94' / FITS file creation date (dd/mm/yy) +DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) +COMMENT COBE specific keywords +DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) +DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) +\end{terminalv} +\normalsize + +Comparing this with the original, you can see that all the FITS cards +that represent WCS information have been removed. They have +effectively been ``sucked out'' of the FitsChan by the destructive +read that \htmlref{astRead}{astRead} performs and converted into an equivalent +FrameSet. AST remembers where they were stored, however, so that if we +later write WCS information back into the FitsChan +(\secref{ss:writingforeignfits}) they will, as far as possible, go +back into their original locations. This helps to preserve the overall +layout of the FITS header. + +You can now see why astRead performs destructive reads. It is a +mechanism for removing WCS information from a FITS header while +insulating you, as a programmer, from the details of the encoding +being used. It means you can ensure that all relevant header cards +have been removed, giving you a clean slate, without having to know +which FITS keywords any particular encoding uses. + +Clearing this WCS information out of a FITS header is particularly +important when considering how to write new WCS information back after +processing (\secref{ss:writingforeignfits}). If any relevant FITS +cards are left over from the input dataset and find their way into the +new processed header, they could interfere with the new information +being written.\footnote{This can happen if a particular keyword is +present in the input header but is not used in the output header +(whether particular keywords are used can depend on the WCS +information being stored). In such a case, the original value would +not be over-written by a new output value, so would remain erroneously +present.} The destructive read mechanism ensures that this doesn't +happen. + +\subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps} + +One of the purposes of AST is to make it feasible to propagate WCS +information through successive stages of data processing, so that it +remains consistent with the associated image data. As far as possible, +this should happen regardless of the FITS encoding used to store the +original WCS information. + +If the data processing being performed does not change the +relationship between image pixel and world coordinates (whatever these +may be), then propagation of the WCS information is +straightforward. You can simply copy the FITS header from input to +output. + +If this relationship changes, however, then the WCS information must +be processed alongside the image data and a new FITS header generated +to represent it. In this case, the sequence of operations within your +program would probably be as follows: + +\begin{enumerate} +\item Read the image data and associated FITS header from the input +dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan} +(\secref{ss:identifyingfitsencoding}). + +\item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically +using a foreign FITS encoding---\secref{ss:readingforeignfits}). + +\item Process the image data and modify the FrameSet accordingly +(\emph{e.g.}~\secref{ss:wcsprocessingexample}). + +\item Write the FrameSet back into the FitsChan +(\secref{ss:writingforeignfits}). + +\item Perform any other modification of FITS header cards your program +may require. + +\item Write the FitsChan contents (\emph{i.e.}\ processed header +cards) and image data to the output dataset. +\end{enumerate} + +In stage (2), the original WCS information will be removed from the +FitsChan by a destructive read. Later, in stage (4), new WCS +information is written to replace it. This is the process which we +consider next (\secref{ss:writingforeignfits}). + +\subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header} + +Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back +into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS +encoding to use. Unfortunately, we cannot simply depend on the +default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the +input information (\secref{ss:identifyingfitsencoding}), because the +destructive action of reading the WCS data +(\secref{ss:destructiveread}) will have altered the FitsChan's +contents. This, in turn, will have changed the choice of default +encoding, probably causing it to revert to NATIVE. + +We will return to the question of the optimum choice of encoding +below. For now, let's assume that we want to use the same encoding +for output as we used for input. Since we enquired what that was +before we read the input WCS data from the FitsChan +(\secref{ss:identifyingfitsencoding}), we can now set that value +explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at +the same time (because the write will fail if the FitsChan is not +rewound). \htmlref{astWrite}{astWrite} can then be used to write the output WCS +information into the FitsChan: + +\small +\begin{terminalv} +int nobj; + +... + +astSet( fitschan, "Card=1, Encoding=%s", encode ); +nobj = astWrite( fitschan, wcsinfo ); +\end{terminalv} +\normalsize + +The value returned by astWrite (assigned to ``nobj'') indicates how +many Objects were written. This will either be 1 or zero. A value of +zero is used to indicate that the information could not be encoded in +the form you requested. If this happens, nothing will have been +written. + +If your choice of encoding proves inadequate, the probable reason is +that the changes you have made to the FrameSet have caused it to +depart from the data model which the encoding assumes. AST knows +about the data model used by each encoding and will attempt to +simplify the FrameSet you provide so as to fit into that model, thus +relieving you of the need to understand the details and limitations of +each encoding yourself.\footnote{Storing values in the FitsChan for +FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels), +before invoking +astWrite +can sometimes help to produce a successful write.} When this attempt fails, +however, you must consider what alternative encoding to use. + +Ideally, you would probably want to try a sequence of alternative +encodings, using an approach such as the following: + +\small +\begin{terminalv} +/* 1. */ +astSet( fitschan, "Card=1, Encoding=FITS-IRAF" ); +if ( !astWrite( fitschan, wcsinfo ) ) { + +/* 2. */ + astSetC( fitschan, "Encoding", encode ); + if ( !astWrite( fitschan, wcsinfo ) ) { + +/* 3. */ + astSet( fitschan, "Encoding=NATIVE" ); + (void) astWrite( fitschan, wcsinfo ); + } +} +\end{terminalv} +\normalsize + +That is: + +\begin{enumerate} +\item Start by trying the FITS-WCS encoding, on the grounds that FITS +should provide a universal interchange standard in which all WCS +information should be expressed if possible. + +\item If that fails, then try the original encoding used for the input +WCS information, on the grounds that you are at least not making the +information any harder for others to read than it originally was. + +\item If that also fails, then you are probably trying to store fairly +complex information for which you need the native encoding. Only other +AST programs will then be able to read this information, but these are +probably the only programs that will be able to do anything sensible +with it anyway. +\end{enumerate} + +An alternative approach might be to encode the WCS information in several +ways, since this gives the maximum chance that other software will be +able to read it. This approach is only possible if there is no +significant conflict between the FITS keywords used by the different +encodings\footnote{In practice, this means you should avoid mixing +FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share +many keywords.}. Adopting this approach would simply require multiple +calls to astWrite, rewinding the FitsChan and changing its Encoding value +before each one. + +Unfortunately, however, there is a drawback to duplicating WCS +information in the FITS header in this way, because any program which +modifies one version of this information and simply copies the +remainder of the header will risk producing two inconsistent sets of +information. This could obviously be confusing to subsequent +software. Whether you consider this a worthwhile risk probably depends +on the use to which you expect your data to be put. + +\cleardoublepage +\section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)} + +\htmladdnormallinkfoot{XML}{http://www.w3.org/XML/} +is fast becoming the standard format for passing structured data around +the internet, and much general purpose software has been written for +tasks such as the parsing, editing, display and transformation of XML +data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides +facilities for storing AST objects externally in the form of XML documents, +thus allowing such software to be used. + +The primary XML format used by the XmlChan class is a fairly close +transliteration of the AST native format produced by the basic Channel +class. Currently, there is no DTD or schema defining the structure of data +produced in this format by an XmlChan. The following is a native AST +representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full} +attribute set to zero so that some default attribute values are included +as extra comments): + +\small +\begin{terminalv} + Begin Frame # Coordinate system description +# Title = "1-d coordinate system" # Title of coordinate system + Naxes = 1 # Number of coordinate axes + Domain = "SCREEN" # Coordinate system domain +# Lbl1 = "Axis 1" # Label for axis 1 +# Uni1 = "cm" # Units for axis 1 + Ax1 = # Axis number 1 + Begin Axis # Coordinate axis + Unit = "cm" # Axis units + End Axis + End Frame +\end{terminalv} +\normalsize + +The corresponding XmlChan output would look like: + +\small +\begin{terminalv} + <Frame xmlns="http://www.starlink.ac.uk/ast/xml/" + desc="Coordinate system description"> + <_attribute name="Title" quoted="true" value="1-d coordinate system" + desc="Title of coordinate system" default="true"/> + <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/> + <_attribute name="Domain" quoted="true" value="SCREEN" + desc="Coordinate system domain"/> + <_attribute name="Lbl1" quoted="true" value="Axis 1" + desc="Label for axis 1" default="true"/> + <_attribute name="Uni1" quoted="true" value="cm" + desc="Units for axis 1" default="true"/> + <Axis label="Ax1" desc="Coordinate axis"> + <!--Axis number 1--> + <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/> + </Axis> + </Frame> +\end{terminalv} +\normalsize + + +Notes: + +\begin{enumerate} +\item The AST class name is used as the name for an XML element which contain +a description of an AST object. + +\item AST attributes are described by XML elements with the name +``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML +to refer to a ``name=value'' pair within an element start tag. So for +instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described +within an XML element with name ``\_attribute'' in which the XML attribute +``name'' has the value ``Title'', and the XML attribute ``value'' has the +value ``1-d coordinate system''. The moral is always to be clear clear +about the context (AST or XML) in which the word \emph{attribute} is being +used! + +\item The XML includes comments both as XML attributes with the name ``desc'', +and as separate comment tags. + +\item Elements which describe default values are identified by the fact +that they have an XML attribute called ``default'' set to the value +``true''. These elements are ignored when being read back into an XmlChan. + +\item The outer-most XML element of an AST object will set the default +namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be +inherited by all nested elements. + +\end{enumerate} + + +The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full +attributes (inherited from the base Channel class) to zero and -1, +resulting in terse output by default. With the default values for these +attributes, the above XML is reduced to the following: + +\small +\begin{terminalv} + <Frame xmlns="http://www.starlink.ac.uk/ast/xml/"> + <_attribute name="Naxes" value="1"/> + <_attribute name="Domain" quoted="true" value="SCREEN"/> + <Axis label="Ax1"> + <_attribute name="Unit" quoted="true" value="cm"/> + </Axis> + </Frame> +\end{terminalv} +\normalsize + + +The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel +class. If Skip is zero (the default) then an error will be reported if the text +supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If +Skip is non-zero, then initial text is skipped over without error until +the start of an AST object is found. this allows an AST object to be +located within a larger XML document. + +\subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions} +The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML +documents which use a restricted subset of an early draft (V1.20) of the +IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X +finally adopted by the IVOA differs in several significant respects from +V1.20, and so the STC-X support currently provided by AST is mainly of +historical interest. Note, AST also supports the alternative ``STC-S'' +linear string description of the STC model (see \secref{ss:stcschans}). + +STC-X V1.20 is documented at +\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current +version is documented at +\url{http://www.ivoa.net/Documents/latest/STC-X.html}. + +When an STC-X document is read using an XmlChan, the read operation +produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of +\htmlref{Region}{Region}. Specifically, each such Object will be an instance of +\htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or +\htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the +\htmlref{XmlFormat}{XmlFormat} attribute for further details. + +\cleardoublepage +\section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)} + +The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing +IVOA ``STC-S'' descriptions. STC-S (see +\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string +syntax that allows simple specification of the STC metadata describing a +region in an astronomical coordinate system. AST supports a +subset of the STC-S specification, allowing an STC-S description of a +region within an AST-supported astronomical coordinate system to be converted +into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further +details, see the full description of the StcsChan class in +\appref{ss:classdescriptions}. + + +\cleardoublepage +\section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)} + +\subsection{The Need for Extensibility} + +However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you +will want to transform coordinates in some way that has not been +foreseen. You might want to plot a graph in some novel curvilinear +coordinate system (perhaps you already have a WCS system in your +software and just want to use AST for its graphical capabilities). +Alternatively, you might need to calibrate a complex dataset (like an +objective prism plate) where each position must be converted to world +coordinates with reference to calibration data under the control of an +elaborate algorithm. + +In such cases, it is clear that the basic pre-formed components +provided by AST for building Mappings are just not enough. What you +need is access to a programming language. However, if you write your +own software to transform coordinate values, then it must be made +available in the form of an AST class (from which you can create +Objects) before it can be used in conjunction with other AST +facilities. + +At this point you might consider writing your own AST class, but this +is not recommended. Not only would the internal conventions used by +AST take some time to master, but you might also find yourself having +to change your software whenever a new version of AST was +released. Fortunately, there is a much easier route provided by the +\htmlref{IntraMap}{IntraMap} class. + +\subsection{The IntraMap Model} + +To allow you to write your own Mappings, AST provides a special kind +of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper'' +for a coordinate transformation function written in C. You write this +function yourself and then register it with AST. This, in effect, +creates a new class from which you can create Mappings +(\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever +way your transformation function specifies. + +Because IntraMaps are Mappings, they may be used in the same way as +any other Mapping. For instance, they may be combined in series or +parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}), +they may be inverted (\secref{ss:invertingmappings}), you may enquire +about their attributes (\secref{ss:gettingattributes}), they may be +inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do, +however, have some important limitations of which you should be aware +before we go on to consider how to create them. + +\subsection{\label{ss:intramaplimitations}Limitations of IntraMaps} + +By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is +required at all. After all, why not simply write your own coordinate +transformation functions in C, wrap them up in IntraMaps and do away +with all the other Mapping classes in AST? + +The reason is not too hard to find. Any transformation function you +write is created solely by you, so it is a private extension which +does not form a permanent part of AST. If you use it to calibrate some +data and then pass that data to someone else, who has only the +standard version of AST, then they will not be able to interpret it. + +Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators +(who we assume have access to the same transformation functions), it +does not address the need for universal data exchange like other AST +Mappings do. This is where the ``Intra'' in the class name +``IntraMap'' comes from, implying private or internal usage. + +For this reason, it is unwise to store IntraMaps in datasets, unless +they will be used solely for communication between collaborating items +of software which share conventions about their use. A private +database describing coordinate systems on a graphics device might be +an example where IntraMaps would be suitable, because the data would +probably never be accessed by anyone else's software. Restricting +IntraMap usage to within a single program (\emph{i.e.} never writing +it out) is, of course, completely safe. + +If, by accident, an IntraMap should happen to escape as part of a +dataset, then the unsuspecting recipient is likely to receive an error +message when they attempt to read the data. However, AST will +associate details of the IntraMap's transformation function and its +author (if provided) with the data, so that the recipient can make an +intelligent enquiry to obtain the necessary software if this proves +essential. + +\subsection{\label{ss:transformationfunctions}Writing a Transformation Function} + +The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate +transformation function. This should have a calling interface like the +\htmlref{astTranP}{astTranP} function provided by AST (\emph{q.v.}). Here is a simple +example of a suitable transformation function which transforms +coordinates by squaring them: +\xlabel{SqrTran} + +\small +\begin{terminalv} +#include "ast.h" +#include <math.h> + +void SqrTran( AstMapping *this, int npoint, int ncoord_in, + const double *ptr_in[], int forward, int ncoord_out, + double *ptr_out[] ) { + int point, coord; + double x; + +/* Forward transformation. */ + if ( forward ) { + for ( point = 0; point < npoint; point++ ) { + for ( coord = 0; coord < ncoord_in; coord++ ) { + x = ptr_in[ coord ][ point ]; + ptr_out[ coord ][ point ] = ( x == AST__BAD ) ? AST__BAD : x * x; + } + } + +/* Inverse transformation. */ + } else { + for ( point = 0; point < npoint; point++ ) { + for ( coord = 0; coord < ncoord_in; coord++ ) { + x = ptr_in[ coord ][ point ]; + ptr_out[ coord ][ point ] = + ( x < 0.0 || x == AST__BAD ) ? AST__BAD : sqrt( x ); + } + } + } +} +\end{terminalv} +\normalsize + +As you can see, the function comes in two halves which implement the +forward and inverse coordinate transformations. The number of points +to be transformed (``npoint'') and the numbers of input and output +coordinates per point (``ncoord\_in'' and ``ncoord\_out''---in this +case both are assumed equal) are passed to the function. A pair of +loops then accesses all the coordinate values. Note that it is +legitimate to omit one or other of the forward/inverse transformations +and simply not to implement it, if it will not be required. It is also +permissible to require that the numbers of input and output +coordinates be fixed (\emph{e.g.}\ at 2), or to write the function so +that it can handle arbitrary dimensionality, as here. + +Before using an incoming coordinate, the function must first check +that it is not set to the value AST\_\_BAD, which indicates missing +data (\secref{ss:badcoordinates}). If it is, the same value is also +assigned to any affected output coordinates. The value AST\_\_BAD is +also generated if any coordinates cannot be transformed. In this +example, this can happen with the inverse transformation if negative +values are encountered, so that the square root cannot be taken. + +There are very few restrictions on what a coordinate transformation +function may do. For example, it may freely perform I/O to access any +external data needed, it may invoke other AST facilities (but beware +of unwanted recursion), \emph{etc.} Typically, you may also want to +pass information to it \emph{via}\ global variables. Remember, +however, that whatever facilities the transformation function requires +must be available in every program which uses it. + +Generally, it is not a good idea to retain context information within +a transformation function. That is, it should transform each set of +coordinates as a single point and retain no memory of the points it +has transformed before. This is in order to conform with the AST model +of a \htmlref{Mapping}{Mapping}. + +If an error occurs within a transformation function, it should use the +\htmlref{astSetStatus}{astSetStatus} function (\secref{ss:errordetection}) to set the AST +status to an error value before returning. This will alert AST to the +error, causing it to abort the current operation. The error value +AST\_\_ITFER is available for this purpose, but other values may also +be used (\emph{e.g.}\ if you wish to distinguish different types of +error). + +\subsection{\label{ss:registeringintramaps}Registering a Transformation Function} + +Having written your coordinate transformation function, the next step +is to register it with AST. Registration is performed using +\htmlref{astIntraReg}{astIntraReg}, as follows: + +\small +\begin{terminalv} +void SqrTran( AstMapping *, int, int, const double *[], int, int, double *[] ); + +const char *author, *contact, *purpose; + +... + +purpose = "Square each coordinate value"; +author = "R.F. Warren-Smith & D.S. Berry"; +contact = "http://www.starlink.ac.uk/cgi-bin/htxserver/sun211.htx/?xref_SqrTran"; + +astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact ); +\end{terminalv} +\normalsize + +Note that you should also provide a function prototype to describe the +transformation function (the implementation of the function itself +would suffice, of course). + +The first argument to astIntraReg is a name by which the +transformation function will be known. This will be used when we come +to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you use +the actual function name here and make this sufficiently unusual that +it is unlikely to clash with any other functions in most people's +software. + +The next two arguments specify the number of input and output +coordinates which the transformation function will handle. These +correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will +create. Here, we have set them both to 2, which means that we will +only be able to create IntraMaps with 2 input and 2 output coordinates +(despite the fact that the transformation function can actually handle +other dimensionalities). We will see later +(\secref{ss:variableintramapcoordinates}) how to remove this +restriction. + +The fourth argument should contain a set of flags which describe the +transformation function in a little more detail. We will return to +this shortly (\secref{ss:restrictedintramaps} \& +\secref{ss:simplifyingintramaps}). For now, we supply a value of zero. + +The remaining arguments are character strings which document the +transformation function, mainly for the benefit of anyone who is +unfortunate enough to encounter a reference to it in their data which +they cannot interpret. As explained above +(\secref{ss:intramaplimitations}), you should try and avoid this, but +accidents will happen, so you should always provide strings containing +the following: + +\begin{enumerate} +\item A short description of what the transformation function is for. +\item The name of the author. +\item Contact details, such as an e-mail or WWW address. +\end{enumerate} + +The idea is that anyone finding an IntraMap in their data, but lacking +the necessary transformation function, should be able to contact the +author and make a sensible enquiry in order to obtain it. If you +expect many enquiries, you may like to set up a World Wide Web page +and use that instead (in the example above, we use the WWW address of +the relevant part of this document). + +\subsection{Creating an IntraMap} + +Once a transformation function has been registered, creating an +\htmlref{IntraMap}{IntraMap} from it is simple: + +\small +\begin{terminalv} +AstIntraMap *intramap; + +... + +intramap = astIntraMap( "SqrTran", 2, 2, "" ); +\end{terminalv} +\normalsize + +We simply use the \htmlref{astIntraMap}{astIntraMap} constructor function and pass it the +name of the transformation function to use. This name is the same +(case sensitive) one that we associated with the function when we +registered it using \htmlref{astIntraReg}{astIntraReg} (\secref{ss:registeringintramaps}). + +You can, of course, register any number of transformation functions +and select which one to use whenever you create an IntraMap. You can +also create any number of independent IntraMaps using each +transformation function. In this sense, each transformation function +you register effectively creates a new ``sub-class'' of IntraMap, from +which you can create Objects just like any other class. However, an +error will occur if you attempt to use a transformation function that +has not yet been registered. + +The second and third arguments to astIntraMap are the numbers of input +and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for +the IntraMap that is created and they must match the corresponding +numbers given when the transformation function was registered. + +The final argument is the usual attribute initialisation string. You +may set attribute values for an IntraMap in exactly the same way as +for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see +\secref{ss:intraflag}). + +\subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Functions} + +You may not always want to use both the forward and inverse +transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit +either from the underlying coordinate transformation +function. Consider the following, for example: + +\small +\begin{terminalv} +void Poly3Tran( AstMapping *this, int npoint, int ncoord_in, + const double *ptr_in[], int forward, int ncoord_out, + double *ptr_out[] ) { + double x; + int point; + +/* Forward transformation. */ + for ( point = 0; point < npoint; point++ ) { + x = ptr_in[ 0 ][ point ]; + ptr_out[ 0 ][ point ] = ( x == AST__BAD ) ? AST__BAD : + 6.18 + x * ( 0.12 + x * ( -0.003 + x * 0.0000101 ) ); + } +} +\end{terminalv} +\normalsize + +This implements a 1-dimensional cubic polynomial transformation. Since +this is somewhat awkward to invert, however, we have only implemented +the forward transformation. When registering the function, this is +indicated via the ``flags'' argument to \htmlref{astIntraReg}{astIntraReg}, as follows: + +\small +\begin{terminalv} +void Poly3Tran( AstMapping *, int, int, const double *[], int, int, double *[] ); + +... + +astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, + purpose, author, contact ); +\end{terminalv} +\normalsize + +Here, the fifth argument has been set to the flag value AST\_\_NOINV +to indicate the lack of an inverse. If the forward transformation were +absent, we would use AST\_\_NOFOR instead. Flag values for this +argument may be combined using a bitwise OR if necessary. + +\subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates} + +In our earlier examples, we have used a fixed number of input and +output coordinates when registering a coordinate transformation +function. It is not necessary to impose this restriction, however, if +the transformation function can cope with a variable number of +coordinates (as with the example in +\secref{ss:transformationfunctions}). We indicate the acceptability of +a variable number when registering the transformation function by +supplying the value AST\_\_ANY for the number of input and/or output +coordinates, as follows: + +\small +\begin{terminalv} +astIntraReg( "SqrTran", AST__ANY, AST__ANY, SqrTran, 0, + purpose, author, contact ); +\end{terminalv} +\normalsize + +The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of +input and output coordinates. For example: + +\small +\begin{terminalv} +AstIntraMap *intramap1, *intramap2; + +... + +intramap1 = astIntraMap( "SqrTran", 1, 1, "" ); +intramap2 = astIntraMap( "SqrTran", 3, 3, "Invert=1" ); +\end{terminalv} +\normalsize + +It is possible to fix either the number of input or output coordinates +(by supplying an explicit number to \htmlref{astIntraReg}{astIntraReg}), but more subtle +restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin} +and \htmlref{Nout}{Nout} be equal, are not supported. This means that: + +\small +\begin{terminalv} +intramap = astIntraMap( "SqrTran", 1, 2, "" ); +\end{terminalv} +\normalsize + +will be accepted without error, although the transformation function +cannot actually handle such a combination sensibly. If this is +important, it would be worth adding a check within the transformation +function itself, so that the error would be detected when it came to +be used. + +\subsection{\label{ss:intraflag}Adapting a Transformation Function to Individual IntraMaps} + +In the examples given so far, our coordinate transformation functions +have not made use of the ``this'' pointer passed to them (which +identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In +practice, this will often be the case. However, the presence of the +``this'' pointer allows the transformation function to invoke any +other AST function on the IntraMap, and this permits enquiries about +its attributes. The transformation function's behaviour can therefore +be modified according to any attribute values which are set. This +turns out to be a useful thing to do, so each IntraMap has a special +\htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose. + +Consider, for instance, the case where the transformation function has +access to several alternative sets of internally-stored data which it +may apply to perform its transformation. Rather than implement many +different versions of the transformation function, you may switch +between them by setting a value for the IntraFlag attribute when you +create an instance of an IntraMap, for example: + +\small +\begin{terminalv} +intramap1 = astIntraMap( "MyTran", 2, 2, "IntraFlag=A" ); +intramap2 = astIntraMap( "MyTran", 2, 2, "IntraFlag=B" ); +\end{terminalv} +\normalsize + +The transformation function may then enquire the value of the IntraFlag +attribute (\emph{e.g.}\ using astGetC and passing it the ``this'' +pointer) and use whichever dataset is required for that particular +IntraMap. + +This approach is particularly useful when the number of possible +transformations is unbounded or not known in advance, in which case +the IntraFlag attribute may be used to hold numerical values encoded +as part of a character string (effectively using them as data for the +IntraMap). It is also superior to the use of a global switch for +communication (\emph{e.g.}\ setting an index to select the ``current'' +data before using the IntraMap), because it continues to work when +several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping}, +when you may have no control over the order in which they are used. + +\subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps} + +A notable disadvantage of IntraMaps is that they are ``black boxes'' +as far as AST is concerned. This means that they have limited ability +to participate in the simplification of compound Mappings performed, +\emph{e.g.}, by \htmlref{astSimplify}{astSimplify} (\secref{ss:simplifyingcmpmaps}), because +AST cannot know how they interact with other Mappings. In reality, of +course, they will often implement such specialised coordinate +transformations that the simplification possibilities will be rather +limited anyway. + +One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to +cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This +is important because Mappings are frequently used to relate a dataset +to some external standard (a celestial coordinate system, for +example). When inter-relating two similar datasets calibrated using +the same standard, part of the Mapping often cancels, because it is +applied first in one direction and then the other, effectively +eliminating the reference to the standard. This is often a useful +simplification and can lead to greater efficiency. + +Many transformations have this property of cancelling with their own +inverse, but not necessarily all. Consider the following +transformation function, for example: + +\small +\begin{terminalv} +void MaxTran( AstMapping *this, int npoint, int ncoord_in, + const double *ptr_in[], int forward, int ncoord_out, + double *ptr_out[] ) { + double hi, x; + int coord, point; + +/* Forward transformation. */ + if ( forward ) { + for ( point = 0; point < npoint; point++ ) { + hi = AST__BAD; + for ( coord = 0; coord < ncoord_in; coord++ ) { + x = ptr_in[ coord ][ point ]; + if ( x != AST__BAD ) { + if ( x > hi || hi == AST__BAD ) hi = x; + } + } + ptr_out[ 0 ][ point ] = hi; + } + +/* Inverse transformation. */ + } else { + for ( coord = 0; coord < ncoord_out; coord++ ) { + for ( point = 0; point < npoint; point++ ) { + ptr_out[ coord ][ point ] = ptr_in[ 0 ][ point ]; + } + } + } +} +\end{terminalv} +\normalsize + +This function takes any number of input coordinates and returns a +single output coordinate which is the maximum value of the input +coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the +input coordinates to the value of the output +coordinate.\footnote{Remember that ``ptr\_in'' identifies the original +``output'' coordinates when applying the inverse transformation and +``ptr\_out'' identifies the original ``input'' coordinates.} + +If this function is applied in the forward direction and then in the +inverse direction, it does \textbf{not} in general restore the original +coordinate values. However, if applied in the inverse direction and +then the forward direction, it does. Hence, replacing the sequence of +operations with an equivalent UnitMap is possible in the latter case, +but not in the former. + +To distinguish these possibilities, two flag values are provided for +use with \htmlref{astIntraReg}{astIntraReg} to indicate what simplification (if any) is +possible. For example, to register the above transformation function, +we might use: + +\small +\begin{terminalv} +void MaxTran( AstMapping *, int, int, const double *[], int, int, double *[] ); + +... + +astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, + purpose, author, contact ); +\end{terminalv} +\normalsize + +Here, the flag value AST\_\_SIMPIF supplied for the fifth argument +indicates that simplification is possible if the transformation is +applied in the inverse direction followed by the forward direction. To +indicate the complementary case, the flag AST\_\_SIMPFI would be used +instead. If both simplifications are possible (as with the SqrTran +function in \secref{ss:transformationfunctions}), then we would use +the bitwise OR of both values. + +In practice, some judgement is usually necessary when deciding whether +to allow simplification. For example, seen in one light our SqrTran +function (\secref{ss:transformationfunctions}) does not cancel with +its own inverse, because squaring a coordinate value and then taking +its square root can change the original value, if this was +negative. Therefore, replacing this combination with a UnitMap will +change the behaviour of a compound Mapping and should not be +allowed. Seen in another light, however, where the coordinates being +processed are intrinsically all positive, it is a permissible and +probably useful simplification. + +If such distinctions are ever important in practice, it is simple to +register the same transformation function twice with different flag +values (use a separate name for each) and then use whichever is +appropriate when creating an \htmlref{IntraMap}{IntraMap}. + +\subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps} + +It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a +\htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation function +which it uses is not stored with it. To do so is impossible, because +the function has been compiled and loaded into memory ready for +execution before AST gets to see it. However, AST does store the name +associated with the transformation function and various details about +the IntraMap itself. + + +This means that any program attempting to read the IntraMap +(\secref{ss:readingfromachannel}) cannot make use of it unless it also +has independent access to the original transformation function. If it +does not have access to this function, an error will occur at the +point where the IntraMap is read and the associated error message will +direct the user to the author of the transformation function for more +information. + +However, if the necessary transformation function is available, and +has been registered before the read operation takes place, then AST is +able to re-create the original IntraMap and will do so. Registration +of the transformation function must, of course, use the same name +(and, in fact, be identical in most particulars) as was used in the +original program which wrote the data. + +This means that a set of co-operating programs which all have access +to the same set of transformation functions and register them in +identical fashion (see \secref{ss:intramaplibrary} for how this can +best be achieved) can freely exchange data that contain IntraMaps. The +need to avoid exporting such data to unsuspecting third parties +(\secref{ss:intramaplimitations}) must, however, be re-iterated. + +\subsection{\label{ss:intramaplibrary}Managing Transformation Functions in Libraries} + +If you are developing a large suite of data reduction software, you +may have a need to use IntraMaps at various points within it. Very +probably this will occur in unrelated modules which are compiled +separately and then stored in a library. Since the transformation +functions required must be registered before they can be used, this +makes it difficult to decide where to perform this registration, +especially since any particular data reduction program may use an +arbitrary subset of the modules in your library. + +To assist with this problem, AST allows you to perform the same +registration of a transformation function any number of times, so long +as it is performed using an identical invocation of \htmlref{astIntraReg}{astIntraReg} on +each occasion (\emph{i.e.}\ all of its arguments must be +identical). This means you do not have to keep track of whether a +particular function has already been registered but could, in fact, +register it on each occasion immediately before it is required +(wherever that may be). In order that all registrations are identical, +however, it is recommended that you group them all together into a +single function, perhaps as follows: + +\small +\begin{terminalv} +void MyTrans( void ) { + + ... + + astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, + purpose, author, contact ); + + ... + + astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, + purpose, author, contact ); + + ... + + astIntraReg( "SqrTran", 2, 2, SqrTran, 0, + purpose, author, contact ); +} +\end{terminalv} +\normalsize + +You can then simply invoke this function wherever necessary. It is, in +fact, particularly important to register all relevant transformation +functions in this way before you attempt to read an \htmlref{Object}{Object} that might +be (or contain) an \htmlref{IntraMap}{IntraMap} +(\secref{ss:readingandwritingintramaps}). This is because you may not +know in advance which of these transformation functions the IntraMap +will use, so they must all be available in order to avoid an error. + +\cleardoublepage +\section{\label{ss:plots}Producing Graphical Output (Plots)} + +Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot}, +which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the +graphical content itself, but is a route through which plotting +operations, such as drawing lines and curves, are conveyed on to a +plotting surface to appear as visible graphics. + +\subsection{The Plot Model} + +When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose +base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or +logarithmically (as specified by the LogPlot attribues) on to a +\emph{plotting area}. This is a rectangular region in the graphical +coordinate space of the underlying graphics system and becomes the new +base Frame of the Plot. In effect, the Plot becomes attached to the +plotting surface, in rather the same way that a basic FrameSet might be +attached to (say) an image. + +The current Frame of the Plot (derived from the current Frame of the +FrameSet supplied) is used to represent a \emph{physical coordinate +system}. This is the system in which plotting operations are +performed by your program. Every plotting operation is then +transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current +and base Frames in order to appear on the plotting surface. + +An example may help here. Suppose we start with a FrameSet whose base +Frame describes the pixel coordinates of an image and whose current +Frame describes a celestial (equatorial) coordinate system. Let us +assume that these two Frames are inter-related by a Mapping within the +FrameSet which represents a particular sky projection. + +When a Plot is created from this FrameSet, we specify how the pixel +coordinates (the base Frame) maps on to the plotting surface. This +simply corresponds to telling the Plot where we have previously +plotted the image data. If we now use the Plot to plot a line with +latitude zero in our physical coordinate system, as given by the +current Frame, this line would appear as a curve (the equator) on the +plotting surface, correctly registered with the image. + +There are a number of plotting functions provided, which all work in a +similar way. Plotting operations are transformed through the Mapping +which the Plot represents before they appear on the plotting +surface.\footnote{Like any FrameSet, a Plot can be used as a +Mapping. In this case it is the inverse transformation which is used +when plotting (\emph{i.e.}\ that which transforms between the current +and base Frames).} It is possible to draw symbols, lines, axes, +entire grids and more in this way. + +%\subsection{TBW---Creating a Plot} + +\subsection{Plotting Symbols} + +The simplest form of plotting is to draw symbols (termed +\emph{markers}) at a set of points. This is performed by \htmlref{astMark}{astMark}, +which is supplied with a set of physical coordinates at which to place +the markers: + +\small +\begin{terminalv} +#include "ast.h" +#define NCOORD 2 +#define NMARK 10 +double in[ NCOORD ][ NMARK ]; +int type; + +... + +astMark( plot, NMARK, NCOORD, NMARK, in, type ); +\end{terminalv} +\normalsize + +Here, NMARK specifies how many markers to plot and NCOORD specifies +how many coordinates are being supplied for each +point.\footnote{Remember, the physical coordinate space need not +necessarily be 2-dimensional, even if the plotting surface is.} The +array ``in'' supplies the coordinates and the integer ``type'' +specifies which type of marker to plot. + +\subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves} + +There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight +line in physical coordinates can potentially turn into a curve in +graphical coordinates. We therefore start by considering how to draw +geodesic curves. These are curves which trace the path of shortest +distance between two points in physical coordinates + and are the basic drawing element in a Plot. + +In many instances, the geodesic will, in fact, be a straight line, but +this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a +celestial coordinate system, for instance, it will be a great circle +(corresponding with the behaviour of the \htmlref{astDistance}{astDistance} function which +defines the metric of the physical coordinate space). The geodesic +will, of course, be transformed into graphics coordinates before being +plotted. A geodesic curve is plotted using \htmlref{astCurve}{astCurve} as follows: + +\small +\begin{terminalv} +double start[ NCOORD ], finish[ NCOORD ]; + +... + +astCurve( plot, start, finish ); +\end{terminalv} +\normalsize + +Here, ``start'' and ``finish'' are arrays containing the starting and +finishing coordinates of the curve. The \htmlref{astOffset}{astOffset} and astDistance +functions can often be useful for computing these +(\secref{ss:distanceandoffset}). + +If you need to draw a series of curves end-to-end (when drawing a +contour line, for example), then a more efficient alternative is to +use \htmlref{astPolyCurve}{astPolyCurve}. This has the same effect as a sequence of +invocations of astCurve, but allows you to supply a whole set of +points at one time. astPolyCurve then joins them, in sequence, using +geodesic curves: + +\small +\begin{terminalv} +#define NPOINT 100 +double coords[ NCOORD ][ NPOINT ]; + +... + +astPolyCurve( plot, NPOINT, NCOORD, NPOINT, coords ); +\end{terminalv} +\normalsize + +Here, NPOINT specifies how many points are to be joined and NCOORD +specifies how many coordinates are being supplied for each point. The +array ``coords'' supplies the coordinates of the points in the Plot's +physical coordinate system. + +\subsection{Plotting Curves Parallel to Axes} + +As there is no \htmlref{Plot}{Plot} function to draw a ``straight line'', drawing axes +and grid lines to represent coordinate systems requires a slightly +different approach. The problem is that for some coordinate systems, +these grid lines will not be geodesics, so \htmlref{astCurve}{astCurve} and \htmlref{astPolyCurve}{astPolyCurve} +(\secref{ss:plottinggeodesics}) cannot easily be used (you would have +to resort to approximating grid lines by many small elements). Lines +of constant celestial latitude provide an example of this, with the +exception of the equator which is a geodesic. + +The \htmlref{astGridLine}{astGridLine} function allows these curves to be drawn, as follows: + +\small +\begin{terminalv} +int axis; +double length; + +... + +astGridLine( plot, axis, start, length ); +\end{terminalv} +\normalsize + +Here, ``axis'' specifies which physical coordinate axis we wish to +draw parallel to. The ``start'' array contains the coordinates of the +start of the curve and ``length'' specifies the distance to draw along +the axis in physical coordinate space. + +\subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves} +We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot} +class includes another method, +\htmlref{astGenCurve}{astGenCurve}, +which allows curves of \emph{any} form to be drawn. The caller supplies a +\htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the +start of the curve is at offset 0.0 and the end of the curve is at offset +1.0 - offset need not be linearly related to distance.} into the +corresponding position in the current \htmlref{Frame}{Frame} of the Plot. +astGenCurve, +then takes care of Mapping these positions into graphics coordinates. The +choice of exactly which positions along the curve are to be used to +define the curve is also made by +astGenCurve, +using an adaptive algorithm which concentrates points around areas where +the curve is bending sharply or is discontinuous in graphics coordinates. + +The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows +you to code your own Mappings to do any transformation you choose. + + +\subsection{\label{ss:clipping}Clipping} + +Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics +you produce. This means that plotting is restricted to certain regions +of the plotting surface so that anything drawn outside these regions +will not appear. All Plots automatically clip at the edges of the +plotting area specified when the Plot is created. This means that +graphics are ultimately restricted to the rectangular region of +plotting space to which you have attached the Plot. + +In addition to this, you may also specify lower and upper limits on +each axis at which clipping should occur. This permits you to further +restrict the plotting region. Moreover, you may attach these clipping +limits to \emph{any} of the Frames in the Plot. This allows you to +place restrictions on where plotting will take place in either the +physical coordinate system, the graphical coordinate system, or in any +other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot. + +For example, you could plot using equatorial coordinates and set up +clipping limits in galactic coordinates. In general, you could set up +arbitrary clipping regions by adding a new Frame to a Plot (in which +clipping will be performed) and inter-relating this to the other +Frames in a suitable way. + +Clipping limits are defined using the \htmlref{astClip}{astClip} function, as follows: + +\small +\begin{terminalv} +#define NAXES 2 +int iframe; +double lbnd[ NAXES ], ubnd[ NAXES ]; + +... +astClip( plot, iframe, lbnd, ubnd); +\end{terminalv} +\normalsize + +Here, the ``iframe'' value gives the index of the Frame within the +Plot to which clipping is to be applied, while ``lbnd'' and ``ubnd'' +give the limits on each axis of the selected Frame (NAXES is the +number of axes in this Frame). + +You can remove clipping by giving a value of AST\_\_NOFRAME for ``iframe''. + +\subsection{Using a Plot as a Mapping} + +All Plots are also Mappings (just like the FrameSets from which they +are derived), so can be used to transform coordinates. + +Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert +coordinates between the base and current Frames (\emph{i.e.}\ between +graphical and physical coordinates). This would be useful if you were +(say) reading a cursor position in graphical coordinates and needed to +convert this into physical coordinates for display. + +Conversely, a Plot's inverse transformation converts between its +current and base Frames (\emph{i.e.}\ from physical coordinates to +graphical coordinates). This transformation is applied automatically +whenever plotting operations are carried out by AST functions. It may +also be useful to apply it directly, however, if you wish to perform +additional plotting operations (\emph{e.g.}\ those provided by the +native graphics system) at positions specified in physical +coordinates. + +There is, however, one important difference between using a \htmlref{FrameSet}{FrameSet} +and a Plot to transform coordinates, and this is that clipping may be +applied by a Plot (if it has been enabled using +\htmlref{astClip}{astClip}---\secref{ss:clipping}). Any point which lies within the +clipped region of a Plot will, when transformed, yield coordinates +with the value AST\_\_BAD. If you wish to avoid this clipping, you +should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using +\htmlref{astGetMapping}{astGetMapping}) and use this, instead of the Plot, to transform the +coordinates. + +\subsection{Using a Plot as a Frame} + +Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of +Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units, +\emph{etc.}, which are typically used when displaying data and/or +coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from +the current Frame of the Plot (\secref{ss:framesetasframe}). They are +also used automatically when using the Plot to plot coordinate axes +and coordinate grids (\emph{e.g.}\ for labelling +them---\secref{ss:plottingagrid}). + +Because the current Frame of a Plot represents physical coordinates, +any Frame operation applied to the Plot will effectively be working in +this coordinate system. For example, the \htmlref{astDistance}{astDistance} and \htmlref{astOffset}{astOffset} +functions will compute distances and offsets in physical coordinate +space, while \htmlref{astFormat}{astFormat} and \htmlref{astNorm}{astNorm} will format physical coordinates in +an appropriate way for display. + +\subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates} + +When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot} +into graphics coordinates for plotting, they may not always yield +valid coordinates, irrespective of any clipping being applied +(\secref{ss:clipping}). To indicate this, the resulting coordinate +values will be set to the value AST\_\_BAD +(\secref{ss:badcoordinates}). + +There are a number of reasons why this may occur, but typically it +will be because physical coordinates only map on to a subset of the +graphics coordinate space. This situation is commonly encountered with +all-sky projections where, typically, the celestial sphere appears, +when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which +does not entirely fill the graphics space. In some cases, there may +even be multiple regions of valid and invalid physical coordinates. + +When plotting is performed \emph{via} a Plot, graphical output will +only appear in the regions of valid physical coordinates. Nothing will +appear where invalid coordinates occur. Such output is effectively +clipped. If you wish to plot in these areas, you must change +coordinate system and use, say, graphical coordinates to address the +plotting surface directly. + +\subsection{Plotting Borders} + +The \htmlref{astBorder}{astBorder} function is provided to draw a (line) border around your +graphical output. With most graphics systems, this would simply be a +rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this +boundary follows the edge of each region containing valid, unclipped +physical coordinates (\secref{ss:validphysicalcoordinates}). + +This means, for example, that if you were plotting an all-sky +projection, this boundary would outline the perimeter of the celestial +sphere when projected on to your plotting surface. Of course, if there +is no clipping and all physical coordinates are valid, then you will +get the traditional rectangular box. astBorder requires only +a pointer to the Plot: + +\small +\begin{terminalv} +int holes; + +... + +holes = astBorder( plot ); +\end{terminalv} +\normalsize + +It returns a boolean (integer) value to indicate if any invalid or +clipped physical coordinates were found within the plotting area. If +they were, it will draw around the valid unclipped regions and return +a value of one. Otherwise, it will draw a simple rectangular border +and return zero. + +\subsection{Plotting Text} + +Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be +displayed and a position in physical coordinates where the text is to +appear. The position is transformed into graphical coordinates to +determine where the text should appear on the plotting surface. You +must also provide a 2-element ``up'' vector which gives the upward +direction of the text in graphical coordinates. This allows text to be +drawn at any angle. + +Plotting is performed by \htmlref{astText}{astText}, for example: + +\small +\begin{terminalv} +char text[ 21 ]; +double pos[ NCOORD ]; +float up[ 2 ] = { 0.0f, 1.0f }; + +... + +astText( plot, text, pos, up, "TL" ); +\end{terminalv} +\normalsize + +Here, ``text'' contains the string to be drawn, ``pos'' is an array of +physical coordinates and ``up'' specifies the upward vector. In this +case, the text will be drawn horizontally. The final argument +specifies the text justification, here indicating that the top left +corner of the text should appear at the position given. + +Further control over the appearance of the text is possible by setting +values for various Plot attributes, for example Colour, Font and Size. +Sub-strings within the displayed text can be given different appearances, +or turned into super-scripts or sub-scripts, by the inclusion of escape +sequences (see section~\secref{ss:escapes}) within the supplied text string. + +\subsection{\label{ss:plottingagrid}Plotting a Grid} + +The most comprehensive plotting function available is \htmlref{astGrid}{astGrid}, which +can be used to draw labelled coordinate axes and, optionally, to +overlay coordinate grids on the plotting area +(Figure~\ref{fig:gridplot}). The routine is straightforward to use, +simply requiring a pointer to the \htmlref{Plot}{Plot}: + +\small +\begin{terminalv} +astGrid( plot ); +\end{terminalv} +\normalsize + +It will draw both linear and curvilinear axes and grids, as required +by the particular Plot. The appearance of the output can be modified +in a wide variety of ways by setting various Plot attributes. +The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis +labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings +within these strings can be given different appearances, or turned into +super-scripts or sub-scripts, by the inclusion of escape sequences (see +section~\secref{ss:escapes}) within the Label attributes. + +\subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings} +Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be +plotted so that all characters in the string have the same font size, +colour, \emph{etc.}, specified by the appropriate attributes of the +Plot. However, it is possible to include \emph{escape sequences} within +the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be +used to change, colour, font, size, width, to introduce extra horizontal +space between characters, and to change the base line of characters (thus +allowing super-scripts and sub-scripts to be created). See the entry for +the Escape attribute in \appref{ss:attributedescriptions} for details. + +As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is +plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a +super-scripted exponent. The exponent text will be 70\% of the size of +normal text (as determined by the Size attribute), and its baseline will +be raised by 50\% of the height of a normal character. + +Such escape sequences can be used in the strings assigned to textual +attributes of the Plot (such as the axis Labels), and may also be +included in strings plotted using +\htmlref{astText}{astText}. + +The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option +which will cause escape sequences to be included when formatting +celestial positions so that super-script characters are used as +delimiters for the various fields (a super-script ``h'' for hours, ``m'' +for minutes, \emph{etc}). + +Note, the facility for interpreting escape sequences is only available if +the graphics wrapper functions which provide the interface to the +underlying graphics system support all the functions included in the +\verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be +extended by the addition of new functions before escape sequences can be +interpretted. + +\subsection{\label{ss:logaxes}Producing Logarithmic Axes} +In certain situations you may wish for one or both of the plotted axes to +be displayed logarithmically rather than linearly. For instance, you may +wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux +against frequency. In this case, you can cause the frequency axis to be drawn +logarithmically simply by setting the boolean LogPlot attribute for the +frequency axis to a non-zero value. This causes several things to happen: + +\begin{enumerate} + +\item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents +the underlying graphics world coordinate system) and the base Frame of +the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By +default, this mapping is linear on both axes, but setting LogPlot non-zero +for an axis causes the Mapping to be modified so that it is logarithmic +on the specified axis. This is only possible if the displayed section of +the axis does not include the value zero (otherwise the attempt to set +a new value for LogPlot is ignored,and it retains its default value of +zero). + +\item The major tick marks drawn as part of the annotated coordinate grid +are spaced logarithmically rather than linearly. That is, major axis +values are chosen so that there is a constant ratio between adjacent +tick mark values. This ratio is constrained to be a power of ten. The +minor tick marks are drawn at linearly distributed points between the +adjoining major tick values. Thus if a pair of adjacent major tick values +are drawn at axis values 10.0 and 100.0, minor ticks will be placed at +20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick +marks are drawn). + +\item If possible, numerical axis labels are shown as powers of ten. +This depends on the facilities implemented by the graphics wrapper +functions (see the next section). Extra functions were introduced to this +set of wrapper functions at AST V3.2 which enable super-scripts and +sub-scripts to be produced. Some older wrappers may not yet have +implemented these functiosn and this will result in axis labels being +drawn in usual scientific or decimal notation. + +\end{enumerate} + +Whilst the LogPlot attribute can be used to control all three of the above +facilities, it is possible to control them individually as well. The +LogTicks and LogLabel attributes control the behaviour specified in items +2 and 3 above, but the default values for these attributes depend on the +setting of the LogPlot attribute. This means that setting LogPlot +non-zero will swicth all three facilites on, so long as zero values have +not been assigned explicitly to LogTicks or LogLabel. + + +\subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package} +The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a +graphics device. Instead, it requires a set of functions to be provided +which it uses to draw the required graphics. These include functions +to draw a straight line, draw a text string, \emph{etc}. You may choose +to provide functions from your favorite graphics package, or you can even +write your own! To accomodate variations in the calling interfaces of +different graphics packages, AST defines a standard interface for these +routines. If this interface differs from the interface provided by your +graphics package (which in general it will), then you must write a set of +\emph{wrapper functions}, which provide the interface expected by AST but +which then call functions from your graphics package to provide the +required functionality. AST comes with wrapper functions suitable for +the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}). + +There are two ways of indicating which wrapper functions are to be used by +the Plot class: +\begin{enumerate} + +\item A file containing C functions with pre-defined names can be written +and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command. +(see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is +distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT +functions to implement the required functionality. This file can be used +as a template for writing your own. + +\item The +\htmlref{astGrfSet}{astGrfSet} +method of the Plot class can be used to ``register'' +wrapper functions at run-time. This allows an application to switch +between graphics systems if required. Graphics functions registered in +this way do not need to have the pre-defined names used in the link-time +method described above. + +\end{enumerate} + +For details of the interfaces of the wrapper routines, see +either the \texttt{grf\_pgplot.c} file included in the AST source +distribution, or the reference documentation for the astGrfSet method. + +\cleardoublepage +\section{Compiling and Linking Software that Uses AST} + +A small number of UNIX commands are provided by AST to assist with the +process of building software. A description of these can be found in +\appref{ss:commanddescriptions} and their use is discussed here. Note +that in order to access these commands, the appropriate directory +(normally ``/star/bin'') should be on your PATH.\footnote{If you have +not installed AST in the usual location, then substitute the +appropriate directory in place of ``/star'' wherever it occurs.} + +\subsection{\label{ss:accessingheaderfile}Accessing the ``ast.h'' Header File} + +The ``ast.h'' header file defines the external interface to the AST library, +including all constants, function prototypes, macros, \emph{etc.}. This file +should be located using the usual compiler options for finding C +include files, for instance: + +\small +\begin{terminalv} +cc prog.c -I/star/include -o prog +\end{terminalv} +\normalsize + +This is preferable to specifying the file's absolute name within your +software. + +\subsection{\label{ss:linking}Linking with AST Facilities} + +C programs which use AST facilities may be linked by including +execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command +line. Thus, to compile and link a program called ``prog'', the +following might be used: + +\small +\begin{terminalv} +cc prog.c -L/star/lib `ast_link` -o prog +\end{terminalv} +\normalsize + +Note the use of backward quote characters, which cause the +``ast\_link'' command to be executed and its result substituted into +the compiler command. An alternative is to save the output from +``ast\_link'' in (say) a shell variable and use this instead. You may +find this a little faster if you are building software repeatedly +during development. + +Programs which use AST can also be linked in a number of other ways, +depending on the facilities they require. In the example above, we +have used the default method which assumes that the program will not +be generating graphical output, so that no graphics libraries need be +linked. If you need other facilities, then various switches can be +applied to the ``ast\_link'' command in order to control the linking +process. + +For example, if you were producing graphical output using the PGPLOT +graphics package, you could link with the AST/PGPLOT interface by +using the ``$-$pgplot'' switch with ``ast\_link'', as +follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use +the Starlink version of PGPLOT which uses GKS to generate its output.} + +\small +\begin{terminalv} +cc prog.c -L/star/lib `ast_link -pgplot` -o prog +\end{terminalv} +\normalsize + +See the ``ast\_link'' command description in +\appref{ss:commanddescriptions} for details of the options available. + +\subsection{Building ADAM Applications that Use AST} + +Users of Starlink's \xref{ADAM}{sg4}{} programming environment +\latex{(SG/4)} on UNIX should use the +``\xref{alink}{sun144}{ADAM_link_scripts}'' command +(\xref{SUN/144}{sun144}{}) to compile and link applications and can +access the AST library by including execution of the command +``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows: + +\begin{small} +\begin{terminalv} +alink adamprog.c `ast_link_adam` +\end{terminalv} +\end{small} + +Note the use of backward quote characters. + +By default, AST error messages produced by applications built in this +way will be delivered \emph{via} the Starlink EMS Error Message +Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is +consistent with the \xref{\emph{inherited +status}}{sun104}{inherited_status} error handling normally used in +Starlink software. + +Switches may be given to the ``ast\_link\_adam'' command (in a similar +way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with +additional AST-related facilities, such as a graphics interface. See +the ``ast\_link\_adam'' command description in +\appref{ss:commanddescriptions} for details of the options available. + +\appendix +\cleardoublepage +\section{\label{ss:classhierarchy}The AST Class Hierarchy} +The following table shows the hierarchy of classes in the AST library. +For a description of each class, you should consult +\appref{ss:classdescriptions}. + +\small +\begin{terminalv} +Object - Base class for all AST Objects + Axis - Store axis information + SkyAxis - Store celestial axis information + Channel - Basic (textual) I/O channel + FitsChan - I/O Channel using FITS header cards + XmlChan - I/O Channel using XML + StcsChan - I/O Channel using IVOA STC-S descriptions + KeyMap - Store a set of key/value pairs + Table - Store a 2-dimensional table of values + Mapping - Inter-relate two coordinate systems + CmpMap - Compound Mapping + DssMap - Map points using Digitised Sky Survey plate solution + Frame - Coordinate system description + CmpFrame - Compound Frame + SpecFluxFrame - Observed value versus spectral position + FluxFrame - Observed value at a given fixed spectral position + FrameSet - Set of inter-related coordinate systems + Plot - Provide facilities for 2D graphical output + Plot3D - Provide facilities for 3D graphical output + Region - Specify areas within a coordinate system + Box - A box region with sides parallel to the axes of a Frame + Circle - A circular or spherical region within a Frame + CmpRegion - A combination of two regions within a single Frame + Ellipse - An elliptical region within a 2-dimensional Frame + Interval - Intervals on one or more axes of a Frame. + NullRegion - A boundless region within a Frame + PointList - A collection of points in a Frame + Polygon - A polygonal region within a 2-dimensional Frame + Prism - An extrusion of a Region into orthogonal dimensions + Stc - Represents an generic instance of an IVOA STC-X description + StcResourceProfile - Represents an an IVOA STC-X ResourceProfile + StcSearchLocation - Represents an an IVOA STC-X SearchLocation + StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation + StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation + SkyFrame - Celestial coordinate system description + SpecFrame - Spectral coordinate system description + DSBSpecFrame - Dual sideband spectral coordinate system description + TimeFrame - Time coordinate system description + GrismMap - Models the spectral dispersion produced by a grism + IntraMap - Map points using a private transformation function + LutMap - Transform 1-dimensional coordinates using a lookup table + MathMap - Transform coordinates using mathematical expressions + MatrixMap - Map positions by multiplying them by a matrix + NormMap - Normalise coordinates using a supplied Frame + PcdMap - Apply 2-dimensional pincushion/barrel distortion + PermMap - Coordinate permutation Mapping + PolyMap - General N-dimensional polynomial Mapping + RateMap - Calculates an element of a Mapping's Jacobian matrix + SelectorMap - Locates positions within a set of Regions + ShiftMap - Shifts each axis by a constant amount + SlaMap - Sequence of celestial coordinate conversions + SpecMap - Sequence of spectral coordinate conversions + SphMap - Map 3-d Cartesian to 2-d spherical coordinates + SwitchMap - Encapuslates a set of alternate Mappings + TimeMap - Sequence of time coordinate conversions + TranMap - Combine fwd. and inv. transformations from two Mappings + UnitMap - Unit (null) Mapping + UnitNormMap - Converts a vector to a unit vector plus length + WcsMap - Implement a FITS-WCS sky projection + WinMap - Match windows by scaling and shifting each axis + ZoomMap - Zoom coordinates about the origin +\end{terminalv} +\normalsize + +\cleardoublepage +\section{\label{ss:functiondescriptions}AST Function Descriptions} +\small +\sstroutine{ + astSet +}{ + Set attribute values for an Object +}{ + \sstdescription{ + This function assigns a set of attribute values to an \htmlref{Object}{Object}, + over-riding any previous values. The attributes and their new + values are specified via a character string, which should + contain a comma-separated list of the form: + + \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} + + where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value + to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual + representation of the value to be assigned. This value will be + interpreted according to the attribute\texttt{'} s data type. + + The string supplied may also contain \texttt{"} printf\texttt{"} -style format + specifiers, identified by \texttt{"} \%\texttt{"} signs in the usual way. If + present, these will be substituted by values supplied as + additional optional arguments (using the normal \texttt{"} printf\texttt{"} rules) + before the string is used. + } + \sstsynopsis{ + void astSet( AstObject $*$this, const char $*$settings, ... ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + settings + }{ + Pointer to a null-terminated character string containing a + comma-separated list of attribute settings in the form described + above. + } + \sstsubsection{ + ... + }{ + Optional additional arguments which supply values to be + substituted for any \texttt{"} printf\texttt{"} -style format specifiers that + appear in the \texttt{"} settings\texttt{"} string. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstexamples{ + \sstexamplesubsection{ + astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"} ); + }{ + Sets the Report attribute for Object \texttt{"} map\texttt{"} to the value 1 and + the Zoom attribute to 25.0. + } + \sstexamplesubsection{ + astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis ); + }{ + Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"} to a + suitable string, where the axis number is obtained from + \texttt{"} axis\texttt{"} , a variable of type int. + } + \sstexamplesubsection{ + astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring ); + }{ + Sets the Title attribute for Object \texttt{"} frame\texttt{"} to the contents of + the string \texttt{"} mystring\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + White space may also surround attribute values, where it will + generally be ignored (except for string-valued attributes where + it is significant and forms part of the value to be assigned). + + \sstitem + To include a literal comma in the value assigned to an attribute, + the whole attribute value should be enclosed in quotation markes. + Alternatively, you can use \texttt{"} \%s\texttt{"} format and supply the value as a + separate additional argument to astSet (or use the astSetC + function instead). + + \sstitem + The same procedure may be adopted if \texttt{"} \%\texttt{"} signs are to be included + and are not to be interpreted as format specifiers (alternatively, + the \texttt{"} printf\texttt{"} convention of writing \texttt{"} \%\%\texttt{"} may be used). + + \sstitem + An error will result if an attempt is made to set a value for + a read-only attribute. + } + } +} +\sstroutine{ + astAddColumn +}{ + Add a new column definition to a table +}{ + \sstdescription{ + Adds the definition of a new column to the supplied table. Initially, + the column is empty. Values may be added subsequently using the + methods of the \htmlref{KeyMap}{KeyMap} class. + } + \sstsynopsis{ + void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim, + int $*$dims, const char $*$unit ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Table}{Table}. + } + \sstsubsection{ + name + }{ + The column name. Trailing spaces are ignored (all other spaces + are significant). The supplied string is converted to upper case. + } + \sstsubsection{ + type + }{ + The data type associated with the column. See \texttt{"} Applicability:\texttt{"} + below. + } + \sstsubsection{ + ndim + }{ + The number of dimensions spanned by the values stored in a single + cell of the column. Zero if the column holds scalar values. + } + \sstsubsection{ + dims + }{ + An array holding the the lengths of each of the axes spanned by + the values stored in a single cell of the column. Ignored if the + column holds scalara values. + } + \sstsubsection{ + unit + }{ + A string specifying the units of the column. Supply a blank + string if the column is unitless. + } + } + \sstapplicability{ + \sstsubsection{ + Table + }{ + Tables can hold columns with any of the following data types - + AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for + short int), + AST\_\_BYTETYPE (for + unsigned bytes - i.e. unsigned chars), + AST\_\_DOUBLETYPE (for double + precision floating point), AST\_\_FLOATTYPE (for single + precision floating point), AST\_\_STRINGTYPE (for character string), + AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for + arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values + created by + \htmlref{astMapPutU}{astMapPutU}). + } + \sstsubsection{ + \htmlref{FitsTable}{FitsTable} + }{ + FitsTables can hold columns with any of the following data types - + AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for + short int), + AST\_\_BYTETYPE (for + unsigned bytes - i.e. unsigned chars), + AST\_\_DOUBLETYPE (for double + precision floating point), AST\_\_FLOATTYPE (for single + precision floating point), AST\_\_STRINGTYPE (for character string). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This + function + returns without action if a column already exists in the Table + with the supplied name and properties. However an error is + reported if any of the properties differ. + } + } +} +\sstroutine{ + astAddFrame +}{ + Add a Frame to a FrameSet to define a new coordinate system +}{ + \sstdescription{ + This function adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a + \htmlref{FrameSet}{FrameSet} so as to define a new coordinate system, derived from + one which already exists within the FrameSet. The new Frame then + becomes the FrameSet\texttt{'} s current Frame. + + This function + may also be used to merge two FrameSets, or to append extra axes + to every Frame in a FrameSet. + } + \sstsynopsis{ + void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map, + AstFrame $*$frame ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe + }{ + The index of the Frame within the FrameSet which describes + the coordinate system upon which the new one is to be based. + This value should lie in the range from 1 to the number of + Frames already in the FrameSet (as given by its \htmlref{Nframe}{Nframe} + attribute). As a special case, AST\_\_ALLFRAMES may be supplied, + in which case the axes defined by the supplied Frame are appended + to every Frame in the FrameSet (see the Notes section for details). + } + \sstsubsection{ + map + }{ + Pointer to a Mapping which describes how to convert + coordinates from the old coordinate system (described by the + Frame with index \texttt{"} iframe\texttt{"} ) into coordinates in the new + system. The Mapping\texttt{'} s forward transformation should perform + this conversion, and its inverse transformation should + convert in the opposite direction. The supplied Mapping is ignored + if parameter \texttt{"} iframe\texttt{"} is equal to AST\_\_ALLFRAMES. + } + \sstsubsection{ + frame + }{ + Pointer to a Frame that describes the new coordinate system. + Any class of Frame may be supplied (including Regions and + FrameSets). + + This function may also be used to merge two FrameSets by + supplying a pointer to a second FrameSet for this parameter + (see the Notes section for details). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Deep copies of the supplied + \texttt{"} mapping\texttt{"} and \texttt{"} frame\texttt{"} + objects are stored within the modified FrameSet. So any changes made + to the FrameSet after calling this method will have no effect on the + supplied Mapping and Frame objects. + + \sstitem + A value of AST\_\_BASE or AST\_\_CURRENT may be given for the + \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current + Frame respectively. + + \sstitem + This function sets the value of the \htmlref{Current}{Current} attribute for the + FrameSet so that the new Frame subsequently becomes the current + Frame. + + \sstitem + The number of input coordinate values accepted by the supplied + Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the + Frame identified by the \texttt{"} iframe\texttt{"} parameter. Similarly, the + number of output coordinate values generated by this Mapping + (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new + Frame. + + \sstitem + As a special case, if a pointer to a FrameSet is given for the + \texttt{"} frame\texttt{"} parameter, this is treated as a request to merge a pair of + FrameSets. This is done by appending all the new Frames (in the + \texttt{"} frame\texttt{"} FrameSet) to the original FrameSet, while preserving + their order and retaining all the inter-relationships + (i.e. Mappings) between them. The two sets of Frames are + inter-related within the merged FrameSet by using the Mapping + supplied. This should convert between the Frame identified by + the \texttt{"} iframe\texttt{"} parameter (in the original FrameSet) and the current + Frame of the \texttt{"} frame\texttt{"} FrameSet. This latter Frame becomes the + current Frame in the merged FrameSet. + + \sstitem + As another special case, if a value of AST\_\_ALLFRAMES is supplied + for parameter + \texttt{"} iframe\texttt{"} , + then the supplied Mapping is ignored, and the axes defined by the + supplied Frame are appended to each Frame in the FrameSet. In detail, + each Frame in the FrameSet is replaced by a \htmlref{CmpFrame}{CmpFrame} containing the + original Frame and the Frame specified by parameter + \texttt{"} frame\texttt{"} . + In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap} + containing the original Mapping and a \htmlref{UnitMap}{UnitMap} in parallel. The Nin and + Nout attributes of the UnitMap are set equal to the number of axes + in the supplied Frame. Each new CmpMap is simplified using + \htmlref{astSimplify}{astSimplify} + before being stored in the FrameSet. + } + } +} +\sstroutine{ + astAddParameter +}{ + Add a new global parameter definition to a table +}{ + \sstdescription{ + Adds the definition of a new global parameter to the supplied + table. Note, this does not store a value for the parameter. To get + or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class + should be used, using the name of the parameter as the key. + } + \sstsynopsis{ + void astAddParameter( AstTable $*$this, const char $*$name ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Table}{Table}. + } + \sstsubsection{ + name + }{ + The parameter name. Trailing spaces are ignored (all other spaces + are significant). The supplied string is converted to upper case. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Unlike columns, the definition of a parameter does not specify its type, + size or dimensionality. + } + } +} +\sstroutine{ + astAddVariant +}{ + Store a new variant Mapping for the current Frame in a FrameSet +}{ + \sstdescription{ + This function + allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame} + in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"} attribute for more details. It can + also be used to rename the currently selected variant Mapping. + } + \sstsynopsis{ + void astAddVariant( AstFrameSet $*$this, AstMapping $*$map, + const char $*$name, int $*$status ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + map + }{ + Pointer to a Mapping which describes how to convert + coordinates from the current Frame to the new variant of the + current Frame. If + NULL + is supplied, then the name associated with the currently selected + variant of the current Frame is set to the value supplied for + \texttt{"} name\texttt{"} , but no new variant is added. + } + \sstsubsection{ + name + }{ + The name to associate with the new variant Mapping (or the currently + selected variant Mapping if + \texttt{"} map\texttt{"} is NULL). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The newly added Variant becomes the current variant on exit (this is + equivalent to setting the Variant attribute to the value supplied for + \texttt{"} name). + + \sstitem + An error is reported if a variant with the supplied name already + exists in the current Frame. + + \sstitem + An error is reported if the current Frame is a mirror for the + variant Mappings in another Frame. This is only the case if the + \htmlref{astMirrorVariants}{astMirrorVariants} function + has been called to make the current Frame act as a mirror. + } + } +} +\sstroutine{ + astAngle +}{ + Calculate the angle subtended by two points at a third point +}{ + \sstdescription{ + This function + finds the angle at point B between the line joining points A and B, + and the line joining points C and B. These lines will in fact be + geodesic curves appropriate to the \htmlref{Frame}{Frame} in use. For instance, in + \htmlref{SkyFrame}{SkyFrame}, they will be great circles. + } + \sstsynopsis{ + double astAngle( AstFrame $*$this, const double a[], const double b[], + const double c[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + a + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. + } + \sstsubsection{ + b + }{ + An array of double, with one element for each Frame axis + (Naxes attribute) containing the coordinates of the second point. + } + \sstsubsection{ + c + }{ + An array of double, with one element for each Frame axis + (Naxes attribute) containing the coordinates of the third point. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAngle + }{ + The angle in radians, from the line AB to the line CB. If the + Frame is 2-dimensional, it will be in the range \$$\backslash$pm $\backslash$pi\$, + and positive rotation is in the same sense as rotation from + the positive direction of axis 2 to the positive direction of + axis 1. If the Frame has more than 2 axes, a positive value will + always be returned in the range zero to \$$\backslash$pi\$. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of AST\_\_BAD will also be returned if points A and B are + co-incident, or if points B and C are co-incident. + + \sstitem + A value of AST\_\_BAD will also be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astAnnul +}{ + Annul a pointer to an Object +}{ + \sstdescription{ + This function annuls a pointer to an \htmlref{Object}{Object} so that it is no + longer recognised as a valid pointer by the AST library. Any + resources associated with the pointer are released and made + available for re-use. + + This function also decrements the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute by + one. If this attribute reaches zero (which happens when the last + pointer to the Object is annulled), then the Object is deleted. + } + \sstsynopsis{ + AstObject $*$astAnnul( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + The Object pointer to be annulled. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAnnul() + }{ + A null Object pointer (AST\_\_NULL) is always returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function will attempt to annul the pointer even if the + Object is not currently locked by the calling thread (see \htmlref{astLock}{astLock}). + + \sstitem + This function attempts to execute even if the AST error + status is set + on entry, although no further error report will be + made if it subsequently fails under these circumstances. In + particular, it will fail if the pointer suppled is not valid, + but this will only be reported if the error status is clear on + entry. + } + } +} +\sstroutine{ + astAxAngle +}{ + Returns the angle from an axis, to a line through two points +}{ + \sstdescription{ + This function + finds the angle, as seen from point A, between the positive + direction of a specified axis, and the geodesic curve joining point + A to point B. + } + \sstsynopsis{ + double astAxAngle( AstFrame $*$this, const double a[], const double b[], int axis ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Frame}{Frame}. + } + \sstsubsection{ + a + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. + } + \sstsubsection{ + b + }{ + An array of double, with one element for each Frame axis + (Naxes attribute) containing the coordinates of the second point. + } + \sstsubsection{ + axis + }{ + The number of the Frame axis from which the angle is to be + measured (axis numbering starts at 1 for the first axis). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAxAngle + }{ + The angle in radians, from the positive direction of the + specified axis, to the line AB. If the Frame is 2-dimensional, + it will be in the range [-PI/2,$+$PI/2], and positive rotation is in + the same sense as rotation from the positive direction of axis 2 + to the positive direction of axis 1. If the Frame has more than 2 + axes, a positive value will always be returned in the range zero + to PI. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The geodesic curve used by this function is the path of + shortest distance between two points, as defined by the + \htmlref{astDistance}{astDistance} function. + + \sstitem + This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) + if any of the input coordinates has this value, or if the require + position angle is undefined. + } + } +} +\sstroutine{ + astAxDistance +}{ + Find the distance between two axis values +}{ + \sstdescription{ + This function returns a signed value representing the axis increment + from axis value v1 to axis value v2. + + For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the + difference between the two axis values. But for other derived classes + of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. + } + \sstsynopsis{ + double astAxDistance( AstFrame $*$this, int axis, double v1, double v2 ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + axis + }{ + The index of the axis to which the supplied values refer. The + first axis has index 1. + } + \sstsubsection{ + v1 + }{ + The first axis value. + } + \sstsubsection{ + v2 + }{ + The second axis value. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAxDistance + }{ + The distance from the first to the second axis value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if + any of the input values has this value. + + \sstitem + A \texttt{"} bad\texttt{"} value will also be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astAxNorm +}{ + Normalise an array of axis values +}{ + \sstdescription{ + This function + modifies a supplied array of axis values so that they are normalised + in the manner indicated by + parameter \texttt{"} oper\texttt{"} . + + No normalisation is possible for a simple \htmlref{Frame}{Frame} and so the supplied + values are returned unchanged. However, this may not be the case for + specialised sub-classes of Frame. For instance, a \htmlref{SkyFrame}{SkyFrame} has a + discontinuity at zero longitude and so a longitude value can be + expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the + \texttt{"} Applicability:\texttt{"} section below for details. + } + \sstsynopsis{ + void astAxNorm( AstFrame $*$this, int axis, int oper, int nval, + double $*$values, int $*$status ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + axis + }{ + The index of the axis to which the supplied values refer. The + first axis has index 1. + } + \sstsubsection{ + oper + }{ + Indicates the type of normalisation to be applied. If zero is + supplied, the normalisation will be the same as that performed by + function \htmlref{astNorm}{astNorm}. + If 1 is supplied, the normalisation will be chosen automatically + so that the resulting list has the smallest range. + } + \sstsubsection{ + nval + }{ + The number of points in the values array. + } + \sstsubsection{ + values + }{ + On entry, the axis values to be normalised. Modified on exit to + hold the normalised values. + } + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + If \texttt{"} oper\texttt{"} + is 0, longitude values are returned in the range [0,2$*$PI]. + If \texttt{"} oper\texttt{"} + is 1, longitude values are returned in either the range + [0,2$*$PI] or [-PI,PI]. The choice is made so that that the + resulting list has the smallest range. Latitude values are + always returned in the range [-PI,PI]. + } + \sstsubsection{ + All other classes of Frame + }{ + The supplied axis values are returned unchanged. + } + } +} +\sstroutine{ + astAxOffset +}{ + Add an increment onto a supplied axis value +}{ + \sstdescription{ + This function returns an axis value formed by adding a signed axis + increment onto a supplied axis value. + + For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the + sum of the two supplied values. But for other derived classes + of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case. + } + \sstsynopsis{ + double astAxOffset( AstFrame $*$this, int axis, double v1, double dist ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + axis + }{ + The index of the axis to which the supplied values refer. The + first axis has index 1. + } + \sstsubsection{ + v1 + }{ + The original axis value. + } + \sstsubsection{ + dist + }{ + The axis increment to add to the original axis value. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAxOffset + }{ + The incremented axis value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if + any of the input values has this value. + + \sstitem + A \texttt{"} bad\texttt{"} value will also be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astBBuf +}{ + Begin a new graphical buffering context +}{ + \sstdescription{ + This function + starts a new graphics buffering context. A matching call to the + function \htmlref{astEBuf}{astEBuf} + should be used to end the context. + } + \sstsynopsis{ + void astBBuf( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Plot}{Plot}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The nature of the buffering is determined by the underlying + graphics system (as defined by the current grf module). Each call + to this function + to this function + simply invokes the astGBBuf function in the grf module. + } + } +} +\sstroutine{ + astBegin +}{ + Begin a new AST context +}{ + \sstdescription{ + This macro invokes a function to begin a new AST context. + Any \htmlref{Object}{Object} pointers + created within this context will be annulled when it is later + ended using \htmlref{astEnd}{astEnd} (just as if \htmlref{astAnnul}{astAnnul} had been invoked), + unless they have first been exported using \htmlref{astExport}{astExport} or rendered + exempt using \htmlref{astExempt}{astExempt}. If + annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to + fall to zero (which happens when the last pointer to it is + annulled), then the Object will be deleted. + } + \sstsynopsis{ + void astBegin + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This macro applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + astBegin attempts to execute even if the AST error status + is set on entry. + + \sstitem + Contexts delimited by astBegin and astEnd may be nested to any + depth. + } + } +} +\sstroutine{ + astBorder +}{ + Draw a border around valid regions of a Plot +}{ + \sstdescription{ + This function draws a (line) border around regions of the + plotting area of a \htmlref{Plot}{Plot} which correspond to valid, unclipped + physical coordinates. For example, when plotting using an + all-sky map projection, this function could be used to draw the + boundary of the celestial sphere when it is projected on to the + plotting surface. + + If the entire plotting area contains valid, unclipped physical + coordinates, then the boundary will just be a rectangular box + around the edges of the plotting area. + + If the Plot is a \htmlref{Plot3D}{Plot3D}, this method is applied individually to + each of the three 2D Plots encapsulated within the Plot3D (each of + these Plots corresponds to a single 2D plane in the 3D graphics + system). In addition, if the entire plotting volume has valid + coordinates in the 3D current \htmlref{Frame}{Frame} of the Plot3D, then additional + lines are drawn along the edges of the 3D plotting volume so that + the entire plotting volume is enclosed within a cuboid grid. + } + \sstsynopsis{ + int astBorder( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astBorder() + }{ + Zero is returned if the plotting space is completely filled by + valid, unclipped physical coordinates (so that only a + rectangular box was drawn around the edge). Otherwise, one is + returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + + \sstitem + An error results if either the current Frame or the base Frame + of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. + + \sstitem + An error also results if the transformation between the base + and current Frames of the Plot is not defined (i.e. the Plot\texttt{'} s + \htmlref{TranForward}{TranForward} attribute is zero). + } + } +} +\sstroutine{ + astBoundingBox +}{ + Return a bounding box for previously drawn graphics +}{ + \sstdescription{ + This function returns the bounds of a box which just encompasess the + graphics produced by the previous call to any of the \htmlref{Plot}{Plot} methods + which produce graphical output. If no such previous call has yet + been made, or if the call failed for any reason, then the bounding box + returned by this function is undefined. + } + \sstsynopsis{ + void astBoundingBox( AstPlot $*$this, float lbnd[2], float ubnd[2] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + lbnd + }{ + A two element array in which is returned the lower limits of the + bounding box on each of the two axes of the graphics coordinate + system (the base \htmlref{Frame}{Frame} of the Plot). + } + \sstsubsection{ + ubnd + }{ + A two element array in which is returned the upper limits of the + bounding box on each of the two axes of the graphics coordinate + system (the base Frame of the Plot). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error results if the base Frame of the Plot is not + 2-dimensional. + } + } +} +\sstroutine{ + astBox +}{ + Create a Box +}{ + \sstdescription{ + This function creates a new \htmlref{Box}{Box} and optionally initialises its + attributes. + + The Box class implements a \htmlref{Region}{Region} which represents a box with sides + parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given + range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the + only real difference being that the Interval class allows some axis + limits to be unspecified. Note, a Box will only look like a box if + the Frame geometry is approximately flat. For instance, a Box centred + close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box + (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a + pole). + } + \sstsynopsis{ + AstBox $*$astBox( AstFrame $*$frame, int form, const double point1[], + const double point2[], AstRegion $*$unc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. A deep + copy is taken of the supplied Frame. This means that any + subsequent changes made to the Frame using the supplied pointer + will have no effect the Region. + } + \sstsubsection{ + form + }{ + Indicates how the box is described by the remaining parameters. + A value of zero indicates that the box is specified by a centre + position and a corner position. A value of one indicates that the + box is specified by a two opposite corner positions. + } + \sstsubsection{ + point1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). If + \texttt{"} form\texttt{"} + is zero, this array should contain the coordinates at the centre of + the box. + If \texttt{"} form\texttt{"} + is one, it should contain the coordinates at the corner of the box + which is diagonally opposite the corner specified by + \texttt{"} point2\texttt{"} . + } + \sstsubsection{ + point2 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute) containing the coordinates at any corner of the + box. + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with the boundary of the Box being created. + The uncertainty in any point on the boundary of the Box is found by + shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at + the boundary point being considered. The area covered by the + shifted uncertainty Region then represents the uncertainty in the + boundary position. The uncertainty is assumed to be the same for + all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Box. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the Box being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Box. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astBox() + }{ + A pointer to the new Box. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astChannel +}{ + Create a Channel +}{ + \sstdescription{ + This function creates a new \htmlref{Channel}{Channel} and optionally initialises + its attributes. + + A Channel implements low-level input/output for the AST library. + Writing an \htmlref{Object}{Object} to a Channel (using \htmlref{astWrite}{astWrite}) will generate a + textual representation of that Object, and reading from a + Channel (using \htmlref{astRead}{astRead}) will create a new Object from its + textual representation. + + Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting text. By default, however, + a Channel will read from standard input and write to standard + output. Alternatively, a Channel can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + } + \sstsynopsis{ + AstChannel $*$astChannel( const char $*$($*$ source)( void ), + void ($*$ sink)( const char $*$ ), + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + source + }{ + Pointer to a source function that takes no arguments and + returns a pointer to a null-terminated string. If no value + has been set for the SourceFile attribute, this function + will be used by the Channel to obtain lines of input text. On + each invocation, it should return a pointer to the next input + line read from some external data store, and a NULL pointer + when there are no more lines to read. + + If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile + attribute, the Channel will read from standard input instead. + } + \sstsubsection{ + sink + }{ + Pointer to a sink function that takes a pointer to a + null-terminated string as an argument and returns void. + If no value has been set for the SinkFile attribute, this + function will be used by the Channel to deliver lines of + output text. On each invocation, it should deliver the + contents of the string supplied to some external data store. + + If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile + attribute, the Channel will write to standard output instead. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Channel. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChannel() + }{ + A pointer to the new Channel. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Application code can pass arbitrary data (such as file + descriptors, etc) to source and sink functions using the + \htmlref{astPutChannelData}{astPutChannelData} function. The source or sink function should use + the \htmlref{astChannelData}{astChannelData} macro to retrieve this data. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astChannelData +}{ + Return a pointer to user-supplied data stored with a Channel +}{ + \sstdescription{ + This macro is intended to be used within the source or sink + functions associated with a \htmlref{Channel}{Channel}. It returns any pointer + previously stored in the Channel (that is, the Channel that has + invoked the source or sink function) using \htmlref{astPutChannelData}{astPutChannelData}. + + This mechanism is a thread-safe alternative to passing file + descriptors, etc, via static global variables. + } + \sstsynopsis{ + void $*$astChannelData + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + This macro applies to all Channels. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChannelData + }{ + The pointer previously stored with the Channel using + astPutChannelData. A NULL pointer will be returned if no such + pointer has been stored with the Channel. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This routine is not available in the Fortran 77 interface to + the AST library. + } + } +} +\sstroutine{ + astCircle +}{ + Create a Circle +}{ + \sstdescription{ + This function creates a new \htmlref{Circle}{Circle} and optionally initialises its + attributes. + + A Circle is a \htmlref{Region}{Region} which represents a circle or sphere within the + supplied \htmlref{Frame}{Frame}. + } + \sstsynopsis{ + AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[], + const double point[], AstRegion $*$unc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. A deep + copy is taken of the supplied Frame. This means that any + subsequent changes made to the Frame using the supplied pointer + will have no effect the Region. + } + \sstsubsection{ + form + }{ + Indicates how the circle is described by the remaining parameters. + A value of zero indicates that the circle is specified by a + centre position and a position on the circumference. A value of one + indicates that the circle is specified by a centre position and a + scalar radius. + } + \sstsubsection{ + centre + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of + the circle or sphere. + } + \sstsubsection{ + point + }{ + If \texttt{"} form\texttt{"} + is zero, then this array should have one element for each Frame + axis (Naxes attribute), and should be supplied holding the + coordinates at a point on the circumference of the circle or sphere. + If \texttt{"} form\texttt{"} + is one, then this array should have one element only which should + be supplied holding the scalar radius of the circle or sphere, + as a geodesic distance within the Frame. + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with the boundary of the Circle being created. + The uncertainty in any point on the boundary of the Circle is found by + shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at + the boundary point being considered. The area covered by the + shifted uncertainty Region then represents the uncertainty in the + boundary position. The uncertainty is assumed to be the same for + all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. \htmlref{Box}{Box}, Circle, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Circle. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the Circle being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Circle. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCircle() + }{ + A pointer to the new Circle. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astCirclePars +}{ + Returns the geometric parameters of an Circle +}{ + \sstdescription{ + This function + returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}. + } + \sstsynopsis{ + void astCirclePars( AstCircle $*$this, double $*$centre, double $*$radius, + double $*$p1 ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Region}{Region}. + } + \sstsubsection{ + centre + }{ + Pointer to an array + in which to return the coordinates of the Circle centre. + The length of this array should be no less than the number of + axes in the associated coordinate system. + } + \sstsubsection{ + radius + }{ + Returned holding the radius of the Circle, as an geodesic + distance in the associated coordinate system. + } + \sstsubsection{ + p1 + }{ + Pointer to an array + in which to return the coordinates of a point on the + circumference of the Circle. The length of this array should be + no less than the number of axes in the associated coordinate system. + A NULL pointer can be supplied if the circumference position is + not needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the coordinate system represented by the Circle has been + changed since it was first created, the returned parameters refer + to the new (changed) coordinate system, rather than the original + coordinate system. Note however that if the transformation from + original to new coordinate system is non-linear, the shape + represented by the supplied Circle object may not be an accurate + circle. + } + } +} +\sstroutine{ + astClear +}{ + Clear attribute values for an Object +}{ + \sstdescription{ + This function clears the values of a specified set of attributes + for an \htmlref{Object}{Object}. Clearing an attribute cancels any value that has + previously been explicitly set for it, so that the standard + default attribute value will subsequently be used instead. This + also causes the \htmlref{astTest}{astTest} function to return the value zero for + the attribute, indicating that no value has been set. + } + \sstsynopsis{ + void astClear( AstObject $*$this, const char $*$attrib ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + attrib + }{ + Pointer to a null-terminated character string containing a + comma-separated list of the names of the attributes to be cleared. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + It does no harm to clear an attribute whose value has not been + set. + + \sstitem + An error will result if an attempt is made to clear the value + of a read-only attribute. + } + } +} +\sstroutine{ + astClearStatus +}{ + Clear the AST error status +}{ + \sstdescription{ + This macro resets the AST error status to an OK value, + indicating that an error condition (if any) has been cleared. + } + \sstsynopsis{ + void astClearStatus + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the AST error status is set to an error value (after an + error), most AST functions will not execute and will simply + return without action. Using astClearStatus will restore normal + behaviour. + } + } +} +\sstroutine{ + astClip +}{ + Set up or remove clipping for a Plot +}{ + \sstdescription{ + This function defines regions of a \htmlref{Plot}{Plot} which are to be clipped. + Any subsequent graphical output created using the Plot will then + be visible only within the unclipped regions of the plotting + area. See also the \htmlref{Clip}{Clip} attribute. + } + \sstsynopsis{ + void astClip( AstPlot $*$this, int iframe, const double lbnd[], + const double ubnd[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + iframe + }{ + The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping + limits supplied in \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} (below) refer. Clipping + may be applied to any of the coordinate systems associated + with a Plot (as defined by the Frames it contains), so this + index may take any value from 1 to the number of Frames in + the Plot (\htmlref{Nframe}{Nframe} attribute). In addition, the values + AST\_\_BASE and AST\_\_CURRENT may be used to specify the base + and current Frames respectively. + + For example, a value of AST\_\_CURRENT causes clipping to be + performed in physical coordinates, while a value of AST\_\_BASE + would clip in graphical coordinates. Clipping may also be + removed completely by giving a value of AST\_\_NOFRAME. In this + case any clipping bounds supplied (below) are ignored. + } + \sstsubsection{ + lbnd + }{ + An array with one element for each axis of the clipping Frame + (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the + lower bound, on each axis, of the region which is to remain + visible (unclipped). + } + \sstsubsection{ + ubnd + }{ + An array with one element for each axis of the clipping Frame + (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the + upper bound, on each axis, of the region which is to remain + visible (unclipped). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Only one clipping Frame may be active at a time. This function + will deactivate any previously-established clipping Frame before + setting up new clipping limits. + + \sstitem + The clipping produced by this function is in addition to that + specified by the Clip attribute which occurs at the edges of the + plotting area + established when the Plot is created (see \htmlref{astPlot}{astPlot}). The + underlying graphics system may also impose further clipping. + + \sstitem + When testing a graphical position for clipping, it is first + transformed into the clipping Frame. The resulting coordinate on + each axis is then checked against the clipping limits (given by + \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} ). By default, a position is clipped if any + coordinate lies outside these limits. However, if a non-zero + value is assigned to the Plot\texttt{'} s \htmlref{ClipOp}{ClipOp} attribute, then a + position is only clipped if the coordinates on all axes lie + outside their clipping limits. + + \sstitem + If the lower clipping limit exceeds the upper limit for any + axis, then the sense of clipping for that axis is reversed (so + that coordinate values lying between the limits are clipped + instead of those lying outside the limits). To produce a \texttt{"} hole\texttt{"} + in a coordinate space (that is, an internal region where nothing + is plotted), you should supply all the bounds in reversed order, + and set the ClipOp attribute for the Plot to a non-zero value. + + \sstitem + Either clipping limit may be set to the value AST\_\_BAD, which + is equivalent to setting it to infinity (or minus infinity for a + lower bound) so that it is not used. + + \sstitem + If a graphical position results in any bad coordinate values + (AST\_\_BAD) when transformed into the clipping Frame, then it is + treated (for the purposes of producing graphical output) as if + it were clipped. + + \sstitem + When a Plot is used as a \htmlref{Mapping}{Mapping} to transform points + (e.g. using \htmlref{astTran2}{astTran2}), any clipped output points are assigned + coordinate values of AST\_\_BAD. + + \sstitem + An error results if the base Frame of the Plot is not + 2-dimensional. + } + } +} +\sstroutine{ + astClone +}{ + Clone (duplicate) an Object pointer +}{ + \sstdescription{ + This function returns a duplicate pointer to an existing + \htmlref{Object}{Object}. It also increments the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to + keep track of how many pointers have been issued. + + Note that this function is NOT equivalent to an assignment + statement, as in general the two pointers will not have the same + value. + } + \sstsynopsis{ + AstObject $*$astClone( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Original pointer to the Object. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astClone() + }{ + A duplicate pointer to the same Object. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astCmpFrame +}{ + Create a CmpFrame +}{ + \sstdescription{ + This function creates a new \htmlref{CmpFrame}{CmpFrame} and optionally initialises + its attributes. + + A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames + (of any class) to be merged together to form a more complex + Frame. The axes of the two component Frames then appear together + in the resulting CmpFrame (those of the first Frame, followed by + those of the second Frame). + + Since a CmpFrame is itself a Frame, it can be used as a + component in forming further CmpFrames. Frames of arbitrary + complexity may be built from simple individual Frames in this + way. + + Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a + Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, + but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} + (a sub-class of Frame), then the CmpFrame will use the Region as a + Mapping when transforming values for axes described by the Region. + Thus input axis values corresponding to positions which are outside the + Region will result in bad output axis values. + } + \sstsynopsis{ + AstCmpFrame $*$astCmpFrame( AstFrame $*$frame1, AstFrame $*$frame2, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame1 + }{ + Pointer to the first component Frame. + } + \sstsubsection{ + frame2 + }{ + Pointer to the second component Frame. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new CmpFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCmpFrame() + }{ + A pointer to the new CmpFrame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astCmpMap +}{ + Create a CmpMap +}{ + \sstdescription{ + This function creates a new \htmlref{CmpMap}{CmpMap} and optionally initialises + its attributes. + + A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component + Mappings (of any class) to be connected together to form a more + complex Mapping. This connection may either be \texttt{"} in series\texttt{"} + (where the first Mapping is used to transform the coordinates of + each point and the second mapping is then applied to the + result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the + earlier coordinates for each point and the second Mapping + simultaneously transforms the later coordinates). + + Since a CmpMap is itself a Mapping, it can be used as a + component in forming further CmpMaps. Mappings of arbitrary + complexity may be built from simple individual Mappings in this + way. + } + \sstsynopsis{ + AstCmpMap $*$astCmpMap( AstMapping $*$map1, AstMapping $*$map2, int series, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + map1 + }{ + Pointer to the first component Mapping. + } + \sstsubsection{ + map2 + }{ + Pointer to the second component Mapping. + } + \sstsubsection{ + series + }{ + If a non-zero value is given for this parameter, the two + component Mappings will be connected in series. A zero + value requests that they are connected in parallel. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new CmpMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCmpMap() + }{ + A pointer to the new CmpMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the component Mappings are connected in series, then using + the resulting CmpMap to transform coordinates will cause the + first Mapping to be applied, followed by the second Mapping. If + the inverse CmpMap transformation is requested, the two + component Mappings will be applied in both the reverse order and + the reverse direction. + + \sstitem + When connecting two component Mappings in series, the number + of output coordinates generated by the first Mapping (its \htmlref{Nout}{Nout} + attribute) must equal the number of input coordinates accepted + by the second Mapping (its \htmlref{Nin}{Nin} attribute). + + \sstitem + If the component Mappings of a CmpMap are connected in + parallel, then the first Mapping will be used to transform the + earlier input coordinates for each point (and to produce the + earlier output coordinates) and the second Mapping will be used + simultaneously to transform the remaining input coordinates (to + produce the remaining output coordinates for each point). If the + inverse transformation is requested, each Mapping will still be + applied to the same coordinates, but in the reverse direction. + + \sstitem + When connecting two component Mappings in parallel, there is + no restriction on the number of input and output coordinates for + each Mapping. + + \sstitem + Note that the component Mappings supplied are not copied by + astCmpMap (the new CmpMap simply retains a reference to + them). They may continue to be used for other purposes, but + should not be deleted. If a CmpMap containing a copy of its + component Mappings is required, then a copy of the CmpMap should + be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astCmpRegion +}{ + Create a CmpRegion +}{ + \sstdescription{ + This function creates a new \htmlref{CmpRegion}{CmpRegion} and optionally initialises + its attributes. + + A CmpRegion is a \htmlref{Region}{Region} which allows two component + Regions (of any class) to be combined to form a more complex + Region. This combination may be performed a boolean AND, OR + or XOR (exclusive OR) operator. If the AND operator is + used, then a position is inside the CmpRegion only if it is + inside both of its two component Regions. If the OR operator is + used, then a position is inside the CmpRegion if it is inside + either (or both) of its two component Regions. If the XOR operator + is used, then a position is inside the CmpRegion if it is inside + one but not both of its two component Regions. Other operators can + be formed by negating one or both component Regions before using + them to construct a new CmpRegion. + + The two component Region need not refer to the same coordinate + \htmlref{Frame}{Frame}, but it must be possible for the + \htmlref{astConvert}{astConvert} + function to determine a \htmlref{Mapping}{Mapping} between them (an error will be + reported otherwise when the CmpRegion is created). For instance, + a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} + with a Region defined within a Galactic SkyFrame. This is + acceptable because the SkyFrame class knows how to convert between + these two systems, and consequently the + astConvert + function will also be able to convert between them. In such cases, + the second component Region will be mapped into the coordinate Frame + of the first component Region, and the Frame represented by the + CmpRegion as a whole will be the Frame of the first component Region. + + Since a CmpRegion is itself a Region, it can be used as a + component in forming further CmpRegions. Regions of arbitrary + complexity may be built from simple individual Regions in this + way. + } + \sstsynopsis{ + AstCmpRegion $*$astCmpRegion( AstRegion $*$region1, AstRegion $*$region2, + int oper, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region1 + }{ + Pointer to the first component Region. + } + \sstsubsection{ + region2 + }{ + Pointer to the second component Region. This Region will be + transformed into the coordinate Frame of the first region before + use. An error will be reported if this is not possible. + } + \sstsubsection{ + oper + }{ + The boolean operator with which to combine the two Regions. This + must be one of the symbolic constants AST\_\_AND, AST\_\_OR or AST\_\_XOR. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new CmpRegion. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCmpRegion() + }{ + A pointer to the new CmpRegion. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If one of the supplied Regions has an associated uncertainty, + that uncertainty will also be used for the returned CmpRegion. + If both supplied Regions have associated uncertainties, the + uncertainty associated with the first Region will be used for the + returned CmpRegion. + + \sstitem + Deep copies are taken of the supplied Regions. This means that + any subsequent changes made to the component Regions using the + supplied pointers will have no effect on the CmpRegion. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astColumnName +}{ + Get the name of the column at a given index within the Table +}{ + \sstdescription{ + This function returns a string holding the name of the column with + the given index within the \htmlref{Table}{Table}. + + This function is intended primarily as a means of iterating round all + the columns in a Table. For this purpose, the number of columns in + the Table is given by the \htmlref{Ncolumn}{Ncolumn} attribute of the Table. This function + could then be called in a loop, with the index value going from + zero to one less than Ncolumn. + + Note, the index associated with a column decreases monotonically with + the age of the column: the oldest Column in the Table will have index + one, and the Column added most recently to the Table will have the + largest index. + } + \sstsynopsis{ + const char $*$astColumnName( AstTable $*$this, int index ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + index + }{ + The index into the list of columns. The first column has index + one, and the last has index \texttt{"} Ncolumn\texttt{"} . + } + } + \sstreturnedvalue{ + \sstsubsection{ + astColumnName() + }{ + A pointer to a null-terminated string containing the + upper case column name. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned pointer is guaranteed to remain valid and the + string to which it points will not be over-written for a total + of 50 successive invocations of this function. After this, the + memory containing the string may be re-used, so a copy of the + string should be made if it is needed for longer than this. + + \sstitem + A NULL pointer will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astColumnNull +}{ + Get or set the null value for an integer column of a FITS table +}{ + \sstdescription{ + This function allows a null value to be stored with a named + integer-valued column in a \htmlref{FitsTable}{FitsTable}. The supplied null value is + assigned to the TNULLn keyword in the FITS header associated with + the FitsTable. A value in the named column is then considered to be + null if 1) it equals the null value supplied to this function, or + 2) no value has yet been stored in the cell. + + As well as setting a new null value, this function also returns the + previous null value. If no null value has been set previously, a + default value will be returned. This default will be an integer + value that does not currently occur anywhere within the named column. + If no such value can be found, what happens depends on whether the + column contains any cells in which no values have yet been stored. + If so, an error will be reported. Otherwise (i.e. if there are no + null values in the column), an arbitrary value of zero will be + returned as the function value, and no TNULLn keyword will be + stored in the FITS header. + + A flag is returned indicating if the returned null value was set + explicitly by a previous call to this function, or is a default + value. + + A second flag is returned indicating if the named column contains + any null values (i.e. values equal to the supplied null value, or + cells to which no value has yet been assigned). + } + \sstsynopsis{ + int astColumnNull( AstFitsTable $*$this, const char $*$column, int set, + int newval, int $*$wasset, int $*$hasnull ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Table}{Table}. + } + \sstsubsection{ + column + }{ + The character string holding the name of the column. Trailing + spaces are ignored. + } + \sstsubsection{ + set + }{ + If non-zero, the value supplied for parameter \texttt{"} newval\texttt{"} + will be stored as the current null value, replacing any value + set by a previous call to this function. + If zero, the value supplied for parameter \texttt{"} newval\texttt{"} + is ignored and the current null value is left unchanged. + } + \sstsubsection{ + newval + }{ + The new null value to use. Ignored if + \texttt{"} set\texttt{"} is zero. + An error will be reported if the supplied value is outside the + range of values that can be stored in the integer data type + associated with the column. + } + \sstsubsection{ + wasset + }{ + Pointer to an int that will be returned non-zero + if the returned null value was set previously via an + earlier invocation of this function. + Zero + is returned otherwise. If the named column does not exist, or an + error occurs, a value of + zero is returned. + } + \sstsubsection{ + hasnull + }{ + Pointer to an int that will be returned non-zero + if and only if the named column currently contains any values + equal to the null value on exit (i.e. + \texttt{"} newval\texttt{"} if \texttt{"} set\texttt{"} is non-zero, + or the returned function value otherwise), or contains any empty + cells. If the named column does not exist, or an error occurs, a + value of + zero is returned. + If a NULL pointer is supplied for \texttt{"} hasnull\texttt{"} , no check on the + presence of null values will be performed. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astColumnNull() + }{ + The null value that was in use on entry to this function. If a + null value has been set by a previous invocation of this + function, it will be returned. Otherwise, if + \texttt{"} set\texttt{"} is non-zero, the supplied \texttt{"} newval\texttt{"} + value is returned. Otherwise, a default value is chosen (if + possible) that does not currently occur in the named column. If + all available values are in use in the column, an error is + reported if and only if the column contains any empty cells. + Otherwise, a value of zero is returned. A value of zero is also + returned if the named column does not exist, or an error occurs. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The FITS binary table definition allows only integer-valued + columns to have an associated null value. This routine will return + without action if the column is not integer-valued. + } + } +} +\sstroutine{ + astColumnShape +}{ + Returns the shape of the values in a named column +}{ + \sstdescription{ + This function + returns the number of dimensions spaned by each value in a named + column of a \htmlref{Table}{Table}, together with the length of each dimension. + These are the values supplied when the column was created using + \htmlref{astAddColumn}{astAddColumn}. + } + \sstsynopsis{ + void astColumnShape( AstTable $*$this, const char $*$column, int mxdim, + int $*$ndim, int $*$dims ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + column + }{ + The character string holding the upper case name of the column. Trailing + spaces are ignored. + } + \sstsubsection{ + mxdim + }{ + The length of the + \texttt{"} dims\texttt{"} array. + } + \sstsubsection{ + ndim + }{ + Pointer to an int in which to return the + number of dimensions spanned by values in the named column. + This will be zero if the column contains scalar values. + } + \sstsubsection{ + dims + }{ + Pointer to an + array in which to return the length of each dimension. Any + excess trailing elements will be filled with the value 1. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No error is reported if the requested column cannot be found in the + given Table. A value of zero is returned for + \texttt{"} ndim\texttt{"} and the supplied values in \texttt{"} dims\texttt{"} + are left unchanged. + + \sstitem + A value of zero is returned for + \texttt{"} ndim\texttt{"} + if an error occurs. + } + } +} +\sstroutine{ + astColumnSize +}{ + Get the number of bytes needed to hold a full column of data +}{ + \sstdescription{ + This function returns the number of bytes of memory that must be + allocated prior to retrieving the data from a column using + \htmlref{astGetColumnData}{astGetColumnData}. + } + \sstsynopsis{ + size\_t astColumnSize( AstFitsTable $*$this, const char $*$column, + int $*$hasnull ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Table}{Table}. + } + \sstsubsection{ + column + }{ + The character string holding the name of the column. Trailing + spaces are ignored. + } + } + \sstreturnedvalue{ + \sstsubsection{ + \htmlref{astColumnNull}{astColumnNull}() + }{ + The number of bytes required to store the column data. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error will be reported if the named column does not exist in + the \htmlref{FitsTable}{FitsTable}. + + \sstitem + Zero will be returned as the function value in an error occurs. + } + } +} +\sstroutine{ + astConvert +}{ + Determine how to convert between two coordinate systems +}{ + \sstdescription{ + This function compares two Frames and determines whether it is + possible to convert between the coordinate systems which they + represent. If conversion is possible, it returns a \htmlref{FrameSet}{FrameSet} + which describes the conversion and which may be used (as a + \htmlref{Mapping}{Mapping}) to transform coordinate values in either direction. + + The same function may also be used to determine how to convert + between two FrameSets (or between a \htmlref{Frame}{Frame} and a FrameSet, or + vice versa). This mode is intended for use when (for example) + two images have been calibrated by attaching a FrameSet to each. + astConvert might then be used to search for a + celestial coordinate system that both images have in common, and + the result could then be used to convert between the pixel + coordinates of both images -- having effectively used their + celestial coordinate systems to align them. + + When using FrameSets, there may be more than one possible + intermediate coordinate system in which to perform the + conversion (for instance, two FrameSets might both have + celestial coordinates, detector coordinates, pixel coordinates, + etc.). A comma-separated list of coordinate system domains may + therefore be given which defines a priority order to use when + selecting the intermediate coordinate system. The path used for + conversion must go via an intermediate coordinate system whose + \htmlref{Domain}{Domain} attribute matches one of the domains given. If conversion + cannot be achieved using the first domain, the next one is + considered, and so on, until success is achieved. + } + \sstsynopsis{ + AstFrameSet $*$astConvert( AstFrame $*$from, AstFrame $*$to, + const char $*$domainlist ) + } + \sstparameters{ + \sstsubsection{ + from + }{ + Pointer to a Frame which represents the \texttt{"} source\texttt{"} coordinate + system. This is the coordinate system in which you already + have coordinates available. + + If a FrameSet is given, its current Frame (as determined by + its \htmlref{Current}{Current} attribute) is taken to describe the source + coordinate system. Note that the \htmlref{Base}{Base} attribute of this + FrameSet may be modified by this function to indicate which + intermediate coordinate system was used (see under + \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). + } + \sstsubsection{ + to + }{ + Pointer to a Frame which represents the \texttt{"} destination\texttt{"} + coordinate system. This is the coordinate system into which + you wish to convert your coordinates. + + If a FrameSet is given, its current Frame (as determined by + its Current attribute) is taken to describe the destination + coordinate system. Note that the Base attribute of this + FrameSet may be modified by this function to indicate which + intermediate coordinate system was used (see under + \texttt{"} FrameSets\texttt{"} in the \texttt{"} Applicability\texttt{"} section for details). + } + \sstsubsection{ + domainlist + }{ + Pointer to a null-terminated character string containing a + comma-separated list of Frame domains. This may be used to + define a priority order for the different intermediate + coordinate systems that might be used to perform the + conversion. + + The function will first try to obtain a conversion by making + use only of an intermediate coordinate system whose Domain + attribute matches the first domain in this list. If this + fails, the second domain in the list will be used, and so on, + until conversion is achieved. A blank domain (e.g. two + consecutive commas) indicates that all coordinate systems + should be considered, regardless of their domains. + + This list is case-insensitive and all white space is ignored. + If you do not wish to restrict the domain in this way, + you should supply an empty string. This is normally + appropriate if either of the source or destination coordinate + systems are described by Frames (rather than FrameSets), + since there is then usually only one possible choice of + intermediate coordinate system. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{DSBSpecFrame}{DSBSpecFrame} + }{ + If the \htmlref{AlignSideBand}{AlignSideBand} attribute is non-zero, alignment occurs in the + upper sideband expressed within the spectral system and standard of + rest given by attributes \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}. If + AlignSideBand is zero, the two DSBSpecFrames are aligned as if + they were simple SpecFrames (i.e. the \htmlref{SideBand}{SideBand} is ignored). + } + \sstsubsection{ + Frame + }{ + This function applies to all Frames. Alignment occurs within the + coordinate system given by attribute AlignSystem. + } + \sstsubsection{ + FrameSet + }{ + If either of the \texttt{"} from\texttt{"} or \texttt{"} to\texttt{"} parameters is a pointer to a + FrameSet, then astConvert will attempt to convert from the + coordinate system described by the current Frame of the \texttt{"} from\texttt{"} + FrameSet to that described by the current Frame of the \texttt{"} to\texttt{"} + FrameSet. + + To achieve this, it will consider all of the Frames within + each FrameSet as a possible way of reaching an intermediate + coordinate system that can be used for the conversion. There + is then the possibility that more than one conversion path + may exist and, unless the choice is sufficiently restricted + by the \texttt{"} domainlist\texttt{"} string, the sequence in which the Frames + are considered can be important. In this case, the search + for a conversion path proceeds as follows: + \sstitemlist{ + + \sstitem + Each field in the \texttt{"} domainlist\texttt{"} string is considered in turn. + + \sstitem + The Frames within each FrameSet are considered in a + specific order: (1) the base Frame is always considered + first, (2) after this come all the other Frames in + Frame-index order (but omitting the base and current Frames), + (3) the current Frame is always considered last. However, if + either FrameSet\texttt{'} s \htmlref{Invert}{Invert} attribute is set to a non-zero value + (so that the FrameSet is inverted), then its Frames are + considered in reverse order. (Note that this still means that + the base Frame is considered first and the current Frame + last, because the Invert value will also cause these Frames + to swap places.) + + \sstitem + All source Frames are first considered (in the appropriate + order) for conversion to the first destination Frame. If no + suitable intermediate coordinate system emerges, they are + then considered again for conversion to the second + destination Frame (in the appropriate order), and so on. + + \sstitem + Generally, the first suitable intermediate coordinate + system found is used. However, the overall Mapping between + the source and destination coordinate systems is also + examined. Preference is given to cases where both the + forward and inverse transformations are defined (as indicated + by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one + transformation is defined, the forward one is preferred. + + \sstitem + If the domain of the intermediate coordinate system matches + the current \texttt{"} domainlist\texttt{"} field, the conversion path is + accepted. Otherwise, the next \texttt{"} domainlist\texttt{"} field is considered + and the process repeated. + + } + If conversion is possible, the Base attributes of the two + FrameSets will be modified on exit to identify the Frames + used to access the intermediate coordinate system which was + finally accepted. + + Note that it is possible to force a particular Frame within a + FrameSet to be used as the basis for the intermediate + coordinate system, if it is suitable, by (a) focussing + attention on + it by specifying its domain in the \texttt{"} domainlist\texttt{"} string, or (b) + making it the base Frame, since this is always considered + first. + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + Alignment occurs within the spectral system and standard of rest + given by attributes AlignSystem and AlignStdOfRest. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + Alignment occurs within the time system and time scale given by + attributes AlignSystem and \htmlref{AlignTimeScale}{AlignTimeScale}. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astConvert() + }{ + If the requested coordinate conversion is possible, the + function returns a pointer to a FrameSet which describes the + conversion. Otherwise, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is + returned without error. + + If a FrameSet is returned, it will contain two Frames. Frame + number 1 (its base Frame) will describe the source coordinate + system, corresponding to the \texttt{"} from\texttt{"} parameter. Frame number 2 + (its current Frame) will describe the destination coordinate + system, corresponding to the \texttt{"} to\texttt{"} parameter. The Mapping + which inter-relates these two Frames will perform the + required conversion between their respective coordinate + systems. + + Note that a FrameSet may be used both as a Mapping and as a + Frame. If the result is used as a Mapping (e.g. with + \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates + from the source to the destination coordinate system (or + vice versa if its inverse transformation is selected). If it + is used as a Frame, its attributes will describe the + destination coordinate system. + } + } + \sstexamples{ + \sstexamplesubsection{ + cvt = astConvert( a, b, \texttt{"} \texttt{"} ); + }{ + Attempts to convert between the coordinate systems represented + by \texttt{"} a\texttt{"} and \texttt{"} b\texttt{"} (assumed to be Frames). If successful, a FrameSet + is returned via the \texttt{"} cvt\texttt{"} pointer which may be used to apply the + conversion to sets of coordinates (e.g. using astTran2). + } + \sstexamplesubsection{ + cvt = astConvert( \htmlref{astSkyFrame}{astSkyFrame}(\texttt{"} \texttt{"} ), astSkyFrame(\texttt{"} \htmlref{Equinox}{Equinox}=2005\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Creates a FrameSet which describes precession in the default + FK5 celestial coordinate system between equinoxes J2000 (also + the default) and J2005. The returned \texttt{"} cvt\texttt{"} pointer may then + be passed to astTran2 to apply this precession correction to + any number of coordinate values given in radians. + + Note that the returned FrameSet also contains information + about how to format coordinate values. This means that + setting its \htmlref{Report}{Report} attribute to 1 is a simple way to obtain + printed output (formatted in sexagesimal notation) to show + the coordinate values before and after conversion. + } + \sstexamplesubsection{ + cvt = astConvert( a, b, \texttt{"} sky,detector,\texttt{"} ); + }{ + Attempts to convert between the coordinate systems + represented by the current Frames of \texttt{"} a\texttt{"} and \texttt{"} b\texttt{"} + (now assumed to be FrameSets), via the intermediate \texttt{"} SKY\texttt{"} + coordinate system. This, by default, is the Domain + associated with a celestial coordinate system represented by + a \htmlref{SkyFrame}{SkyFrame}. + + If this fails (for example, because either FrameSet lacks + celestial coordinate information), then the user-defined + \texttt{"} DETECTOR\texttt{"} coordinate system is used instead. If this also + fails, then all other possible ways of achieving conversion + are considered before giving up. + + The returned pointer \texttt{"} cvt\texttt{"} indicates whether conversion was + possible and will have the value AST\_\_NULL if it was not. If + conversion was possible, \texttt{"} cvt\texttt{"} will point at a new FrameSet + describing the conversion. + + The Base attributes of the two FrameSets + will be set by astConvert to indicate which of their Frames was + used for the intermediate coordinate system. This means that + you can subsequently determine which coordinate system was + used by enquiring the Domain attribute of either base Frame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Mapping represented by the returned FrameSet results in + alignment taking place in the coordinate system specified by the + AlignSystem attribute of the \texttt{"} to\texttt{"} Frame. See the description of the + AlignSystem attribute for further details. + + \sstitem + When aligning (say) two images, which have been calibrated by + attaching FrameSets to them, it is usually necessary to convert + between the base Frames (representing \texttt{"} native\texttt{"} pixel + coordinates) of both FrameSets. This may be achieved by + inverting the FrameSets (e.g. using \htmlref{astInvert}{astInvert}) so as to + interchange their base and current Frames before using + astConvert. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astConvex$<$X$>$ +}{ + Create a new Polygon representing the convex hull of a 2D data grid +}{ + \sstdescription{ + This is a set of functions that create the shortest \htmlref{Polygon}{Polygon} that + encloses all pixels with a specified value within a gridded + 2-dimensional data array (e.g. an image). + + A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate + system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to + \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the + Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other + attributes are left unset. The nature of the pixel coordinate system + is determined by parameter + \texttt{"} starpix\texttt{"} . + + You should use a function which matches the numerical type of the + data you are processing by replacing $<$X$>$ in the generic function + name + astConvex$<$X$>$ + by an appropriate 1- or 2-character type code. For example, if you + are procesing data with type + \texttt{"} float\texttt{"} , you should use the function astConvexF + (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to + other numerical types). + } + \sstsynopsis{ + AstPolygon $*$astConvex$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], + const int lbnd[2], const int ubnd[2], int starpix ) + } + \sstparameters{ + \sstsubsection{ + value + }{ + A data value that specifies the pixels to be included within the + convex hull. + } + \sstsubsection{ + oper + }{ + Indicates how the + \texttt{"} value\texttt{"} + parameter is used to select the required pixels. It can + have any of the following values: + \sstitemlist{ + + \sstitem + AST\_\_LT: include pixels with value less than \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_LE: include pixels with value less than or equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_EQ: include pixels with value equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_NE: include pixels with value not equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_GE: include pixels with value greater than or equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_GT: include pixels with value greater than \texttt{"} value\texttt{"} . + } + } + \sstsubsection{ + array + }{ + Pointer to a + 2-dimensional array containing the data to be processed. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astConvexF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the second dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of two integers + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of two integers + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre or upper corner, as selected by parameter + \texttt{"} starpix\texttt{"} . + } + \sstsubsection{ + starpix + }{ + A flag indicating the nature of the pixel coordinate system used + to describe the vertex positions in the returned Polygon. If + non-zero, + the standard Starlink definition of pixel coordinate is used in + which a pixel with integer index I spans a range of pixel coordinate + from (I-1) to I (i.e. pixel corners have integral pixel coordinates). + If zero, + the definition of pixel coordinate used by other AST functions + such as astResample, astMask, + etc., is used. In this definition, a pixel with integer index I + spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. + pixel centres have integral pixel coordinates). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astConvex$<$X$>$() + }{ + A pointer to the required Polygon. + NULL + is returned without error if the array contains no pixels that + satisfy the criterion specified by + \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + NULL + will be returned if this function is invoked with the global + error status set, or if it should fail for any reason. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate masking function, you should + replace $<$X$>$ in the generic function name astConvex$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + L: long int + + \sstitem + UL: unsigned long int + + \sstitem + I: int + + \sstitem + UI: unsigned int + + \sstitem + S: short int + + \sstitem + US: unsigned short int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astConvexD would be used to process \texttt{"} double\texttt{"} + data, while astConvexS would be used to process \texttt{"} short int\texttt{"} + data, etc. + } +} +\sstroutine{ + astCopy +}{ + Copy an Object +}{ + \sstdescription{ + This function creates a copy of an \htmlref{Object}{Object} and returns a pointer + to the resulting new Object. It makes a \texttt{"} deep\texttt{"} copy, which + contains no references to any other Object (i.e. if the original + Object contains references to other Objects, then the actual + data are copied, not simply the references). This means that + modifications may safely be made to the copy without indirectly + affecting any other Object. + } + \sstsynopsis{ + AstObject $*$astCopy( const AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be copied. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCopy() + }{ + Pointer to the new Object. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astCurrentTime +}{ + Return the current system time +}{ + \sstdescription{ + This function + returns the current system time, represented in the form specified + by the supplied \htmlref{TimeFrame}{TimeFrame}. That is, the returned floating point + value should be interpreted using the attribute values of the + TimeFrame. This includes \htmlref{System}{System}, \htmlref{TimeOrigin}{TimeOrigin}, \htmlref{LTOffset}{LTOffset}, \htmlref{TimeScale}{TimeScale}, + and Unit. + } + \sstsynopsis{ + double astCurrentTime( AstTimeFrame $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the TimeFrame. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCurrentTime() + }{ + A TimeFrame axis value representing the current system time. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Values of AST\_\_BAD will be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + + \sstitem + It is assumes that the system time (returned by the C time() + function) follows the POSIX standard, representing a continuous + monotonic increasing count of SI seconds since the epoch 00:00:00 + UTC 1 January 1970 AD (equivalent to TAI with a constant offset). + Resolution is one second. + + \sstitem + An error will be reported if the TimeFrame has a TimeScale value + which cannot be converted to TAI (e.g. \texttt{"} angular\texttt{"} systems such as + UT1, GMST, LMST and LAST). + + \sstitem + Any inaccuracy in the system clock will be reflected in the value + returned by this function. + } + } +} +\sstroutine{ + astCurve +}{ + Draw a geodesic curve +}{ + \sstdescription{ + This function draws a geodesic curve between two points in the + physical coordinate system of a \htmlref{Plot}{Plot}. The curve drawn is the + path of shortest distance joining the two points (as defined by + the \htmlref{astDistance}{astDistance} function for the current \htmlref{Frame}{Frame} of the Plot). + For example, if the current Frame is a basic Frame, then the + curve joining the two points will be a straight line in physical + coordinate space. If the current Frame is more specialised and + describes, for instance, a sky coordinate system, then the + geodesic curve would be a great circle in physical coordinate + space passing through the two sky positions given. + + Note that the geodesic curve is transformed into graphical + coordinate space for plotting, so that a straight line in + physical coordinates may result in a curved line being drawn if + the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the + Mapping between physical and graphical coordinates are + catered for, as is any clipping established using \htmlref{astClip}{astClip}. + + If you need to draw many geodesic curves end-to-end, then the + \htmlref{astPolyCurve}{astPolyCurve} function is equivalent to repeatedly using + astCurve, but will usually be more efficient. + + If you need to draw curves which are not geodesics, see \htmlref{astGenCurve}{astGenCurve} + or \htmlref{astGridLine}{astGridLine}. + } + \sstsynopsis{ + void astCurve( AstPlot $*$this, const double start[], + const double finish[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + start + }{ + An array, with one element for each axis of the Plot, giving + the physical coordinates of the first point on the geodesic + curve. + } + \sstsubsection{ + finish + }{ + An array, with one element for each axis of the Plot, giving + the physical coordinates of the second point on the geodesic + curve. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No curve is drawn if either of the \texttt{"} start\texttt{"} or \texttt{"} finish\texttt{"} arrays + contains any coordinates with the value AST\_\_BAD. + + \sstitem + An error results if the base Frame of the Plot is not 2-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astDSBSpecFrame +}{ + Create a DSBSpecFrame +}{ + \sstdescription{ + This function creates a new \htmlref{DSBSpecFrame}{DSBSpecFrame} and optionally initialises its + attributes. + + A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents + positions in a spectrum obtained using a dual sideband instrument. + Such an instrument produces a spectrum in which each point contains + contributions from two distinctly different frequencies, one from + the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). + Corresponding LSB and USB frequencies are connected by the fact + that they are an equal distance on either side of a fixed central + frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. + + When quoting a position within such a spectrum, it is necessary to + indicate whether the quoted position is the USB position or the + corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this + indication. Another option that the SideBand attribute provides is + to represent a spectral position by its topocentric offset from the + LO frequency. + + In practice, the LO frequency is specified by giving the distance + from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically + this central position is that of some interesting spectral feature. + The distance from this central position to the LO frequency is known + as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can + be a signed value in order to indicate whether the LO frequency is + above or below the central position. + } + \sstsynopsis{ + AstDSBSpecFrame $*$astDSBSpecFrame( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new DSBSpecFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astDSBSpecFrame() + }{ + A pointer to the new DSBSpecFrame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astDecompose +}{ + Decompose a Mapping into two component Mappings +}{ + \sstdescription{ + This function returns pointers to two Mappings which, when applied + either in series or parallel, are equivalent to the supplied \htmlref{Mapping}{Mapping}. + + Since the \htmlref{Frame}{Frame} class inherits from the Mapping class, Frames can + be considered as special types of Mappings and so this method can + be used to decompose either CmpMaps or CmpFrames. + } + \sstsynopsis{ + void astDecompose( AstMapping $*$this, AstMapping $*$$*$map1, + AstMapping $*$$*$map2, int $*$series, int $*$invert1, + int $*$invert2 ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping. + } + \sstsubsection{ + map1 + }{ + Address of a location to receive a pointer to first component + Mapping. + } + \sstsubsection{ + map2 + }{ + Address of a location to receive a pointer to second component + Mapping. + } + \sstsubsection{ + series + }{ + Address of a location to receive a value indicating if the + component Mappings are applied in series or parallel. A non-zero + value means that the supplied Mapping is equivalent to applying map1 + followed by map2 in series. A zero value means that the supplied + Mapping is equivalent to applying map1 to the lower numbered axes + and map2 to the higher numbered axes, in parallel. + } + \sstsubsection{ + invert1 + }{ + The value of the \htmlref{Invert}{Invert} attribute to be used with map1. + } + \sstsubsection{ + invert2 + }{ + The value of the Invert attribute to be used with map2. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + If the supplied Mapping is a CmpMap, then map1 and map2 will be + returned holding pointers to the component Mappings used to + create the CmpMap, either in series or parallel. Note, changing + the Invert attribute of either of the component Mappings using + the returned pointers will have no effect on the supplied CmpMap. + This is because the CmpMap remembers and uses the original settings + of the Invert attributes (that is, the values of the Invert + attributes when the CmpMap was first created). These are the + Invert values which are returned in invert1 and invert2. + } + \sstsubsection{ + \htmlref{TranMap}{TranMap} + }{ + If the supplied Mapping is a TranMap, then map1 and map2 will be + returned holding pointers to the forward and inverse Mappings + represented by the TranMap (zero will be returned for + series). + Note, changing the Invert attribute of + either of the component Mappings using the returned pointers will + have no effect on the supplied TranMap. This is because the TranMap + remembers and uses the original settings of the Invert attributes + (that is, the values of the Invert attributes when the TranMap was + first created). These are the + Invert values which are returned in invert1 and invert2. + } + \sstsubsection{ + Mapping + }{ + For any class of Mapping other than a CmpMap, map1 will be + returned holding a clone of the supplied Mapping pointer, and map2 + will be returned holding a NULL pointer. Invert1 will be returned + holding the current value of the Invert attribute for the supplied + Mapping, and invert2 will be returned holding zero. + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + If the supplied Mapping is a CmpFrame, then map1 and map2 will be + returned holding pointers to the component Frames used to + create the CmpFrame. The component Frames are considered to be in + applied in parallel. + } + \sstsubsection{ + Frame + }{ + For any class of Frame other than a CmpFrame, map1 will be + returned holding a clone of the supplied Frame pointer, and map2 + will be returned holding a NULL pointer. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned Invert values should be used in preference to the + current values of the Invert attribute in map1 and map2. This is + because the attributes may have changed value since the Mappings + were combined. + + \sstitem + Any changes made to the component Mappings using the returned + pointers will be reflected in the supplied Mapping. + } + } +} +\sstroutine{ + astDelFits +}{ + Delete the current FITS card in a FitsChan +}{ + \sstdescription{ + This function deletes the current FITS card from a \htmlref{FitsChan}{FitsChan}. The + current card may be selected using the \htmlref{Card}{Card} attribute (if its index + is known) or by using \htmlref{astFindFits}{astFindFits} (if only the FITS keyword is + known). + + After deletion, the following card becomes the current card. + } + \sstsynopsis{ + void astDelFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function returns without action if the FitsChan is + initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the Card + attribute exceeds the number of cards in the FitsChan). + + \sstitem + If there are no subsequent cards in the FitsChan, then the + Card attribute is left pointing at the \texttt{"} end-of-file\texttt{"} after + deletion (i.e. is set to one more than the number of cards in + the FitsChan). + } + } +} +\sstroutine{ + astDelete +}{ + Delete an Object +}{ + \sstdescription{ + This function deletes an \htmlref{Object}{Object}, freeing all resources + associated with it and rendering any remaining pointers to the + Object invalid. + + Note that deletion is unconditional, regardless of whether other + pointers to the Object are still in use (possibly within other + Objects). A safer approach is to defer deletion, until all + references to an Object have expired, by using \htmlref{astBegin}{astBegin}/\htmlref{astEnd}{astEnd} + (together with \htmlref{astClone}{astClone} and \htmlref{astAnnul}{astAnnul} if necessary). + } + \sstsynopsis{ + AstObject $*$astDelete( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be deleted. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astDelete() + }{ + A null Object pointer (AST\_\_NULL) is always returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function attempts to execute even if the AST error status + is set + on entry, although no further error report will be + made if it subsequently fails under these circumstances. + } + } +} +\sstroutine{ + astDistance +}{ + Calculate the distance between two points in a Frame +}{ + \sstdescription{ + This function finds the distance between two points whose \htmlref{Frame}{Frame} + coordinates are given. The distance calculated is that along + the geodesic curve that joins the two points. + + For example, in a basic Frame, the distance calculated will be + the Cartesian distance along the straight line joining the two + points. For a more specialised Frame describing a sky coordinate + system, however, it would be the distance along the great circle + passing through two sky positions. + } + \sstsynopsis{ + double astDistance( AstFrame $*$this, + const double point1[], const double point2[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + point1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point. + } + \sstsubsection{ + point2 + }{ + An array of double, with one element for each Frame axis + containing the coordinates of the second point. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astDistance + }{ + The distance between the two points. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function will return a \texttt{"} bad\texttt{"} result value (AST\_\_BAD) if + any of the input coordinates has this value. + + \sstitem + A \texttt{"} bad\texttt{"} value will also be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astDownsize +}{ + Reduce the number of vertices in a Polygon +}{ + \sstdescription{ + This function returns a pointer to a new \htmlref{Polygon}{Polygon} that contains a + subset of the vertices in the supplied Polygon. The subset is + chosen so that the returned Polygon is a good approximation to + the supplied Polygon, within the limits specified by the supplied + parameter values. That is, the density of points in the returned + Polygon is greater at points where the curvature of the boundary of + the supplied Polygon is greater. + } + \sstsynopsis{ + AstPolygon $*$astDownsize( AstPolygon $*$this, double maxerr, int maxvert ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Polygon. + } + \sstsubsection{ + maxerr + }{ + The maximum allowed discrepancy between the supplied and + returned Polygons, expressed as a geodesic distance within the + Polygon\texttt{'} s coordinate frame. If this is zero or less, the + returned Polygon will have the number of vertices specified by + maxvert. + } + \sstsubsection{ + maxvert + }{ + The maximum allowed number of vertices in the returned Polygon. + If this is less than 3, the number of vertices in the returned + Polygon will be the minimum needed to achieve the maximum + discrepancy specified by + maxerr. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astDownsize() + }{ + Pointer to the new Polygon. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astEBuf +}{ + End the current graphical buffering context +}{ + \sstdescription{ + This function + ends the current graphics buffering context. It should match a + corresponding call to the + \htmlref{astBBuf}{astBBuf} function. + } + \sstsynopsis{ + void astEBuf( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Plot}{Plot}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The nature of the buffering is determined by the underlying + graphics system (as defined by the current grf module). Each call + to this function + simply invokes the astGEBuf function in the grf module. + } + } +} +\sstroutine{ + astEllipse +}{ + Create a Ellipse +}{ + \sstdescription{ + This function creates a new \htmlref{Ellipse}{Ellipse} and optionally initialises its + attributes. + + A Ellipse is a \htmlref{Region}{Region} which represents a elliptical area within the + supplied 2-dimensional \htmlref{Frame}{Frame}. + } + \sstsynopsis{ + AstEllipse $*$astEllipse( AstFrame $*$frame, int form, const double centre[2], + const double point1[2], const double point2[2], + AstRegion $*$unc, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. It must + have exactly 2 axes. A deep copy is taken of the supplied Frame. + This means that any subsequent changes made to the Frame using the + supplied pointer will have no effect the Region. + } + \sstsubsection{ + form + }{ + Indicates how the ellipse is described by the remaining parameters. + A value of zero indicates that the ellipse is specified by a + centre position and two positions on the circumference. A value of + one indicates that the ellipse is specified by its centre position, + the half-lengths of its two axes, and the orientation of its first + axis. + } + \sstsubsection{ + centre + }{ + An array of 2 doubles, + containing the coordinates at the centre of + the ellipse. + } + \sstsubsection{ + point1 + }{ + An array of 2 doubles. If \texttt{"} form\texttt{"} + is zero, this array should contain the coordinates of one of the four + points where an axis of the ellipse crosses the circumference of the + ellipse. + If \texttt{"} form\texttt{"} + is one, it should contain the lengths of semi-major and + semi-minor axes of the ellipse, given as geodesic distances + within the Frame. + } + \sstsubsection{ + point2 + }{ + An array of 2 doubles. If \texttt{"} form\texttt{"} + is zero, this array should containing the coordinates at some other + point on the circumference of the ellipse, distinct from + \texttt{"} point1\texttt{"} . If \texttt{"} form\texttt{"} + is one, the first element of this array should hold the angle + between the second axis of the Frame and the first ellipse axis + (i.e. the ellipse axis which is specified first in the + \texttt{"} point1\texttt{"} + array), and the second element will be ignored. The angle should be + given in radians, measured positive in the same sense as rotation + from the positive direction of the second Frame axis to the positive + direction of the first Frame axis. + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with the boundary of the Ellipse being created. + The uncertainty in any point on the boundary of the Ellipse is found by + shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at + the boundary point being considered. The area covered by the + shifted uncertainty Region then represents the uncertainty in the + boundary position. The uncertainty is assumed to be the same for + all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, Ellipse, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Ellipse. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the Ellipse being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Ellipse. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astEllipse() + }{ + A pointer to the new Ellipse. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astEllipsePars +}{ + Returns the geometric parameters of an Ellipse +}{ + \sstdescription{ + This function + returns the geometric parameters describing the supplied ellipse. + } + \sstsynopsis{ + void astEllipsePars( AstEllipse $*$this, double centre[2], double $*$a, + double $*$b, double $*$angle, double p1[2], double p2[2] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Region}{Region}. + } + \sstsubsection{ + centre + }{ + The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays. + } + \sstsubsection{ + a + }{ + Returned holding the half-length of the first axis of the + ellipse. + } + \sstsubsection{ + b + }{ + Returned holding the half-length of the second axis of the + ellipse. + } + \sstsubsection{ + angle + }{ + If the coordinate system in which the Ellipse is defined has + axes (X,Y), then + \texttt{"} $*$angle\texttt{"} + is returned holding the angle from the positive direction of + the Y axis to the first axis of the ellipse, in radians. + Positive rotation is in the same sense as rotation from the + positive direction of Y to the positive direction of X. + } + \sstsubsection{ + p1 + }{ + An array in which to return the coordinates at one of the two ends + of the first axis of the ellipse. + A NULL pointer can be supplied if these coordinates are not needed. + } + \sstsubsection{ + p2 + }{ + An array in which to return the coordinates at one of the two ends + of the second axis of the ellipse. + A NULL pointer can be supplied if these coordinates are not needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the coordinate system represented by the Ellipse has been + changed since it was first created, the returned parameters refer + to the new (changed) coordinate system, rather than the original + coordinate system. Note however that if the transformation from + original to new coordinate system is non-linear, the shape + represented by the supplied Ellipse object may not be an accurate + ellipse. + + \sstitem + Values of AST\_\_BAD are returned for the parameters without error + if the ellipse is degenerate or undefined. + } + } +} +\sstroutine{ + astEmptyFits +}{ + Delete all cards in a FitsChan +}{ + \sstdescription{ + This function + deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}. + } + \sstsynopsis{ + void astEmptyFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This method simply deletes the cards currently in the FitsChan. + Unlike \htmlref{astWriteFits}{astWriteFits}, + they are not first written out to the sink function or sink file. + + \sstitem + Any Tables or warnings stored in the FitsChan are also deleted. + + \sstitem + This method attempt to execute even if an error has occurred + previously. + } + } +} +\sstroutine{ + astEnd +}{ + End an AST context +}{ + \sstdescription{ + This macro invokes a function to end an AST context which was + begun with a matching invocation of \htmlref{astBegin}{astBegin}. Any \htmlref{Object}{Object} + pointers created within this context will be annulled (just as + if \htmlref{astAnnul}{astAnnul} had been invoked) and will cease to be valid + afterwards, unless they have previously been exported using + \htmlref{astExport}{astExport} or rendered exempt using \htmlref{astExempt}{astExempt}. + If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to + fall to zero (which happens when the last pointer to it is + annulled), then the Object will be deleted. + } + \sstsynopsis{ + void astEnd + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This macro applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + astEnd attempts to execute even if the AST error status is set. + + \sstitem + Contexts delimited by astBegin and astEnd may be nested to any + depth. + } + } +} +\sstroutine{ + astEscapes +}{ + Control whether graphical escape sequences are included in strings +}{ + \sstdescription{ + The \htmlref{Plot}{Plot} class defines a set of escape sequences which can be + included within a text string in order to control the appearance of + sub-strings within the text. See the \htmlref{Escape}{Escape} attribute for a + description of these escape sequences. It is usually inappropriate + for AST to return strings containing such escape sequences when + called by application code. For instance, an application which + displays the value of the \htmlref{Title}{Title} attribute of a \htmlref{Frame}{Frame} usually does + not want the displayed string to include potentially long escape + sequences which a human read would have difficuly interpreting. + Therefore the default behaviour is for AST to strip out such escape + sequences when called by application code. This default behaviour + can be changed using this function. + } + \sstsynopsis{ + int astEscapes( int new\_value ) + } + \sstparameters{ + \sstsubsection{ + new\_value + }{ + A flag which indicates if escapes sequences should be included + in returned strings. If zero is supplied, escape sequences will + be stripped out of all strings returned by any AST function. If + a positive value is supplied, then any escape sequences will be + retained in the value returned to the caller. If a negative + value is supplied, the current value of the flag will be left + unchanged. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Object}{Object} + }{ + This macro applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astEscapes + }{ + The value of the flag on entry to this function. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function also controls whether the + \htmlref{astStripEscapes}{astStripEscapes} + function removes escape sequences from the supplied string, or + returns the supplied string without change. + + \sstitem + This function attempts to execute even if an error has already + occurred. + } + } +} +\sstroutine{ + astExempt +}{ + Exempt an Object pointer from AST context handling +}{ + \sstdescription{ + This function exempts an \htmlref{Object}{Object} pointer from AST context + handling, as implemented by \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}. This means that + the pointer will not be affected when astEnd is invoked and will + remain active until the end of the program, or until explicitly + annulled using \htmlref{astAnnul}{astAnnul}. + + If possible, you should avoid using this function when writing + applications. It is provided mainly for developers of other + libraries, who may wish to retain references to AST Objects in + internal data structures, and who therefore need to avoid the + effects of astBegin and astEnd. + } + \sstsynopsis{ + void astExempt( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Object pointer to be exempted from context handling. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } +} +\sstroutine{ + astExport +}{ + Export an Object pointer to an outer context +}{ + \sstdescription{ + This function exports an \htmlref{Object}{Object} pointer from the current AST context + into the context that encloses the current one. This means that + the pointer will no longer be annulled when the current context + is ended (with \htmlref{astEnd}{astEnd}), but only when the next outer context (if + any) ends. + } + \sstsynopsis{ + void astExport( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Object pointer to be exported. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + It is only sensible to apply this function to pointers that + have been created within (or exported to) the current context + and have not been rendered exempt using \htmlref{astExempt}{astExempt}. + Applying it to an unsuitable Object pointer has no effect. + } + } +} +\sstroutine{ + astFindFits +}{ + Find a FITS card in a FitsChan by keyword +}{ + \sstdescription{ + This function searches for a card in a \htmlref{FitsChan}{FitsChan} by keyword. The + search commences at the current card (identified by the \htmlref{Card}{Card} + attribute) and ends when a card is found whose FITS keyword + matches the template supplied, or when the last card in the + FitsChan has been searched. + + If the search is successful (i.e. a card is found which matches + the template), the contents of the card are (optionally) + returned and the Card attribute is adjusted to identify the card + found or, if required, the one following it. If the search is + not successful, the function returns zero and the Card attribute + is set to the \texttt{"} end-of-file\texttt{"} . + } + \sstsynopsis{ + int astFindFits( AstFitsChan $*$this, const char $*$name, char card[ 81 ], + int inc ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + name + }{ + Pointer to a null-terminated character string containing a + template for the keyword to be found. In the simplest case, + this should simply be the keyword name (the search is case + insensitive and trailing spaces are ignored). However, this + template may also contain \texttt{"} field specifiers\texttt{"} which are + capable of matching a range of characters (see the \texttt{"} Keyword + Templates\texttt{"} section for details). In this case, the first card + with a keyword which matches the template will be found. To + find the next FITS card regardless of its keyword, you should + use the template \texttt{"} \%f\texttt{"} . + } + \sstsubsection{ + card + }{ + An array of at least 81 characters (to allow room for a + terminating null) + in which the FITS card which is found will be returned. If + the search is not successful (or a NULL pointer is given), a + card will not be returned. + } + \sstsubsection{ + inc + }{ + If this value is zero (and the search is successful), the + FitsChan\texttt{'} s Card attribute will be set to the index of the card + that was found. If it is non-zero, however, the Card + attribute will be incremented to identify the card which + follows the one found. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFindFits() + }{ + One if the search was successful, otherwise zero. + } + } + \sstexamples{ + \sstexamplesubsection{ + result = astFindFits( fitschan, \texttt{"} \%f\texttt{"} , card, 1 ); + }{ + Returns the current card in a FitsChan and advances the Card + attribute to identify the card that follows (the \texttt{"} \%f\texttt{"} + template matches any keyword). + } + \sstexamplesubsection{ + result = astFindFits( fitschan, \texttt{"} BITPIX\texttt{"} , card, 1 ); + }{ + Searches a FitsChan for a FITS card with the \texttt{"} BITPIX\texttt{"} keyword + and returns that card. The Card attribute is then incremented + to identify the card that follows it. + } + \sstexamplesubsection{ + result = astFindFits( fitschan, \texttt{"} COMMENT\texttt{"} , NULL, 0 ); + }{ + Sets the Card attribute of a FitsChan to identify the next + COMMENT card (if any). The card itself is not returned. + } + \sstexamplesubsection{ + result = astFindFits( fitschan, \texttt{"} CRVAL\%1d\texttt{"} , card, 1 ); + }{ + Searches a FitsChan for the next card with a keyword of the + form \texttt{"} CRVALi\texttt{"} (for example, any of the keywords \texttt{"} CRVAL1\texttt{"} , + \texttt{"} CRVAL2\texttt{"} or \texttt{"} CRVAL3\texttt{"} would be matched). The card found (if + any) is returned, and the Card attribute is then incremented + to identify the following card (ready to search for another + keyword with the same form, perhaps). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The search always starts with the current card, as identified + by the Card attribute. To ensure you search the entire contents + of a FitsChan, you should first clear the Card attribute (using + \htmlref{astClear}{astClear}). This effectively \texttt{"} rewinds\texttt{"} the FitsChan. + + \sstitem + If a search is unsuccessful, the Card attribute is set to the + \texttt{"} end-of-file\texttt{"} (i.e. to one more than the number of cards in the + FitsChan). No error occurs. + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + } + } + \sstdiytopic{ + Keyword Templates + }{ + The templates used to match FITS keywords are normally composed + of literal characters, which must match the keyword exactly + (apart from case). However, a template may also contain \texttt{"} field + specifiers\texttt{"} which can match a range of possible characters. This + allows you to search for keywords that contain (for example) + numbers, where the digits comprising the number are not known in + advance. + + A field specifier starts with a \texttt{"} \%\texttt{"} character. This is followed + by an optional single digit (0 to 9) specifying a field + width. Finally, there is a single character which specifies the + + type of character to be matched, as follows: + + \sstitemlist{ + + \sstitem + \texttt{"} c\texttt{"} : matches all upper case letters, + + \sstitem + \texttt{"} d\texttt{"} : matches all decimal digits, + + \sstitem + \texttt{"} f\texttt{"} : matches all characters which are permitted within a FITS + keyword (upper case letters, digits, underscores and hyphens). + + } + If the field width is omitted, the field specifier matches one + or more characters. If the field width is zero, it matches zero + or more characters. Otherwise, it matches exactly the number of + + characters specified. In addition to this: + + \sstitemlist{ + + \sstitem + The template \texttt{"} \%f\texttt{"} will match a blank FITS keyword consisting + of 8 spaces (as well as matching all other keywords). + + \sstitem + A template consisting of 8 spaces will match a blank keyword + (only). + + } + For example: + + \sstitemlist{ + + \sstitem + The template \texttt{"} BitPix\texttt{"} will match the keyword \texttt{"} BITPIX\texttt{"} only. + + \sstitem + The template \texttt{"} crpix\%1d\texttt{"} will match keywords consisting of + \texttt{"} CRPIX\texttt{"} followed by one decimal digit. + + \sstitem + The template \texttt{"} P\%c\texttt{"} will match any keyword starting with \texttt{"} P\texttt{"} + and followed by one or more letters. + + \sstitem + The template \texttt{"} E\%0f\texttt{"} will match any keyword beginning with \texttt{"} E\texttt{"} . + + \sstitem + The template \texttt{"} \%f\texttt{"} will match any keyword at all (including a + blank one). + } + } +} +\sstroutine{ + astFindFrame +}{ + Find a coordinate system with specified characteristics +}{ + \sstdescription{ + This function uses a \texttt{"} template\texttt{"} \htmlref{Frame}{Frame} to search another Frame + (or \htmlref{FrameSet}{FrameSet}) to identify a coordinate system which has a + specified set of characteristics. If a suitable coordinate + system can be found, the function returns a pointer to a + FrameSet which describes the required coordinate system and how + to convert coordinates to and from it. + + This function is provided to help answer general questions about + coordinate systems, such as typically arise when coordinate + information is imported into a program as part of an initially + unknown dataset. For example: + \sstitemlist{ + + \sstitem + Is there a wavelength scale? + + \sstitem + Is there a 2-dimensional coordinate system? + + \sstitem + Is there a celestial coordinate system? + + \sstitem + Can I plot the data in ecliptic coordinates? + + } + You can also use this function as a means of reconciling a + user\texttt{'} s preference for a particular coordinate system (for + example, what type of axes to draw) with what is actually + possible given the coordinate information available. + + To perform a search, you supply a \texttt{"} target\texttt{"} Frame (or FrameSet) + which represents the set of coordinate systems to be searched. + If a basic Frame is given as the target, this set of coordinate + systems consists of the one described by this Frame, plus all + other \texttt{"} virtual\texttt{"} coordinate systems which can potentially be + reached from it by applying built-in conversions (for example, + any of the celestial coordinate conversions known to the AST + library would constitute a \texttt{"} built-in\texttt{"} conversion). If a FrameSet + is given as the target, the set of coordinate systems to be + searched consists of the union of those represented by all the + individual Frames within it. + + To select from this large set of possible coordinate systems, + you supply a \texttt{"} template\texttt{"} Frame which is an instance of the type + of Frame you are looking for. Effectively, you then ask the + function to \texttt{"} find a coordinate system that looks like this\texttt{"} . + + You can make your request more or less specific by setting + attribute values for the template Frame. If a particular + attribute is set in the template, then the function will only + find coordinate systems which have exactly the same value for + that attribute. If you leave a template attribute un-set, + however, then the function has discretion about the value the + attribute should have in any coordinate system it finds. The + attribute will then take its value from one of the actual + (rather than virtual) coordinate systems in the target. If the + target is a FrameSet, its \htmlref{Current}{Current} attribute will be modified to + indicate which of its Frames was used for this purpose. + + The result of this process is a coordinate system represented by + a hybrid Frame which acquires some attributes from the template + (but only if they were set) and the remainder from the + target. This represents the \texttt{"} best compromise\texttt{"} between what you + asked for and what was available. A \htmlref{Mapping}{Mapping} is then generated + which converts from the target coordinate system to this hybrid + one, and the returned FrameSet encapsulates all of this + information. + } + \sstsynopsis{ + AstFrameSet $*$astFindFrame( AstFrame $*$target, AstFrame $*$template, + const char $*$domainlist ) + } + \sstparameters{ + \sstsubsection{ + target + }{ + Pointer to the target Frame (or FrameSet). + + Note that if a FrameSet is supplied (and a suitable + coordinate system is found), then its Current attribute will + be modified to indicate which Frame was used to obtain + attribute values which were not specified by the template. + This Frame will, in some sense, represent the \texttt{"} closest\texttt{"} + non-virtual coordinate system to the one you requested. + } + \sstsubsection{ + template + }{ + Pointer to the template Frame, which should be an instance of + the type of Frame you wish to find. If you wanted to find a + Frame describing a celestial coordinate system, for example, + then you might use a \htmlref{SkyFrame}{SkyFrame} here. See the \texttt{"} Examples\texttt{"} + section for more ideas. + } + \sstsubsection{ + domainlist + }{ + Pointer to a null-terminated character string containing a + comma-separated list of Frame domains. This may be used to + establish a priority order for the different types of + coordinate system that might be found. + + The function will first try to find a suitable coordinate + system whose \htmlref{Domain}{Domain} attribute equals the first domain in this + list. If this fails, the second domain in the list will be + used, and so on, until a result is obtained. A blank domain + (e.g. two consecutive commas) indicates that any coordinate + system is acceptable (subject to the template) regardless of + its domain. + + This list is case-insensitive and all white space is ignored. + If you do not wish to restrict the domain in this way, + you should supply an empty string. + } + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + This function applies to all Frames. + } + \sstsubsection{ + FrameSet + }{ + If the target is a FrameSet, the possibility exists that + several of the Frames within it might be matched by the + template. Unless the choice is sufficiently restricted by + the \texttt{"} domainlist\texttt{"} string, the sequence in which Frames are + searched can then become important. In this case, the search + proceeds as follows: + \sstitemlist{ + + \sstitem + Each field in the \texttt{"} domainlist\texttt{"} string is considered in turn. + + \sstitem + An attempt is made to match the template to each of the + target\texttt{'} s Frames in the order: (1) the current Frame, (2) the + base Frame, (3) each remaining Frame in the order of being + added to the target FrameSet. + + \sstitem + Generally, the first match found is used. However, the + Mapping between the target coordinate system and the + resulting Frame is also examined. Preference is given to + cases where both the forward and inverse transformations are + defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} + attributes). If only one transformation is defined, the + forward one is preferred. + + \sstitem + If a match is found and the domain of the resulting Frame also + matches the current \texttt{"} domainlist\texttt{"} field, it is + accepted. Otherwise, the next \texttt{"} domainlist\texttt{"} field is considered + and the process repeated. + + } + If a suitable coordinate system is found, the Current + attribute of the target FrameSet will be modified on exit to + identify the Frame whose match with the target was eventually + accepted. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFindFrame() + }{ + If the search is successful, the function returns a pointer + to a FrameSet which contains the Frame found and a + description of how to convert to (and from) the coordinate + system it represents. Otherwise, a null \htmlref{Object}{Object} pointer + (AST\_\_NULL) is returned without error. + + If a FrameSet is returned, it will contain two Frames. Frame + number 1 (its base Frame) represents the target coordinate + system and will be the same as the (base Frame of the) + target. Frame number 2 (its current Frame) will be a Frame + representing the coordinate system which the function + found. The Mapping which inter-relates these two Frames will + describe how to convert between their respective coordinate + systems. + + Note that a FrameSet may be used both as a Mapping and as a + Frame. If the result is used as a Mapping (e.g. with + \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates + from the target coordinate system into the new coordinate + system that was found (and vice versa if its inverse + transformation is selected). If it is used as a Frame, its + attributes will describe the new coordinate system. + } + } + \sstexamples{ + \sstexamplesubsection{ + result = astFindFrame( target, \htmlref{astFrame}{astFrame}( 3, \texttt{"} \texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Searches for a 3-dimensional coordinate system in the target + Frame (or FrameSet). No attributes have been set in the + template Frame (created by astFrame), so no restriction has + been placed on the required coordinate system, other than + that it should have 3 dimensions. The first suitable Frame + found will be returned as part of the \texttt{"} result\texttt{"} FrameSet. + } + \sstexamplesubsection{ + result = astFindFrame( target, \htmlref{astSkyFrame}{astSkyFrame}( \texttt{"} \texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Searches for a celestial coordinate system in the target + Frame (or FrameSet). The type of celestial coordinate system + is unspecified, so astFindFrame will return the first one + found as part of the \texttt{"} result\texttt{"} FrameSet. If the target is + a FrameSet, then its Current attribute will be updated to + identify the Frame that was used. + + If no celestial coordinate system can be found, a value of + AST\_\_NULL will be returned without error. + } + \sstexamplesubsection{ + result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{MaxAxes}{MaxAxes}=100\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + This is like the last example, except that in the event of the + target being a \htmlref{CmpFrame}{CmpFrame}, the component Frames encapsulated by the + CmpFrame will be searched for a SkyFrame. If found, the returned + Mapping will included a \htmlref{PermMap}{PermMap} which selects the required axes + from the target CmpFrame. + + This is acomplished by setting the MaxAxes attribute of the + template SkyFrame to a large number (larger than or equal to the + number of axes in the target CmpFrame). This allows the SkyFrame + to be used as a match for Frames containing from 2 to 100 axes. + } + \sstexamplesubsection{ + result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{System}{System}=FK5\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Searches for an equatorial (FK5) coordinate system in the + target. The \htmlref{Equinox}{Equinox} value for the coordinate system has not + been specified, so will be obtained from the target. If the + target is a FrameSet, its Current attribute will be updated + to indicate which SkyFrame was used to obtain this value. + } + \sstexamplesubsection{ + result = astFindFrame( target, astFrame( 2, \texttt{"} \texttt{"} ), \texttt{"} sky,pixel,\texttt{"} ); + }{ + Searches for a 2-dimensional coordinate system in the + target. Initially, a search is made for a suitable coordinate + system whose Domain attribute has the value \texttt{"} SKY\texttt{"} . If this + search fails, a search is then made for one with the domain + \texttt{"} PIXEL\texttt{"} . If this also fails, then any 2-dimensional + coordinate system is returned as part of the \texttt{"} result\texttt{"} + FrameSet. + + Only if no 2-dimensional coordinate systems can be reached by + applying built-in conversions to any of the Frames in the + target will a value of AST\_\_NULL be returned. + } + \sstexamplesubsection{ + result = astFindFrame( target, astFrame( 1, \texttt{"} Domain=WAVELENGTH\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Searches for any 1-dimensional coordinate system in the + target which has the domain \texttt{"} WAVELENGTH\texttt{"} . + } + \sstexamplesubsection{ + result = astFindFrame( target, astFrame( 1, \texttt{"} \texttt{"} ), \texttt{"} wavelength\texttt{"} ); + }{ + This example has exactly the same effect as that above. It + illustrates the equivalence of the template\texttt{'} s Domain attribute + and the fields in the \texttt{"} domainlist\texttt{"} string. + } + \sstexamplesubsection{ + result = astFindFrame( target, astFrame( 1, \texttt{"} MaxAxes=3\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + This is a more advanced example which will search for any + coordinate system in the target having 1, 2 or 3 + dimensions. The Frame returned (as part of the \texttt{"} result\texttt{"} + FrameSet) will always be 1-dimensional, but will be related + to the coordinate system that was found by a suitable Mapping + (e.g. a PermMap) which simply extracts the first axis. + + If we had wanted a Frame representing the actual (1, 2 or + 3-dimensional) coordinate system found, we could set the + \htmlref{PreserveAxes}{PreserveAxes} attribute to a non-zero value in the template. + } + \sstexamplesubsection{ + result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{Permute}{Permute}=0\texttt{"} ), \texttt{"} \texttt{"} ); + }{ + Searches for any celestial coordinate system in the target, + but only finds one if its axes are in the conventional + (longitude,latitude) order and have not been permuted + (e.g. with \htmlref{astPermAxes}{astPermAxes}). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Mapping represented by the returned FrameSet results in + alignment taking place in the coordinate system specified by the + \htmlref{AlignSystem}{AlignSystem} attribute of the \texttt{"} template\texttt{"} Frame. See the description + of the AlignSystem attribute for further details. + + \sstitem + Beware of setting the Domain attribute of the template and then + using a \texttt{"} domainlist\texttt{"} string which does not include the template\texttt{'} s domain + (or a blank field). If you do so, no coordinate system will be + found. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + More on Using Templates + }{ + A Frame (describing a coordinate system) will be found by this + function if (a) it is \texttt{"} matched\texttt{"} by the template you supply, and + (b) the value of its Domain attribute appears in the \texttt{"} domainlist\texttt{"} + string (except that a blank field in this string permits any + domain). A successful match by the template depends on a number + of criteria, as outlined below: + \sstitemlist{ + + \sstitem + In general, a template will only match another Frame which + belongs to the same class as the template, or to a derived (more + specialised) class. For example, a SkyFrame template will match + any other SkyFrame, but will not match a basic + Frame. Conversely, a basic Frame template will match any class + of Frame. + + \sstitem + The exception to this is that a Frame of any class can be used to + match a CmpFrame, if that CmpFrame contains a Frame of the same + class as the template. Note however, the MaxAxes and \htmlref{MinAxes}{MinAxes} + attributes of the template must be set to suitable values to allow + it to match the CmpFrame. That is, the MinAxes attribute must be + less than or equal to the number of axes in the target, and the MaxAxes + attribute must be greater than or equal to the number of axes in + the target. + + \sstitem + If using a CmpFrame as a template frame, the MinAxes and MaxAxes + for the template are determined by the MinAxes and MaxAxes values of + the component Frames within the template. So if you want a template + CmpFrame to be able to match Frames with different numbers of axes, + then you must set the MaxAxes and/or MinAxes attributes in the component + template Frames, before combining them together into the template + CmpFrame. + + \sstitem + If a template has a value set for any of its main attributes, then + it will only match Frames which have an identical value for that + attribute (or which can be transformed, using a built-in + conversion, so that they have the required value for that + attribute). If any attribute in the template is un-set, however, + then Frames are matched regardless of the value they may have + for that attribute. You may therefore make a template more or + less specific by choosing the attributes for which you set + values. This requirement does not apply to \texttt{'} descriptive\texttt{'} attributes + such as titles, labels, symbols, etc. + + \sstitem + An important application of this principle involves the Domain + attribute. Setting the Domain attribute of the template has the + effect of restricting the search to a particular type of Frame + (with the domain you specify). Conversely, if the Domain + attribute is not set in the template, then the domain of the + Frame found is not relevant, so all Frames are searched. Note + that the + \texttt{"} domainlist\texttt{"} string provides an alternative way of restricting the + search in the same manner, but is a more convenient interface if + you wish to search automatically for another domain if the first + search fails. + + \sstitem + Normally, a template will only match a Frame which has the + same number of axes as itself. However, for some classes of + template, this default behaviour may be changed by means of the + MinAxes, MaxAxes and \htmlref{MatchEnd}{MatchEnd} attributes. In addition, the + behaviour of a template may be influenced by its Permute and + PreserveAxes attributes, which control whether it matches Frames + whose axes have been permuted, and whether this permutation is + retained in the Frame which is returned (as opposed to returning + the axes in the order specified in the template, which is the + default behaviour). You should consult the descriptions of these + attributes for details of this more advanced use of templates. + } + } +} +\sstroutine{ + astFitsChan +}{ + Create a FitsChan +}{ + \sstdescription{ + This function creates a new \htmlref{FitsChan}{FitsChan} and optionally initialises + its attributes. + + A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O + operations involving the use of FITS (Flexible Image Transport + \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a + description of that Object composed of FITS header cards, and + reading from a FitsChan will create a new Object from its FITS + header card description. + + While a FitsChan is active, it represents a buffer which may + contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to + FITS conventions. Any sequence of FITS-conforming header cards + may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is + merely implied. The cards may be accessed in any order by using + the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} + card, to which subsequent operations apply. Searches + based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new + cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and + existing ones may be deleted (\htmlref{astDelFits}{astDelFits}) or changed (astSetFits$<$X$>$). + + When you create a FitsChan, you have the option of specifying + \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data + stores by reading and writing FITS header cards. If you provide + a source function, it is used to fill the FitsChan with header cards + when it is accessed for the first time. If you do not provide a + source function, the FitsChan remains empty until you explicitly enter + data into it (e.g. using astPutFits, astPutCards, astWrite + or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from + which headers should be read). When the FitsChan is deleted, any + remaining header cards in the FitsChan can be saved in either of + two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the + name of a text file to which header cards should be written), or 2) + by providing a sink function (used to to deliver header cards to an + external data store). If you do not provide a sink function or a + value for SinkFile, any header cards remaining when the FitsChan + is deleted will be lost, so you should arrange to extract them + first if necessary + (e.g. using astFindFits or \htmlref{astRead}{astRead}). + + Coordinate system information may be described using FITS header + cards using several different conventions, termed + \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a + FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute + determines how the Object is converted to (or from) a + description involving FITS header cards. In general, different + encodings will result in different sets of header cards to + describe the same Object. Examples of encodings include the DSS + encoding (based on conventions used by the STScI Digitised Sky + Survey data), the FITS-WCS encoding (based on a proposed FITS + standard) and the NATIVE encoding (a near loss-less way of + storing AST Objects in FITS headers). + + The available encodings differ in the range of Objects they can + represent, in the number of Object descriptions that can coexist + in the same FitsChan, and in their accessibility to other + (external) astronomy applications (see the Encoding attribute + for details). Encodings are not necessarily mutually exclusive + and it may sometimes be possible to describe the same Object in + several ways within a particular set of FITS header cards by + using several different encodings. + + The detailed behaviour of astRead and astWrite, when used with + a FitsChan, depends on the encoding in use. In general, however, + all use of astRead is destructive, so that FITS header cards + are consumed in the process of reading an Object, and are + removed from the FitsChan (this deletion can be prevented for + specific cards by calling the + \htmlref{astRetainFits}{astRetainFits} function). + + If the encoding in use allows only a single Object description + to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF + encodings), then write operations using astWrite will + over-write any existing Object description using that + encoding. Otherwise (e.g. the NATIVE encoding), multiple Object + descriptions are written sequentially and may later be read + back in the same sequence. + } + \sstsynopsis{ + AstFitsChan $*$astFitsChan( const char $*$($*$ source)( void ), + void ($*$ sink)( const char $*$ ), + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + source + }{ + Pointer to a source function which takes no arguments and + returns a pointer to a null-terminated string. This function + will be used by the FitsChan to obtain input FITS header + cards. On each invocation, it should read the next input card + from some external source (such as a FITS file), and return a + pointer to the (null-terminated) contents of the card. It + should return a NULL pointer when there are no more cards to + be read. + + If \texttt{"} source\texttt{"} is NULL, the FitsChan will remain empty until + cards are explicitly stored in it (e.g. using astPutCards, + astPutFits or via the SourceFile attribute). + } + \sstsubsection{ + sink + }{ + Pointer to a sink function that takes a pointer to a + null-terminated string as an argument and returns void. If + no value has been set for the SinkFile attribute, this + function will be used by the FitsChan to deliver any FITS + header cards it contains when it is finally deleted. On + each invocation, it should deliver the contents of the character + string passed to it as a FITS header card to some external + data store (such as a FITS file). + + If \texttt{"} sink\texttt{"} is NULL, + and no value has been set for the SinkFile attribute, the + contents of the FitsChan will be lost when it is deleted. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new FitsChan. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + + Note, the FITSCHAN\_OPTIONS environment variable may be used + to specify default options for all newly created FitsChans. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFitsChan() + }{ + A pointer to the new FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No FITS \texttt{"} END\texttt{"} card will be written via the sink function. You + should add this card yourself after the FitsChan has been + deleted. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astFitsTable +}{ + Create a FitsTable +}{ + \sstdescription{ + This function creates a new \htmlref{FitsTable}{FitsTable} and optionally initialises + its attributes. + + The FitsTable class is a representation of a FITS binary table. It + inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the + binary data of the main table, and a \htmlref{FitsChan}{FitsChan} is used to hold the FITS + header. Note, there is no provision for binary data following the main + table (such data is referred to as a \texttt{"} heap\texttt{"} in the FITS standard). + + Note - it is not recommended to use the FitsTable class to store + very large tables. + } + \sstsynopsis{ + AstFitsTable $*$astFitsTable( AstFitsChan $*$header, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + header + }{ + Pointer to an optional FitsChan containing headers to be stored + in the FitsTable. + NULL + may be supplied if the new FitsTable is to be left empty. If + supplied, and if the headers describe columns of a FITS binary + table, then equivalent (empty) columns are added to the FitsTable. + Each column has the same index in the FitsTable that it has in + the supplied header. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new FitsTable. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFitsTable() + }{ + A pointer to the new FitsTable. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list described above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astFluxFrame +}{ + Create a FluxFrame +}{ + \sstdescription{ + This function creates a new \htmlref{FluxFrame}{FluxFrame} and optionally initialises + its attributes. + + A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various systems used to represent the signal level in an + observation. The particular coordinate system to be used is specified + by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by + other attributes such as the units, etc (see the description of the + System attribute for details). + + All flux values are assumed to be measured at the same frequency or + wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is + more appropriate for use with images rather than spectra. + } + \sstsynopsis{ + AstFluxFrame $*$astFluxFrame( double specval, AstSpecFrame $*$specfrm, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + specval + }{ + The spectral value to which the flux values refer, given in the + spectral coordinate system specified by + \texttt{"} specfrm\texttt{"} . The value supplied for the \texttt{"} specval\texttt{"} + parameter becomes the default value for the SpecVal attribute. + A value of AST\_\_BAD may be supplied if the spectral position is + unknown, but this may result in it not being possible for the + \htmlref{astConvert}{astConvert} + function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and + some other FluxFrame. + } + \sstsubsection{ + specfrm + }{ + A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system + in which the + \texttt{"} specval\texttt{"} + parameter is given. A deep copy of this object is taken, so any + subsequent changes to the SpecFrame using the supplied pointer will + have no effect on the new FluxFrame. + A NULL pointer can be supplied if AST\_\_BAD is supplied for \texttt{"} specval\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new FluxFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFluxFrame() + }{ + A pointer to the new FluxFrame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When conversion between two FluxFrames is requested (as when + supplying FluxFrames to astConvert), + account will be taken of the nature of the flux coordinate systems + they represent, together with any qualifying attribute values, including + the \htmlref{AlignSystem}{AlignSystem} attribute. The results will therefore fully reflect the + relationship between positions measured in the two systems. In addition, + any difference in the Unit attributes of the two systems will also be + taken into account. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astFormat +}{ + Format a coordinate value for a Frame axis +}{ + \sstdescription{ + This function returns a pointer to a string containing the + formatted (character) version of a coordinate value for a \htmlref{Frame}{Frame} + axis. The formatting applied is determined by the Frame\texttt{'} s + attributes and, in particular, by any Format attribute string + that has been set for the axis. A suitable default format (based + on the Digits attribute value) will be applied if necessary. + } + \sstsynopsis{ + const char $*$astFormat( AstFrame $*$this, int axis, double value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + axis + }{ + The number of the Frame axis for which formatting is to be + performed (axis numbering starts at 1 for the first axis). + } + \sstsubsection{ + value + }{ + The coordinate value to be formatted. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFormat() + }{ + A pointer to a null-terminated string containing the formatted + value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned pointer is guaranteed to remain valid and the + string to which it points will not be over-written for a total + of 50 successive invocations of this function. After this, the + memory containing the string may be re-used, so a copy of the + string should be made if it is needed for longer than this. + + \sstitem + A formatted value may be converted back into a numerical (double) + value using \htmlref{astUnformat}{astUnformat}. + + \sstitem + A NULL pointer will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astFrame +}{ + Create a Frame +}{ + \sstdescription{ + This function creates a new \htmlref{Frame}{Frame} and optionally initialises its + attributes. + + A Frame is used to represent a coordinate system. It does this + in rather the same way that a frame around a graph describes the + coordinate space in which data are plotted. Consequently, a + Frame has a \htmlref{Title}{Title} (string) attribute, which describes the + coordinate space, and contains axes which in turn hold + information such as Label and Units strings which are used for + labelling (e.g.) graphical output. In general, however, the + number of axes is not restricted to two. + + Functions are available for converting Frame coordinate values + into a form suitable for display, and also for calculating + distances and offsets between positions within the Frame. + + Frames may also contain knowledge of how to transform to and + from related coordinate systems. + } + \sstsynopsis{ + AstFrame $*$astFrame( int naxes, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + naxes + }{ + The number of Frame axes (i.e. the number of dimensions of + the coordinate space which the Frame describes). + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Frame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFrame() + }{ + A pointer to the new Frame. + } + } + \sstexamples{ + \sstexamplesubsection{ + frame = astFrame( 2, \texttt{"} Title=Energy Spectrum: \htmlref{Plot}{Plot} \%d\texttt{"} , n ); + }{ + Creates a new 2-dimensional Frame and initialises its Title + attribute to the string \texttt{"} Energy Spectrum: Plot $<$n$>$\texttt{"} , where + $<$n$>$ takes the value of the int variable \texttt{"} n\texttt{"} . + } + \sstexamplesubsection{ + frame = astFrame( 2, \texttt{"} Label(1)=Energy, Label(2)=Response\texttt{"} ); + }{ + Creates a new 2-dimensional Frame and initialises its axis + Label attributes to suitable string values. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astFrameSet +}{ + Create a FrameSet +}{ + \sstdescription{ + This function creates a new \htmlref{FrameSet}{FrameSet} and optionally initialises + its attributes. + + A FrameSet consists of a set of one or more Frames (which + describe coordinate systems), connected together by Mappings + (which describe how the coordinate systems are inter-related). A + FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair + of these Frames (i.e. to convert between any of the coordinate + systems which it describes). The individual Frames are + identified within the FrameSet by an integer index, with Frames + being numbered consecutively from one as they are added to the + FrameSet. + + Every FrameSet has a \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} Frame (which + are allowed to be the same). Any of the Frames may be nominated + to hold these positions, and the choice is determined by the + values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold + the indices of the relevant Frames. By default, the first Frame + added to a FrameSet is its base Frame, and the last one added is + its current Frame. + + The base Frame describes the \texttt{"} native\texttt{"} coordinate system of + whatever the FrameSet is used to calibrate (e.g. the pixel + coordinates of an image) and the current Frame describes the + \texttt{"} apparent\texttt{"} coordinate system in which it should be viewed + (e.g. displayed, etc.). Any further Frames represent a library + of alternative coordinate systems, which may be selected by + making them current. + + When a FrameSet is used in a context that requires a Frame, + (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current + Frame is used. A FrameSet may therefore be used in place of its + current Frame in most situations. + + When a FrameSet is used in a context that requires a Mapping, + the Mapping used is the one between its base Frame and its + current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"} + coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any + Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which + has the effect of interchanging its base and current Frames and + hence of reversing the Mapping between them. + + Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of + Frame), either explicitly or as components within CmpFrames. In this + case the Mapping between a pair of Frames within a FrameSet will + include the effects of the clipping produced by any Regions included + in the path between the Frames. + } + \sstsynopsis{ + AstFrameSet $*$astFrameSet( AstFrame $*$frame, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + Pointer to the first Frame to be inserted into the + FrameSet. This initially becomes both the base and the + current Frame. (Further Frames may be added using the + \htmlref{astAddFrame}{astAddFrame} function.) + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new FrameSet. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFrameSet() + }{ + A pointer to the new FrameSet. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If a pointer to an existing FrameSet is given for the \texttt{"} frame\texttt{"} + parameter, then the new FrameSet will (as a special case) be + initialised to contain the same Frames and Mappings, and to have + the same attribute values, as the one supplied. This process is + similar to making a copy of a FrameSet (see \htmlref{astCopy}{astCopy}), except + that the Frames and Mappings contained in the original are not + themselves copied, but are shared by both FrameSets. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astFromString +}{ + Re-create an Object from an in-memory serialisation +}{ + \sstdescription{ + This function returns a pointer to a new \htmlref{Object}{Object} created from the + supplied text string, which should have been created by \htmlref{astToString}{astToString}. + } + \sstsynopsis{ + AstObject $*$astFromString( const char $*$string ) + } + \sstparameters{ + \sstsubsection{ + string + }{ + Pointer to a text string holding an Object serialisation created + previously by astToString. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFromString() + }{ + Pointer to a new Object created from the supplied serialisation, + or NULL if the serialisation was invalid, or an error occurred. + } + } +} +\sstroutine{ + astGenCurve +}{ + Draw a generalized curve +}{ + \sstdescription{ + This function draws a general user-defined curve defined by the + supplied \htmlref{Mapping}{Mapping}. Note that the curve is transformed into graphical + coordinate space for plotting, so that a straight line in + physical coordinates may result in a curved line being drawn if + the Mapping involved is non-linear. Any discontinuities in the + Mapping between physical and graphical coordinates are + catered for, as is any clipping established using \htmlref{astClip}{astClip}. + + If you need to draw simple straight lines (geodesics), \htmlref{astCurve}{astCurve} + or \htmlref{astPolyCurve}{astPolyCurve} will usually be easier to use and faster. + } + \sstsynopsis{ + void astGenCurve( AstPlot $*$this, astMapping $*$map ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Plot}{Plot}. + } + \sstsubsection{ + map + }{ + Pointer to a Mapping. This Mapping should have 1 input + coordinate representing offset along the required curve, + normalized so that the start of the curve is at offset 0.0, + and the end of the curve is at offset 1.0. Note, this offset + does not need to be linearly related to distance along the curve. + The number of output coordinates should equal the number of axes + in the current \htmlref{Frame}{Frame} of the Plot. The Mapping should map a + specified offset along the curve, into the corresponding + coordinates in the current Frame of the Plot. The inverse + transformation need not be defined. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error results if the base Frame of the Plot is not 2-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astGet$<$X$>$ +}{ + Get an attribute value for an Object +}{ + \sstdescription{ + This is a family of functions which return a specified attribute + value for an \htmlref{Object}{Object} using one of several different data + types. The type is selected by replacing $<$X$>$ in the function name + by C, D, F, I or L, to obtain a result in const char$*$ (i.e. string), + double, float, int, or long format, respectively. + + If possible, the attribute value is converted to the type you + request. If conversion is not possible, an error will result. + } + \sstsynopsis{ + $<$X$>$type astGet$<$X$>$( AstObject $*$this, const char $*$attrib ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + attrib + }{ + Pointer to a null-terminated string containing the name of + the attribute whose value is required. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + These functions apply to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGet$<$X$>$() + }{ + The attribute value, in the data type corresponding to $<$X$>$ (or, + in the case of astGetC, a pointer to a constant null-terminated + character string containing this value). + } + } + \sstexamples{ + \sstexamplesubsection{ + printf( \texttt{"} \htmlref{RefCount}{RefCount} = \%d$\backslash$n\texttt{"} , astGetI( z, \texttt{"} RefCount\texttt{"} ) ); + }{ + Prints the RefCount attribute value for Object \texttt{"} z\texttt{"} as an int. + } + \sstexamplesubsection{ + title = astGetC( axis, \texttt{"} \htmlref{Title}{Title}\texttt{"} ); + }{ + Obtains a pointer to a null-terminated character string containing + the Title attribute of Object \texttt{"} axis\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + An appropriate \texttt{"} null\texttt{"} value will be returned if this function + is invoked with the AST error status set, or if it should + fail for any reason. This null value is zero for numeric + values and NULL for pointer values. + + \sstitem + The pointer returned by astGetC is guaranteed to remain valid + and the string to which it points will not be over-written for a + total of 50 successive invocations of this function. After this, + the memory containing the string may be re-used, so a copy of + the string should be made if it is needed for longer than this. + } + } +} +\sstroutine{ + astGetActiveUnit +}{ + Determines how the Unit attribute will be used +}{ + \sstdescription{ + This function + returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See + the description of the \htmlref{astSetActiveUnit}{astSetActiveUnit} function + for a description of the ActiveUnit flag. + } + \sstsynopsis{ + int astGetActiveUnit( AstFrame $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetActiveUnit + }{ + The current value of the ActiveUnit flag. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A zero value will be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astGetColumnData +}{ + Retrieve all the data values stored in a column +}{ + \sstdescription{ + This function + copies all data values from a named column into a supplied buffer + } + \sstsynopsis{ + void astGetColumnData( AstFitsTable $*$this, const char $*$column, + float fnull, double dnull, size\_t mxsize, + void $*$coldata, int $*$nelem ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{FitsTable}{FitsTable}. + } + \sstsubsection{ + column + }{ + The character string holding the name of the column. Trailing + spaces are ignored. + } + \sstsubsection{ + fnull + }{ + The value to return in + \texttt{"} coldata\texttt{"} + for any cells for which no value has been stored in the + FitsTable. Ignored if the column\texttt{'} s data type is not + AST\_\_FLOATTYPE. Supplying + AST\_\_NANF + will cause a single precision IEEE NaN value to be used. + } + \sstsubsection{ + dnull + }{ + The value to return in + \texttt{"} coldata\texttt{"} + for any cells for which no value has been stored in the + FitsTable. Ignored if the column\texttt{'} s data type is not + AST\_\_DOUBLETYPE. Supplying AST\_\_NAN will cause a double precision + IEEE NaN value to be used. + } + \sstsubsection{ + mxsize + }{ + The size of the + \texttt{"} coldata\texttt{"} + array, in bytes. The amount of memory needed to hold the data + from a column may be determined using + \htmlref{astColumnSize}{astColumnSize}. + If the supplied array is too small to hold all the column data, + trailing column values will be omitted from the returned array, + but no error will be reported. + } + \sstsubsection{ + coldata + }{ + A pointer to an + area of memory in which to return the data + values currently stored in the column. The values are stored in + row order. If the column holds non-scalar values, the elements + of each value are stored in \texttt{"} Fortran\texttt{"} order. No data type + conversion is performed - the data type of each returned value + is the data type associated with the column when the column was + added to the table. If the column holds strings, the returned + strings will be null terminated. Any excess room at the end of + the array will be left unchanged. + } + \sstsubsection{ + nelem + }{ + The number of elements returned in the + \texttt{"} coldata\texttt{"} + array. This is the product of the number of rows returned and + the number of elements in each column value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The \texttt{"} fnull\texttt{"} and \texttt{"} dnull\texttt{"} parameters + specify the value to be returned for any empty cells within columns + holding floating point values. For columns holding integer values, + the value returned for empty cells is the value returned by the + astColumNull function. + For columns holding string values, the ASCII NULL character is returned + for empty cells. + } + } +} +\sstroutine{ + astGetFits$<$X$>$ +}{ + Get a named keyword value from a FitsChan +}{ + \sstdescription{ + This is a family of functions which gets a value for a named keyword, + or the value of the current card, from a \htmlref{FitsChan}{FitsChan} using one of several + different data types. The data type of the returned value is selected + by replacing $<$X$>$ in the function name by one of the following strings + representing the recognised FITS data types: + + \sstitemlist{ + + \sstitem + CF - Complex floating point values. + + \sstitem + CI - Complex integer values. + + \sstitem + F - Floating point values. + + \sstitem + I - Integer values. + + \sstitem + L - Logical (i.e. boolean) values. + + \sstitem + S - String values. + + \sstitem + CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but + are encoded without an equals sign. + + } + The data type of the \texttt{"} value\texttt{"} + parameter + + depends on $<$X$>$ as follows: + + \sstitemlist{ + + \sstitem + CF - \texttt{"} double $*$\texttt{"} (a pointer to a 2 element array to hold the real and + imaginary parts of the complex value). + + \sstitem + CI - \texttt{"} int $*$\texttt{"} (a pointer to a 2 element array to hold the real and + imaginary parts of the complex value). + + \sstitem + F - \texttt{"} double $*$\texttt{"} . + + \sstitem + I - \texttt{"} int $*$\texttt{"} . + + \sstitem + L - \texttt{"} int $*$\texttt{"} . + + \sstitem + S - \texttt{"} char $*$$*$\texttt{"} (a pointer to a static \texttt{"} char\texttt{"} array is returned at the + location given by the \texttt{"} value\texttt{"} parameter, Note, the stored string + may change on subsequent invocations of astGetFitsS so a + permanent copy should be taken of the string if necessary). + + \sstitem + CN - Like\texttt{"} S\texttt{"} . + } + } + \sstsynopsis{ + int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + name + }{ + Pointer to a null-terminated character string + containing the FITS keyword name. This may be a complete FITS + header card, in which case the keyword to use is extracted from + it. No more than 80 characters are read from this string. If + NULL + is supplied, the value of the current card is returned. + } + \sstsubsection{ + value + }{ + A pointer to a + buffer to receive the keyword value. The data type depends on $<$X$>$ + as described above. The conents of the buffer on entry are left + unchanged if the keyword is not found. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetFits$<$X$>$$<$X$>$() + }{ + A value of zero + is returned if the keyword was not found in the FitsChan (no error + is reported). Otherwise, a value of + one + is returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If a name is supplied, the card following the current card is + checked first. If this is not the required card, then the rest of the + FitsChan is searched, starting with the first card added to the + FitsChan. Therefore cards should be accessed in the order they are + stored in the FitsChan (if possible) as this will minimise the time + spent searching for cards. + + \sstitem + If the requested card is found, it becomes the current card, + otherwise the current card is left pointing at the \texttt{"} end-of-file\texttt{"} . + + \sstitem + If the stored keyword value is not of the requested type, it is + converted into the requested type. + + \sstitem + If the keyword is found in the FitsChan, but has no associated + value, an error is reported. If necessary, the + \htmlref{astTestFits}{astTestFits} + function can be used to determine if the keyword has a defined + value in the FitsChan prior to calling this function. + + \sstitem + An error will be reported if the keyword name does not conform + to FITS requirements. + + \sstitem + Zero + + \sstitem + .FALSE. + is returned as the function value if an error has already occurred, + or if this function should fail for any reason. + + \sstitem + The FITS standard says that string keyword values should be + padded with trailing spaces if they are shorter than 8 characters. + For this reason, trailing spaces are removed from the string + returned by + astGetFitsS + if the original string (including any trailing spaces) contains 8 + or fewer characters. Trailing spaces are not removed from longer + strings. + } + } +} +\sstroutine{ + astGetFrame +}{ + Obtain a pointer to a specified Frame in a FrameSet +}{ + \sstdescription{ + This function returns a pointer to a specified \htmlref{Frame}{Frame} in a + \htmlref{FrameSet}{FrameSet}. + } + \sstsynopsis{ + AstFrame $*$astGetFrame( AstFrameSet $*$this, int iframe ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe + }{ + The index of the required Frame within the FrameSet. This + value should lie in the range from 1 to the number of Frames + in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetFrame() + }{ + A pointer to the requested Frame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of AST\_\_BASE or AST\_\_CURRENT may be given for the + \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current + Frame respectively. + + \sstitem + This function increments the \htmlref{RefCount}{RefCount} attribute of the + selected Frame by one. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetGrfContext +}{ + Return the KeyMap that describes a Plot\texttt{'} s graphics context +}{ + \sstdescription{ + This function + returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing + functions registered using \htmlref{astGrfSet}{astGrfSet}. + This KeyMap can be used by an application to pass information to + the drawing functions + about the context in which they are being called. The contents of + the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself. + } + \sstsynopsis{ + AstKeyMap $*$astGetGrfContext( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetGrfContext() + }{ + A pointer to the graphics context KeyMap. The returned pointer + should be annulled when it is no longer needed. + } + } +} +\sstroutine{ + astGetMapping +}{ + Obtain a Mapping that converts between two Frames in a FrameSet +}{ + \sstdescription{ + This function returns a pointer to a \htmlref{Mapping}{Mapping} that will convert + coordinates between the coordinate systems represented by two + Frames in a \htmlref{FrameSet}{FrameSet}. + } + \sstsynopsis{ + AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe1 + }{ + The index of the first \htmlref{Frame}{Frame} in the FrameSet. This Frame describes + the coordinate system for the \texttt{"} input\texttt{"} end of the Mapping. + } + \sstsubsection{ + iframe2 + }{ + The index of the second Frame in the FrameSet. This Frame + describes the coordinate system for the \texttt{"} output\texttt{"} end of the + Mapping. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetMapping() + }{ + Pointer to a Mapping whose forward transformation converts + coordinates from the first coordinate system to the second + one, and whose inverse transformation converts coordinates in + the opposite direction. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned Mapping will include the clipping effect of any + Regions which occur on the path between the two supplied Frames + (this includes the two supplied Frames themselves). + + \sstitem + The values given for the \texttt{"} iframe1\texttt{"} and \texttt{"} iframe2\texttt{"} parameters + should lie in the range from 1 to the number of Frames in the + FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). A value of + AST\_\_BASE or AST\_\_CURRENT may also be given to identify the + FrameSet\texttt{'} s base Frame or current Frame respectively. It is + permissible for both these parameters to have the same value, in + which case a unit Mapping (\htmlref{UnitMap}{UnitMap}) is returned. + + \sstitem + It should always be possible to generate the Mapping + requested, but this does necessarily guarantee that it will be + able to perform the required coordinate conversion. If + necessary, the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes of the + returned Mapping should be inspected to determine if the + required transformation is available. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetRefPos +}{ + Return the reference position in a specified celestial coordinate system +}{ + \sstdescription{ + This function + returns the reference position (specified by attributes \htmlref{RefRA}{RefRA} and + \htmlref{RefDec}{RefDec}) converted to the celestial coordinate system represented by + a supplied \htmlref{SkyFrame}{SkyFrame}. The celestial longitude and latitude values + are returned in radians. + } + \sstsynopsis{ + void astGetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double $*$lon, + double $*$lat ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{SpecFrame}{SpecFrame}. + } + \sstsubsection{ + frm + }{ + Pointer to the SkyFrame which defines the required celestial + coordinate system. + If NULL + is supplied, then the longitude and latitude values are returned + as FK5 J2000 RA and Dec values. + } + \sstsubsection{ + lon + }{ + A pointer to a double in which to store the + longitude of the reference point, in the coordinate system + represented by the supplied SkyFrame (radians). + } + \sstsubsection{ + lat + }{ + A pointer to a double in which to store the + latitude of the reference point, in the coordinate system + represented by the supplied SkyFrame (radians). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Values of AST\_\_BAD will be returned if this function is + invoked with the AST error status set, or if it should fail for + any reason. + } + } +} +\sstroutine{ + astGetRegionBounds +}{ + Returns the bounding box of Region +}{ + \sstdescription{ + This function + returns the upper and lower limits of a box which just encompasses + the supplied \htmlref{Region}{Region}. The limits are returned as axis values within + the \htmlref{Frame}{Frame} represented by the Region. The value of the \htmlref{Negated}{Negated} + attribute is ignored (i.e. it is assumed that the Region has not + been negated). + } + \sstsynopsis{ + void astGetRegionBounds( AstRegion $*$this, double $*$lbnd, double $*$ubnd ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + lbnd + }{ + Pointer to an + array in which to return the lower axis bounds covered by the Region. + It should have at least as many elements as there are axes in the + Region. If an axis has no lower limit, the returned value will + be the largest possible negative value. + } + \sstsubsection{ + ubnd + }{ + Pointer to an + array in which to return the upper axis bounds covered by the Region. + It should have at least as many elements as there are axes in the + Region. If an axis has no upper limit, the returned value will + be the largest possible positive value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The value of the Negated attribute is ignored (i.e. it is assumed that + the Region has not been negated). + + \sstitem + If an axis has no extent on an axis then the lower limit will be + returned larger than the upper limit. Note, this is different to an + axis which has a constant value (in which case both lower and upper + limit will be returned set to the constant value). + + \sstitem + If the bounds on an axis cannot be determined, AST\_\_BAD is returned for + both upper and lower bounds + } + } +} +\sstroutine{ + astGetRegionFrame +}{ + Obtain a pointer to the encapsulated Frame within a Region +}{ + \sstdescription{ + This function returns a pointer to the \htmlref{Frame}{Frame} represented by a + \htmlref{Region}{Region}. + } + \sstsynopsis{ + AstFrame $*$astGetRegionFrame( AstRegion $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetRegionFrame() + }{ + A pointer to a deep copy of the Frame represented by the Region. + Using this pointer to modify the Frame will have no effect on + the Region. To modify the Region, use the Region pointer directly. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetRegionFrameSet +}{ + Obtain a pointer to the encapsulated FrameSet within a Region +}{ + \sstdescription{ + This function returns a pointer to the \htmlref{FrameSet}{FrameSet} encapsulated by a + \htmlref{Region}{Region}. The base \htmlref{Frame}{Frame} is the Frame in which the box was originally + defined, and the current Frame is the Frame into which the Region + is currently mapped (i.e. it will be the same as the Frame returned + by \htmlref{astGetRegionFrame}{astGetRegionFrame}). + } + \sstsynopsis{ + AstFrame $*$astGetRegionFrameSet( AstRegion $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetRegionFrameSet() + }{ + A pointer to a deep copy of the FrameSet represented by the Region. + Using this pointer to modify the FrameSet will have no effect on + the Region. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetRegionMesh +}{ + Return a mesh of points covering the surface or volume of a Region +}{ + \sstdescription{ + This function + returns the axis values at a mesh of points either covering the + surface (i.e. boundary) of the supplied \htmlref{Region}{Region}, or filling the + interior (i.e. volume) of the Region. The number of points in + the mesh is approximately equal to the \htmlref{MeshSize}{MeshSize} attribute. + } + \sstsynopsis{ + void astGetRegionMesh( AstRegion $*$this, int surface, int maxpoint, + int maxcoord, int $*$npoint, double $*$points ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + surface + }{ + If non-zero, + the returned points will cover the surface or the Region. + Otherwise, they will fill the interior of the Region. + } + \sstsubsection{ + maxpoint + }{ + If zero, the number of points in the mesh is returned in + \texttt{"} $*$npoint\texttt{"} , + but no axis values are returned and all other parameters are ignored. + If not zero, the supplied value should be the length of the + second dimension of the \texttt{"} points\texttt{"} + array. An error is reported if the number of points in the mesh + exceeds this number. + } + \sstsubsection{ + maxcoord + }{ + The length of the + first dimension of the \texttt{"} points\texttt{"} array. + An error is reported if the number of axes in the supplied Region + exceeds this number. + } + \sstsubsection{ + npoint + }{ + A pointer to an integer in which to return the + number of points in the returned mesh. + } + \sstsubsection{ + points + }{ + The address of the first element in a 2-dimensional array of + shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return the coordinate + values at the mesh positions. These are stored such that the + value of coordinate number \texttt{"} coord\texttt{"} for point number \texttt{"} point\texttt{"} is + found in element \texttt{"} points[coord][point]\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error is reported if the Region is unbounded. + + \sstitem + If the coordinate system represented by the Region has been + changed since it was first created, the returned axis values refer + to the new (changed) coordinate system, rather than the original + coordinate system. Note however that if the transformation from + original to new coordinate system is non-linear, the shape within + the new coordinate system may be distorted, and so may not match + that implied by the name of the Region subclass (\htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc). + } + } +} +\sstroutine{ + astGetRegionPoints +}{ + Returns the positions that define the given Region +}{ + \sstdescription{ + This function + returns the axis values at the points that define the supplied + \htmlref{Region}{Region}. The particular meaning of these points will depend on the + type of class supplied, as listed below under \texttt{"} Applicability:\texttt{"} . + } + \sstsynopsis{ + void astGetRegionPoints( AstRegion $*$this, int maxpoint, int maxcoord, + int $*$npoint, double $*$points ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + maxpoint + }{ + If zero, the number of points needed to define the Region is + returned in + \texttt{"} $*$npoint\texttt{"} , + but no axis values are returned and all other parameters are ignored. + If not zero, the supplied value should be the length of the + second dimension of the \texttt{"} points\texttt{"} + array. An error is reported if the number of points needed to define + the Region exceeds this number. + } + \sstsubsection{ + maxcoord + }{ + The length of the + first dimension of the \texttt{"} points\texttt{"} array. + An error is reported if the number of axes in the supplied Region + exceeds this number. + } + \sstsubsection{ + npoint + }{ + A pointer to an integer in which to return the + number of points defining the Region. + } + \sstsubsection{ + points + }{ + The address of the first element in a 2-dimensional array of + shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return + the coordinate values at the positions that define the Region. + These are stored such that the value of coordinate number + \texttt{"} coord\texttt{"} for point number \texttt{"} point\texttt{"} is found in element + \texttt{"} points[coord][point]\texttt{"} . + } + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + \sstsubsection{ + \htmlref{Box}{Box} + }{ + The first returned position is the Box centre, and the second is + a Box corner. + } + \sstsubsection{ + \htmlref{Circle}{Circle} + }{ + The first returned position is the Circle centre, and the second is + a point on the circumference. + } + \sstsubsection{ + \htmlref{CmpRegion}{CmpRegion} + }{ + Returns a value of zero for + \texttt{"} $*$npoint\texttt{"} + and leaves the supplied array contents unchanged. To find the + points defining a CmpRegion, use this method on the component + Regions, which can be accessed by invoking + \htmlref{astDecompose}{astDecompose} + on the CmpRegion. + } + \sstsubsection{ + \htmlref{Ellipse}{Ellipse} + }{ + The first returned position is the Ellipse centre. The second is + the end of one of the axes of the ellipse. The third is some + other point on the circumference of the ellipse, distinct from + the second point. + } + \sstsubsection{ + \htmlref{Interval}{Interval} + }{ + The first point corresponds to the lower bounds position, and + the second point corresponds to the upper bounds position. These + are reversed to indicate an extcluded interval rather than an + included interval. See the Interval constructor for more + information. + } + \sstsubsection{ + \htmlref{NullRegion}{NullRegion} + }{ + Returns a value of zero for + \texttt{"} $*$npoint\texttt{"} + and leaves the supplied array contents unchanged. + } + \sstsubsection{ + \htmlref{PointList}{PointList} + }{ + The positions returned are those that were supplied when the + PointList was constructed. + } + \sstsubsection{ + \htmlref{Polygon}{Polygon} + }{ + The positions returned are the vertex positions that were supplied + when the Polygon was constructed. + } + \sstsubsection{ + \htmlref{Prism}{Prism} + }{ + Returns a value of zero for + \texttt{"} $*$npoint\texttt{"} + and leaves the supplied array contents unchanged. To find the + points defining a Prism, use this method on the component + Regions, which can be accessed by invoking + astDecompose + on the CmpRegion. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the coordinate system represented by the Region has been + changed since it was first created, the returned axis values refer + to the new (changed) coordinate system, rather than the original + coordinate system. Note however that if the transformation from + original to new coordinate system is non-linear, the shape within + the new coordinate system may be distorted, and so may not match + that implied by the name of the Region subclass (Circle, Box, etc). + } + } +} +\sstroutine{ + astGetStcCoord +}{ + Return information about an AstroCoords element stored in an Stc +}{ + \sstdescription{ + When any sub-class of \htmlref{Stc}{Stc} is created, the constructor function + allows one or more AstroCoords elements to be stored within the Stc. + This function allows any one of these AstroCoords elements to be + retrieved. The format of the returned information is the same as + that used to pass the original information to the Stc constructor. + That is, the information is returned in a \htmlref{KeyMap}{KeyMap} structure + containing elements with one or more of the keys given by symbolic + constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, + AST\_\_STCSIZE and AST\_\_STCPIXSZ. + + If the coordinate system represented by the Stc has been changed + since it was created (for instance, by changing its \htmlref{System}{System} + attribute), then the sizes and positions in the returned KeyMap + will reflect the change in coordinate system. + } + \sstsynopsis{ + AstKeyMap $*$astGetStcCoord( AstStc $*$this, int icoord ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Stc. + } + \sstsubsection{ + icoord + }{ + The index of the AstroCoords element required. The first has index + one. The number of AstroCoords elements in the Stc can be found using + function astGetStcNcoord. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetStcCoord() + }{ + A pointer to a new KeyMap containing the required information. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetStcNCoord +}{ + Return the number of AstroCoords elements stored in an Stc +}{ + \sstdescription{ + This function returns the number of AstroCoords elements stored in + an \htmlref{Stc}{Stc}. + } + \sstsynopsis{ + int astGetStcNCoord( AstStc $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Stc. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetStcNCoord() + }{ + The number of AstroCoords elements stored in the Stc. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Zero will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetStcRegion +}{ + Obtain a copy of the encapsulated Region within a Stc +}{ + \sstdescription{ + This function returns a pointer to a deep copy of the \htmlref{Region}{Region} + supplied when the \htmlref{Stc}{Stc} was created. + } + \sstsynopsis{ + AstRegion $*$astGetStcRegion( AstStc $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Stc. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetStcRegion() + }{ + A pointer to a deep copy of the Region encapsulated within the + supplied Stc. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetTableHeader +}{ + Get the FITS headers from a FitsTable +}{ + \sstdescription{ + This function returns a pointer to a \htmlref{FitsChan}{FitsChan} holding copies of + the FITS headers associated with a \htmlref{FitsTable}{FitsTable}. + } + \sstsynopsis{ + AstFitsChan $*$astGetTableHeader( AstFitsTable $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsTable. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetTableHeader() + }{ + A pointer to a deep copy of the FitsChan stored within the + FitsTable. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned pointer should be annulled using + \htmlref{astAnnul}{astAnnul} + when it is no longer needed. + + \sstitem + Changing the contents of the returned FitsChan will have no effect + on the FitsTable. To modify the FitsTable, the modified FitsChan must + be stored in the FitsTable using + \htmlref{astPutTableHeader}{astPutTableHeader}. + } + } +} +\sstroutine{ + astGetTables +}{ + Retrieve any FitsTables currently in a FitsChan +}{ + \sstdescription{ + If the supplied \htmlref{FitsChan}{FitsChan} currently contains any tables, then this + function returns a pointer to a \htmlref{KeyMap}{KeyMap}. Each entry in the KeyMap + is a pointer to a \htmlref{FitsTable}{FitsTable} holding the data for a FITS binary + table. The key used to access each entry is the FITS extension + name in which the table should be stored. + + Tables can be present in a FitsChan as a result either of using the + \htmlref{astPutTable}{astPutTable} (or \htmlref{astPutTables}{astPutTables}) + method to store existing tables in the FitsChan, or of using the + \htmlref{astWrite}{astWrite} + method to write a \htmlref{FrameSet}{FrameSet} to the FitsChan. For the later case, if + the FitsChan \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute is positive and the FrameSet requires + a look-up table to describe one or more axes, then the \texttt{"} -TAB\texttt{"} + algorithm code described in FITS-WCS paper III is used and the table + values are stored in the FitsChan in the form of a FitsTable object + (see the documentation for the \texttt{"} TabOK\texttt{"} attribute). + } + \sstsynopsis{ + AstKeyMap $*$astGetTables( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetTables() + }{ + A pointer to a deep copy of the KeyMap holding the tables currently + in the FitsChan, or + NULL + if the FitsChan does not contain any tables. The returned + pointer should be annulled using + \htmlref{astAnnul}{astAnnul} + when no longer needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGetUnc +}{ + Obtain uncertainty information from a Region +}{ + \sstdescription{ + This function returns a \htmlref{Region}{Region} which represents the uncertainty + associated with positions within the supplied Region. See + \htmlref{astSetUnc}{astSetUnc} + for more information about Region uncertainties and their use. + } + \sstsynopsis{ + AstRegion $*$astGetUnc( AstRegion $*$this, int def ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + def + }{ + Controls what is returned if no uncertainty information has been + associated explicitly with the supplied Region. If + a non-zero value + is supplied, then the default uncertainty Region used internally + within AST is returned (see \texttt{"} Applicability\texttt{"} below). If + zero is supplied, then NULL + will be returned (without error). + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{CmpRegion}{CmpRegion} + }{ + The default uncertainty for a CmpRegion is taken from one of the + two component Regions. If the first component Region has a + non-default uncertainty, then it is used as the default uncertainty + for the parent CmpRegion. Otherwise, if the second component Region + has a non-default uncertainty, then it is used as the default + uncertainty for the parent CmpRegion. If neither of the + component Regions has non-default uncertainty, then the default + uncertainty for the CmpRegion is 1.0E-6 of the bounding box of + the CmpRegion. + } + \sstsubsection{ + \htmlref{Prism}{Prism} + }{ + The default uncertainty for a Prism is formed by combining the + uncertainties from the two component Regions. If a component + Region does not have a non-default uncertainty, then its default + uncertainty will be used to form the default uncertainty of the + parent Prism. + } + \sstsubsection{ + Region + }{ + For other classes of Region, the default uncertainty is 1.0E-6 + of the bounding box of the Region. If the bounding box has zero + width on any axis, then the uncertainty will be 1.0E-6 of the + axis value. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGetUnc() + }{ + A pointer to a Region describing the uncertainty in the supplied + Region. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If uncertainty information is associated with a Region, and the + coordinate system described by the Region is subsequently changed + (e.g. by changing the value of its \htmlref{System}{System} attribute, or using the + \htmlref{astMapRegion}{astMapRegion} + function), then the uncertainty information returned by this function + will be modified so that it refers to the coordinate system currently + described by the supplied Region. + + \sstitem + A null \htmlref{Object}{Object} pointer (NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astGrfPop +}{ + Restore previously saved graphics functions used by a Plot +}{ + \sstdescription{ + This function restores a snapshot of the graphics functions + stored previously by calling \htmlref{astGrfPush}{astGrfPush}. The restored graphics + functions become the current graphics functions used by the \htmlref{Plot}{Plot}. + + The astGrfPush and astGrfPop functions are intended for situations + where it is necessary to make temporary changes to the graphics + functions used by the Plot. The current functions should first be + saved by calling astGrfPush. New functions should then be registered + using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced. + Finally, astGrfPop should be called to restore the original graphics + functions. + } + \sstsynopsis{ + void astGrfPop( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function returns without action if there are no snapshots to + restore. No error is reported in this case. + } + } +} +\sstroutine{ + astGrfPush +}{ + Save the current graphics functions used by a Plot +}{ + \sstdescription{ + This function takes a snapshot of the graphics functions which are + currently registered with the supplied \htmlref{Plot}{Plot}, and saves the snapshot + on a first-in-last-out stack within the Plot. The snapshot can be + restored later using function + \htmlref{astGrfPop}{astGrfPop}. + + The astGrfPush and astGrfPop functions are intended for situations + where it is necessary to make temporary changes to the graphics + functions used by the Plot. The current functions should first be + saved by calling astGrfPush. New functions should then be registered + using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced. + Finally, astGrfPop should be called to restore the original graphics + functions. + } + \sstsynopsis{ + void astGrfPush( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + } +} +\sstroutine{ + astGrfSet +}{ + Register a graphics function for use by a Plot +}{ + \sstdescription{ + This function can be used to select the underlying graphics + functions to be used when the supplied \htmlref{Plot}{Plot} produces graphical output. + If this function is not called prior to producing graphical + output, then the underlying graphics functions selected at + link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use + alternative graphics functions, call this function before + the graphical output is created, specifying the graphics + functions to be used. This will register the function for future + use, but the function will not actually be used until the \htmlref{Grf}{Grf} + attribute is given a non-zero value. + } + \sstsynopsis{ + void astGrfSet( AstPlot $*$this, const char $*$name, AstGrfFun fun ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + name + }{ + A name indicating the graphics function to be replaced. + Various graphics functions are used by the + Plot class, and any combination of them may be supplied by calling + this function once for each function to be replaced. If any of the + graphics functions are not replaced in this way, the + corresponding functions in the graphics interface selected at + link-time (using the ast\_link command) are used. The allowed + names are: + + \sstitemlist{ + + \sstitem + Attr - Enquire or set a graphics attribute value + + \sstitem + BBuf - Start a new graphics buffering context + + \sstitem + Cap - Inquire a capability + + \sstitem + EBuf - End the current graphics buffering context + + \sstitem + Flush - Flush all pending graphics to the output device + + \sstitem + Line - Draw a polyline (i.e. a set of connected lines) + + \sstitem + Mark - Draw a set of markers + + \sstitem + Qch - Return the character height in world coordinates + + \sstitem + Scales - Get the axis scales + + \sstitem + Text - Draw a character string + + \sstitem + TxExt - Get the extent of a character string + + } + The string is case insensitive. For details of the interface + required for each, see the sections below. + } + \sstsubsection{ + fun + }{ + A Pointer to the function to be used to provide the + functionality indicated by parameter name. The interface for + each function is described below, but the function pointer should + be cast to a type of AstGrfFun when calling astGrfSet. + + Once a function has been provided, a null pointer can be supplied + in a subsequent call to astGrfSet to reset the function to the + corresponding function in the graphics interface selected at + link-time. + } + } + \sstdiytopic{ + Function Interfaces + }{ + All the functions listed below (except for \texttt{"} Cap\texttt{"} ) should return an + integer value of 0 if an error occurs, and 1 otherwise. All x and y + values refer + to \texttt{"} graphics cordinates\texttt{"} as defined by the graphbox parameter of + the \htmlref{astPlot}{astPlot} call which created the Plot. + + The first parameter (\texttt{"} grfcon\texttt{"} ) + for each function is an AST \htmlref{KeyMap}{KeyMap} pointer that can be used by the + called function to establish the context in which it is being called. + The contents of the KeyMap are determined by the calling + application, which should obtain a pointer to the KeyMap using the + \htmlref{astGetGrfContext}{astGetGrfContext} function, + and then store any necessary information in the KeyMap using the + methods of the KeyMap class. Note, the functions listed below + should never annul or delete the supplied KeyMap pointer. + } + \sstdiytopic{ + Attr + }{ + The \texttt{"} Attr\texttt{"} function returns the current value of a specified graphics + attribute, and optionally establishes a new value. The supplied + value is converted to an integer value if necessary before use. + It requires the following interface: + + int Attr( AstObject $*$grfcon, int attr, double value, double $*$old\_value, int prim ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + attr - An integer value identifying the required attribute. + The following symbolic values are defined in grf.h: + GRF\_\_STYLE (Line style), + GRF\_\_WIDTH (Line width), + GRF\_\_SIZE (Character and marker size scale factor), + GRF\_\_FONT (Character font), + GRF\_\_COLOUR (Colour index). + + \sstitem + value - + A new value to store for the attribute. If this is AST\_\_BAD + no value is stored. + + \sstitem + old\_value - A pointer to a double in which to return + the attribute value. + If this is NULL, no value is returned. + + \sstitem + prim - + The sort of graphics primitive to be drawn with the new attribute. + Identified by the following values defined in grf.h: + GRF\_\_LINE, + GRF\_\_MARK, + GRF\_\_TEXT. + } + } + \sstdiytopic{ + BBuf + }{ + The \texttt{"} BBuf\texttt{"} function should start a new graphics buffering context. + A matching call to the function \texttt{"} EBuf\texttt{"} should be used to end the + context. The nature of the buffering is determined by the underlying + graphics system. + + int BBuf( AstObject $*$grfcon ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + } + } + \sstdiytopic{ + Cap + }{ + The \texttt{"} Cap\texttt{"} function is called to determine if the grf module has a + given capability, as indicated by the \texttt{"} cap\texttt{"} argument: + + int Cap( AstObject $*$grfcon, int cap, int value ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + cap - + The capability being inquired about. This will be one of the + following constants defined in grf.h: + + } + GRF\_\_SCALES: This function should return a non-zero value if the + \texttt{"} Scales\texttt{"} function is implemented, and zero otherwise. The supplied + \texttt{"} value\texttt{"} argument should be ignored. + + GRF\_\_MJUST: This function should return a non-zero value if + the \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions recognise \texttt{"} M\texttt{"} as a + character in the justification string. If the first character of + a justification string is \texttt{"} M\texttt{"} , then the text should be justified + with the given reference point at the bottom of the bounding box. + This is different to \texttt{"} B\texttt{"} justification, which requests that the + reference point be put on the baseline of the text, since some + characters hang down below the baseline. If the \texttt{"} Text\texttt{"} or + \texttt{"} TxExt\texttt{"} function cannot differentiate between \texttt{"} M\texttt{"} and \texttt{"} B\texttt{"} , + then this function should return zero, in which case \texttt{"} M\texttt{"} + justification will never be requested by Plot. The supplied + \texttt{"} value\texttt{"} argument should be ignored. + + GRF\_\_ESC: This function should return a non-zero value if the + \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} functions can recognise and interpret + graphics escape sequences within the supplied string (see + attribute \htmlref{Escape}{Escape}). Zero should be returned if escape sequences + cannot be interpreted (in which case the Plot class will interpret + them itself if needed). The supplied \texttt{"} value\texttt{"} argument should be + ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"} and + \texttt{"} TxExt\texttt{"} . Otherwise, \texttt{"} value\texttt{"} indicates whether \texttt{"} Text\texttt{"} and \texttt{"} TxExt\texttt{"} + should interpret escape sequences in subsequent calls. If \texttt{"} value\texttt{"} is + non-zero then escape sequences should be interpreted by \texttt{"} Text\texttt{"} and + \texttt{"} TxExt\texttt{"} . Otherwise, they should be drawn as literal text. + + \sstitemlist{ + + \sstitem + value - + The use of this parameter depends on the value of \texttt{"} cap\texttt{"} as + described above. + + \sstitem + Returned Function Value: + The value returned by the function depends on the value of \texttt{"} cap\texttt{"} + as described above. Zero should be returned if the supplied + capability is not recognised. + } + } + \sstdiytopic{ + EBuf + }{ + The \texttt{"} EBuf\texttt{"} function should end the current graphics buffering + context. See the description of \texttt{"} BBuf\texttt{"} above for further details. + It requires the following interface: + + int EBuf( AstObject $*$grfcon ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + } + } + \sstdiytopic{ + Flush + }{ + The \texttt{"} Flush\texttt{"} function ensures that the display device is up-to-date, + by flushing any pending graphics to the output device. It + requires the following interface: + + int Flush( AstObject $*$grfcon ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + } + } + \sstdiytopic{ + Line + }{ + The \texttt{"} Line\texttt{"} function displays lines joining the given positions and + requires the following interface: + + int Line( AstObject $*$grfcon, int n, const float $*$x, const float $*$y ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + n - The number of positions to be joined together. + + \sstitem + x - A pointer to an array holding the \texttt{"} n\texttt{"} x values. + + \sstitem + y - A pointer to an array holding the \texttt{"} n\texttt{"} y values. + } + } + \sstdiytopic{ + Mark + }{ + The \texttt{"} Mark\texttt{"} function displays markers at the given positions. It + requires the following interface: + + int Mark( AstObject $*$grfcon, int n, const float $*$x, const float $*$y, int type ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + n - The number of positions to be marked. + + \sstitem + x - A pointer to an array holding the \texttt{"} n\texttt{"} x values. + + \sstitem + y - A pointer to an array holding the \texttt{"} n\texttt{"} y values. + + \sstitem + type - An integer which can be used to indicate the type of marker + symbol required. + } + } + \sstdiytopic{ + Qch + }{ + The \texttt{"} Qch\texttt{"} function returns the heights of characters drawn vertically + and horizontally in graphics coordinates. It requires the following + interface: + + int Qch( AstObject $*$grfcon, float $*$chv, float $*$chh ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + chv - A pointer to the float which is to receive the height of + characters drawn with a vertical baseline. This will be an + increment in the X axis. + + \sstitem + chh - A pointer to the float which is to receive the height of + characters drawn with a horizontal baseline. This will be an + increment in the Y axis. + } + } + \sstdiytopic{ + Scales + }{ + The \texttt{"} Scales\texttt{"} function returns two values (one for each axis) which + scale increments on the corresponding axis into a \texttt{"} normal\texttt{"} coordinate + system in which: 1) the axes have equal scale in terms of (for instance) + millimetres per unit distance, 2) X values increase from left to + right, and 3) Y values increase from bottom to top. It requires the + following interface: + + int Scales( AstObject $*$grfcon, float $*$alpha, float $*$beta ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + alpha - A pointer to the float which is to receive the + scale for the X axis (i.e. Xnorm = alpha$*$Xworld). + + \sstitem + beta - A pointer to the float which is to receive the + scale for the Y axis (i.e. Ynorm = beta$*$Yworld). + } + } + \sstdiytopic{ + Text + }{ + The \texttt{"} Text\texttt{"} function displays a character string at a given + position using a specified justification and up-vector. It + requires the following interface: + + int Text( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, + float upx, float upy ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + text - Pointer to a null-terminated character string to be displayed. + + \sstitem + x - The reference x coordinate. + + \sstitem + y - The reference y coordinate. + + \sstitem + just - A character string which specifies the location within the + text string which is to be placed at the reference position + given by x and y. The first character may be \texttt{'} T\texttt{'} for \texttt{"} top\texttt{"} , + \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} B\texttt{'} for \texttt{"} bottom\texttt{"} , and specifies the + vertical location of the reference position. Note, \texttt{"} bottom\texttt{"} + corresponds to the base-line of normal text. Some characters + (eg \texttt{"} y\texttt{"} , \texttt{"} g\texttt{"} , \texttt{"} p\texttt{"} , etc) descend below the base-line. The second + character may be \texttt{'} L\texttt{'} for \texttt{"} left\texttt{"} , \texttt{'} C\texttt{'} for \texttt{"} centre\texttt{"} , or \texttt{'} R\texttt{'} + for \texttt{"} right\texttt{"} , and specifies the horizontal location of the + reference position. If the string has less than 2 characters + then \texttt{'} C\texttt{'} is used for the missing characters. + + \sstitem + upx - The x component of the up-vector for the text. + If necessary the supplied value should be negated + to ensure that positive values always refer to displacements from + left to right on the screen. + + \sstitem + upy - The y component of the up-vector for the text. + If necessary the supplied value should be negated + to ensure that positive values always refer to displacements from + bottom to top on the screen. + } + } + \sstdiytopic{ + TxExt + }{ + The \texttt{"} TxExt\texttt{"} function returns the corners of a box which would enclose + the supplied character string if it were displayed using the + Text function described above. The returned box includes any leading + or trailing spaces. It requires the following interface: + + int TxExt( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just, + float upx, float upy, float $*$xb, float $*$yb ) + + \sstitemlist{ + + \sstitem + grfcon - + A KeyMap containing information passed from the calling application. + + \sstitem + text - Pointer to a null-terminated character string to be displayed. + + \sstitem + x - The reference x coordinate. + + \sstitem + y - The reference y coordinate. + + \sstitem + just - A character string which specifies the location within the + text string which is to be placed at the reference position + given by x and y. See \texttt{"} Text\texttt{"} above. + + \sstitem + upx - The x component of the up-vector for the text. + See \texttt{"} Text\texttt{"} above. + + \sstitem + upy - The y component of the up-vector for the text. + See \texttt{"} Text\texttt{"} above. + + \sstitem + xb - An array of 4 elements in which to return the x coordinate of + each corner of the bounding box. + + \sstitem + yb - An array of 4 elements in which to return the y coordinate of + each corner of the bounding box. + } + } +} +\sstroutine{ + astGrid +}{ + Draw a set of labelled coordinate axes +}{ + \sstdescription{ + This function draws a complete annotated set of + coordinate axes for a \htmlref{Plot}{Plot} with (optionally) a coordinate grid + superimposed. Details of the axes and grid can be controlled by + setting values for the various attributes defined by the Plot + class (q.v.). + } + \sstsynopsis{ + void astGrid( AstPlot $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the supplied Plot is a \htmlref{Plot3D}{Plot3D}, the axes will be annotated + using three 2-dimensional Plots, one for each 2D plane in the 3D + current coordinate system. The plots will be \texttt{"} pasted\texttt{"} onto 3 faces + of the cuboid graphics volume specified when the Plot3D was + constructed. The faces to be used can be controlled by the \texttt{"} \htmlref{RootCorner}{RootCorner}\texttt{"} + attribute. + + \sstitem + An error results if either the current \htmlref{Frame}{Frame} or the base Frame + of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional. + + \sstitem + An error also results if the transformation between the base + and current Frames of the Plot is not defined in either + direction (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} or \htmlref{TranInverse}{TranInverse} attribute + is zero). + } + } +} +\sstroutine{ + astGridLine +}{ + Draw a grid line (or axis) for a Plot +}{ + \sstdescription{ + This function draws a curve in the physical coordinate system of + a \htmlref{Plot}{Plot} by varying only one of the coordinates along the length + of the curve. It is intended for drawing coordinate axes, + coordinate grids, and tick marks on axes (but note that these + are also available via the more comprehensive \htmlref{astGrid}{astGrid} function). + + The curve is transformed into graphical coordinate space for + plotting, so that a straight line in physical coordinates may + result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is + non-linear. Any discontinuities in the Mapping between physical + and graphical coordinates are catered for, as is any + clipping established using \htmlref{astClip}{astClip}. + } + \sstsynopsis{ + void astGridLine( AstPlot $*$this, int axis, const double start[], + double length ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + axis + }{ + The index of the Plot axis whose physical coordinate value is + to be varied along the length of the curve (all other + coordinates will remain fixed). This value should lie in the + range from 1 to the number of Plot axes (\htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + start + }{ + An array, with one element for each axis of the Plot, giving + the physical coordinates of the start of the curve. + } + \sstsubsection{ + length + }{ + The length of curve to be drawn, given as an increment along + the selected physical axis. This may be positive or negative. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No curve is drawn if the \texttt{"} start\texttt{"} array contains any + coordinates with the value AST\_\_BAD, nor if \texttt{"} length\texttt{"} has this value. + + \sstitem + An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astGrismMap +}{ + Create a GrismMap +}{ + \sstdescription{ + This function creates a new \htmlref{GrismMap}{GrismMap} and optionally initialises + its attributes. + + A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms + 1-dimensional coordinates using the spectral dispersion equation + described in FITS-WCS paper III \texttt{"} Representation of spectral + coordinates in FITS\texttt{"} . This describes the dispersion produced by + gratings, prisms and grisms. + + When initially created, the forward transformation of a GrismMap + transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength + values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is + linearly related to position on the detector. It is defined in FITS-WCS + paper III as \texttt{"} the offset on the detector from the point of intersection + of the camera axis, measured in units of the effective local length\texttt{"} . + The units in which wavelength values are expected or returned is + determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and + \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will + also be used for the wavelength values. + } + \sstsynopsis{ + AstGrismMap $*$astGrismMap( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new GrismMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGrismMap() + }{ + A pointer to the new GrismMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astHasAttribute +}{ + Test if an Object has a named attribute +}{ + \sstdescription{ + This function returns a boolean result (0 or 1) to indicate + whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name. + } + \sstsynopsis{ + int astHasAttribute( AstObject $*$this, const char $*$attrib ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the first Object. + } + \sstsubsection{ + attrib + }{ + Pointer to a string holding the + name of the attribute to be tested. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astHasAttribute() + }{ + One if the Object has the named attribute, otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any reason. + } + } +} +\sstroutine{ + astHasColumn +}{ + Returns a flag indicating if a column is present in a Table +}{ + \sstdescription{ + This function + returns a flag indicating if a named column exists in a \htmlref{Table}{Table}, for + instance, by having been added to to the Table using + \htmlref{astAddColumn}{astAddColumn}. + } + \sstsynopsis{ + int astHasColumn( AstTable $*$this, const char $*$column ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + column + }{ + The character string holding the upper case name of the column. Trailing + spaces are ignored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of + zero + is returned for if an error occurs. + } + } +} +\sstroutine{ + astHasParameter +}{ + Returns a flag indicating if a named global parameter is present in a Table +}{ + \sstdescription{ + This function + returns a flag indicating if a named parameter exists in a \htmlref{Table}{Table}, for + instance, by having been added to to the Table using + \htmlref{astAddParameter}{astAddParameter}. + } + \sstsynopsis{ + int astHasParameter( AstTable $*$this, const char $*$parameter ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + parameter + }{ + The character string holding the upper case name of the parameter. Trailing + spaces are ignored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of + zero + is returned for if an error occurs. + } + } +} +\sstroutine{ + astImport +}{ + Import an Object pointer to the current context +}{ + \sstdescription{ + This function + imports an \htmlref{Object}{Object} pointer that was created in a higher or lower + level context, into the current AST context. + This means that the pointer will be annulled when the current context + is ended (with \htmlref{astEnd}{astEnd}). + } + \sstsynopsis{ + void astImport( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Object pointer to be imported. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } +} +\sstroutine{ + astIntersect +}{ + Find the point of intersection between two geodesic curves +}{ + \sstdescription{ + This function + finds the coordinate values at the point of intersection between + two geodesic curves. Each curve is specified by two points on + the curve. It can only be used with 2-dimensional Frames. + + For example, in a basic \htmlref{Frame}{Frame}, it will find the point of + intersection between two straight lines. But for a \htmlref{SkyFrame}{SkyFrame} it + will find an intersection of two great circles. + } + \sstsynopsis{ + void astIntersect( AstFrame $*$this, const double a1[2], + const double a2[2], const double b1[2], + const double b2[2], double cross[2] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + a1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the + first point on the first geodesic curve. + } + \sstsubsection{ + a2 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute). This should contain the coordinates of a + second point on the first geodesic curve. It should not be + co-incident with the first point. + } + \sstsubsection{ + b1 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute). This should contain the coordinates of the + first point on the second geodesic curve. + } + \sstsubsection{ + b2 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute). This should contain the coordinates of a + second point on the second geodesic curve. It should not be + co-incident with the first point. + } + \sstsubsection{ + cross + }{ + An array of double, with one element for each Frame axis + in which the coordinates of the required intersection will + be returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For SkyFrames each curve will be a great circle, and in general + each pair of curves will intersect at two diametrically opposite + points on the sky. The returned position is the one which is + closest to point + \texttt{"} a1\texttt{"} . + + \sstitem + This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) + if any of the input coordinates has this value, or if the two + points defining either geodesic are co-incident, or if the two + curves do not intersect. + + \sstitem + The geodesic curve used by this function is the path of + shortest distance between two points, as defined by the + \htmlref{astDistance}{astDistance} function. + + \sstitem + An error will be reported if the Frame is not 2-dimensional. + } + } +} +\sstroutine{ + astInterval +}{ + Create a Interval +}{ + \sstdescription{ + This function creates a new \htmlref{Interval}{Interval} and optionally initialises its + attributes. + + A Interval is a \htmlref{Region}{Region} which represents upper and/or lower limits on + one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region + represented by the Interval, the point must satisfy all the + restrictions placed on all the axes. The point is outside the region + if it fails to satisfy any one of the restrictions. Each axis may have + either an upper limit, a lower limit, both or neither. If both limits + are supplied but are in reverse order (so that the lower limit is + greater than the upper limit), then the interval is an excluded + interval, rather than an included interval. + + At least one axis limit must be supplied. + + Note, The Interval class makes no allowances for cyclic nature of + some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} + should usually be used in these cases since this requires the user + to think about suitable upper and lower limits, + } + \sstsynopsis{ + AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[], + const double ubnd[], AstRegion $*$unc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. A deep + copy is taken of the supplied Frame. This means that any + subsequent changes made to the Frame using the supplied pointer + will have no effect the Region. + } + \sstsubsection{ + lbnd + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute) containing the lower limits on each axis. + Set a value to AST\_\_BAD to indicate that the axis has no lower + limit. + } + \sstsubsection{ + ubnd + }{ + An array of double, with one element for each Frame axis + (Naxes attribute) containing the upper limits on each axis. + Set a value to AST\_\_BAD to indicate that the axis has no upper + limit. + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with the boundary of the Interval being created. + The uncertainty in any point on the boundary of the Interval is found by + shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at + the boundary point being considered. The area covered by the + shifted uncertainty Region then represents the uncertainty in the + boundary position. The uncertainty is assumed to be the same for + all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Interval. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the Interval being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Interval. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astInterval() + }{ + A pointer to the new Interval. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astIntraMap +}{ + Create an IntraMap +}{ + \sstdescription{ + This function creates a new \htmlref{IntraMap}{IntraMap} and optionally initialises + its attributes. + + An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates + a privately-defined coordinate transformation function + (e.g. written in C) so that it may be used like any other AST + Mapping. This allows you to create Mappings that perform any + conceivable coordinate transformation. + + However, an IntraMap is intended for use within a single program + or a private suite of software, where all programs have access + to the same coordinate transformation functions (i.e. can be + linked against them). IntraMaps should not normally be stored in + datasets which may be exported for processing by other software, + since that software will not have the necessary transformation + functions available, resulting in an error. + + You must register any coordinate transformation functions to be + used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap. + } + \sstsynopsis{ + AstIntraMap $*$astIntraMap( const char $*$name, int nin, int nout, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + name + }{ + Pointer to a null-terminated string containing the name of + the transformation function to use (which should previously + have been registered using astIntraReg). This name is case + sensitive. All white space will be removed before use. + } + \sstsubsection{ + nin + }{ + The number of input coordinates. This must be compatible with + the number of input coordinates accepted by the + transformation function (as specified when this function was + registered using astIntraReg). + } + \sstsubsection{ + nout + }{ + The number of output coordinates. This must be compatible + with the number of output coordinates produced by the + transformation function (as specified when this function was + registered using astIntraReg). + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new IntraMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astIntraMap() + }{ + A pointer to the new IntraMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astIntraReg +}{ + Register a transformation function for use by an IntraMap +}{ + \sstdescription{ + This function registers a privately-defined coordinate + transformation function written in C so that it may be used to + create an \htmlref{IntraMap}{IntraMap}. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} + which encapsulates the C function so that it may be used like + any other AST Mapping. This allows you to create Mappings that + perform any conceivable coordinate transformation. + + Registration of relevant transformation functions is required + before using the \htmlref{astIntraMap}{astIntraMap} constructor function to create an + IntraMap or reading an external representation of an IntraMap + from a \htmlref{Channel}{Channel}. + } + \sstsynopsis{ + astIntraReg( const char $*$name, int nin, int nout, + void ($*$ tran)( AstMapping $*$, int, int, const double $*$[], + int, int, double $*$[] ), + unsigned int flags, const char $*$purpose, const char $*$author, + const char $*$contact ) + } + \sstparameters{ + \sstsubsection{ + name + }{ + Pointer to a null-terminated string containing a unique name + to be associated with the transformation function in order to + identify it. This name is case sensitive. All white space + will be removed before use. + } + \sstsubsection{ + nin + }{ + The number of input coordinates accepted by the + transformation function (i.e. the number of dimensions of the + space in which the input points reside). A value of AST\_\_ANY + may be given if the function is able to accommodate a + variable number of input coordinates. + } + \sstsubsection{ + nout + }{ + The number of output coordinates produced by the + transformation function (i.e. the number of dimensions of the + space in which the output points reside). A value of AST\_\_ANY + may be given if the function is able to produce a variable + number of output coordinates. + } + \sstsubsection{ + tran + }{ + Pointer to the transformation function to be registered. + This function should perform whatever coordinate + transformations are required and should have an interface + like \htmlref{astTranP}{astTranP} (q.v.). + } + \sstsubsection{ + flags + }{ + This value may be used to supply a set of flags which + describe the transformation function and which may affect the + behaviour of any IntraMap which uses it. Often, a value of + zero will be given here, but you may also supply the bitwise + OR of a set of flags as described in the \texttt{"} Transformation + Flags\texttt{"} section (below). + } + \sstsubsection{ + purpose + }{ + Pointer to a null-terminated string containing a short (one + line) textual comment to describe the purpose of the + transformation function. + } + \sstsubsection{ + author + }{ + Pointer to a null-terminated string containing the name of + the author of the transformation function. + } + \sstsubsection{ + contact + }{ + Pointer to a null-terminated string containing contact + details for the author of the transformation function + (e.g. an e-mail or WWW address). If any IntraMap which uses + this transformation function is exported as part of a dataset + to an external user who does not have access to the function, + then these contact details should allow them to obtain the + necessary code. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Beware that an external representation of an IntraMap (created + by writing it to a Channel) will not include the coordinate + transformation function which it uses, so will only refer to the + function by its name (as assigned using astIntraReg). + Consequently, the external representation cannot be utilised by + another program unless that program has also registered the same + transformation function with the same name using an identical + invocation of astIntraReg. If no such registration has been + performed, then attempting to read the external representation + will result in an error. + + \sstitem + You may use astIntraReg to register a transformation function + with the same name more than once, but only if the arguments + supplied are identical on each occasion (i.e there is no way of + changing things once a function has been successfully registered + under a given name, and attempting to do so will result in an + error). This feature simply allows registration to be performed + independently, but consistently, at several places within your + program, without having to check whether it has already been + done. + + \sstitem + If an error occurs in the transformation function, this may be + indicated by setting the AST error status to an error value + (using \htmlref{astSetStatus}{astSetStatus}) before it returns. This will immediately + terminate the current AST operation. The error value AST\_\_ITFER + is available for this purpose, but other values may also be used + (e.g. if you wish to distinguish different types of error). + } + } + \sstdiytopic{ + Transformation Flags + }{ + The following flags are defined in the ``ast.h\texttt{'} \texttt{'} header file and + allow you to provide further information about the nature of the + transformation function. Having selected the set of flags which + apply, you should supply the bitwise OR of their values as the + ``flags\texttt{'} \texttt{'} argument to astIntraReg. + + \sstitemlist{ + + \sstitem + AST\_\_NOFWD: If this flag is set, it indicates that the + transformation function does not implement a forward coordinate + transformation. In this case, any IntraMap which uses it will + have a \htmlref{TranForward}{TranForward} attribute value of zero and the + transformation function itself will not be invoked with its + ``forward\texttt{'} \texttt{'} argument set to a non-zero value. By default, it is + assumed that a forward transformation is provided. + + \sstitem + AST\_\_NOINV: If this flag is set, it indicates that the + transformation function does not implement an inverse coordinate + transformation. In this case, any IntraMap which uses it will + have a \htmlref{TranInverse}{TranInverse} attribute value of zero and the + transformation function itself will not be invoked with its + ``forward\texttt{'} \texttt{'} argument set to zero. By default, it is assumed + that an inverse transformation is provided. + + \sstitem + AST\_\_SIMPFI: You may set this flag if applying the + transformation function\texttt{'} s forward coordinate transformation, + followed immediately by the matching inverse transformation, + should always restore the original set of coordinates. It + indicates that AST may replace such a sequence of operations by + an identity Mapping (a \htmlref{UnitMap}{UnitMap}) if it is encountered while + simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). It is + not necessary that both transformations have actually been + implemented. + + \sstitem + AST\_\_SIMPIF: You may set this flag if applying the + transformation function\texttt{'} s inverse coordinate transformation, + followed immediately by the matching forward transformation, + should always restore the original set of coordinates. It + indicates that AST may replace such a sequence of operations by + an identity Mapping (a UnitMap) if it is encountered while + simplifying a compound Mapping (e.g. using astSimplify). It is + not necessary that both transformations have actually been + implemented. + } + } +} +\sstroutine{ + astInvert +}{ + Invert a Mapping +}{ + \sstdescription{ + This function inverts a \htmlref{Mapping}{Mapping} by reversing the boolean sense + of its \htmlref{Invert}{Invert} attribute. If this attribute is zero (the + default), the Mapping will transform coordinates in the way + specified when it was created. If it is non-zero, the input and + output coordinates will be inter-changed so that the direction + of the Mapping is reversed. This will cause it to display the + inverse of its original behaviour. + } + \sstsynopsis{ + void astInvert( AstMapping $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping. + } + } +} +\sstroutine{ + astIsA$<$Class$>$ +}{ + Test membership of a class by an Object +}{ + \sstdescription{ + This is a family of functions which test whether an \htmlref{Object}{Object} is a + member of the class called $<$\htmlref{Class}{Class}$>$, or of any class derived from + it. + } + \sstsynopsis{ + int astIsA$<$Class$>$( const Ast$<$Class$>$ $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + These functions apply to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astIsA$<$Class$>$() + }{ + One if the Object belongs to the class called $<$Class$>$ (or to a + class derived from it), otherwise zero. + } + } + \sstexamples{ + \sstexamplesubsection{ + member = astIsAFrame( obj ); + }{ + Tests whether Object \texttt{"} obj\texttt{"} is a member of the \htmlref{Frame}{Frame} class, or + of any class derived from a Frame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Every AST class provides a function (astIsA$<$Class$>$) of this + form, where $<$Class$>$ should be replaced by the class name. + + \sstitem + This function attempts to execute even if the AST error status + is set + on entry, although no further error report will be made + if it subsequently fails under these circumstances. + + \sstitem + A value of zero will be returned if this function should fail + for any reason. In particular, it will fail if the pointer + supplied does not identify an Object of any sort. + } + } +} +\sstroutine{ + astKeyMap +}{ + Create a KeyMap +}{ + \sstdescription{ + This function creates a new empty \htmlref{KeyMap}{KeyMap} and optionally initialises its + attributes. Entries can then be added to the KeyMap using the + \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$} and \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$} functions. + + The KeyMap class is used to store a set of values with associated keys + which identify the values. The keys are strings. These may be case + sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and + trailing spaces are ignored. The value associated with a key can be + integer (signed 4 and 2 byte, or unsigned 1 byte), floating point + (single or double precision), + void pointer, + character string or AST \htmlref{Object}{Object} pointer. Each + value can be a scalar or a one-dimensional vector. A KeyMap is + conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an + input into an output - the input is the key, and the output is the + value associated with the key. However, this is only a conceptual + similarity, and it should be noted that the KeyMap class inherits from + the Object class rather than the Mapping class. The methods of the + Mapping class cannot be used with a KeyMap. + } + \sstsynopsis{ + AstKeyMap $*$astKeyMap( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new KeyMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astKeyMap() + }{ + A pointer to the new KeyMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astLinearApprox +}{ + Obtain a linear approximation to a Mapping, if appropriate +}{ + \sstdescription{ + This function tests the forward coordinate transformation + implemented by a \htmlref{Mapping}{Mapping} over a given range of input coordinates. If + the transformation is found to be linear to a specified level of + accuracy, then an array of fit coefficients is returned. These + may be used to implement a linear approximation to the Mapping\texttt{'} s + forward transformation within the specified range of output coordinates. + If the transformation is not sufficiently linear, no coefficients + are returned. + } + \sstsynopsis{ + int astLinearApprox( AstMapping $*$this, const double $*$lbnd, + const double $*$ubnd, double tol, double $*$fit ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of doubles + containing the lower bounds of a box defined within the input + coordinate system of the Mapping. The number of elements in this + array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This + box should specify the region over which linearity is required. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of doubles + containing the upper bounds of the box specifying the region over + which linearity is required. + } + \sstsubsection{ + tol + }{ + The maximum permitted deviation from linearity, expressed as + a positive Cartesian displacement in the output coordinate + space of the Mapping. If a linear fit to the forward + transformation of the Mapping deviates from the true transformation + by more than this amount at any point which is tested, then no fit + coefficients will be returned. + } + \sstsubsection{ + fit + }{ + Pointer to an array of doubles + in which to return the co-efficients of the linear + approximation to the specified transformation. This array should + have at least \texttt{"} ( Nin $+$ 1 ) $*$ \htmlref{Nout}{Nout}\texttt{"} , elements. The first Nout elements + hold the constant offsets for the transformation outputs. The + remaining elements hold the gradients. So if the Mapping has 2 inputs + and 3 outputs the linear approximation to the forward transformation + is: + + X\_out = fit[0] $+$ fit[3]$*$X\_in $+$ fit[4]$*$Y\_in + + Y\_out = fit[1] $+$ fit[5]$*$X\_in $+$ fit[6]$*$Y\_in + + Z\_out = fit[2] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in + } + } + \sstreturnedvalue{ + \sstsubsection{ + astLinearApprox() + }{ + If the forward transformation is sufficiently linear, + a non-zero value is returned. Otherwise zero is returned + and the fit co-efficients are set to AST\_\_BAD. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function fits the Mapping\texttt{'} s forward transformation. To fit + the inverse transformation, the Mapping should be inverted using + \htmlref{astInvert}{astInvert} + before invoking this function. + + \sstitem + A value of zero + will be returned if this function is invoked + with the global error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astLock +}{ + Lock an Object for exclusive use by the calling thread +}{ + \sstdescription{ + The thread-safe public interface to AST is designed so that an + error is reported if any thread attempts to use an \htmlref{Object}{Object} that it + has not previously locked for its own exclusive use using this + function. When an Object is created, it is initially locked by the + thread that creates it, so newly created objects do not need to be + explicitly locked. However, if an Object pointer is passed to + another thread, the original thread must first unlock it (using + \htmlref{astUnlock}{astUnlock}) and the new thread must then lock it (using astLock) + before the new thread can use the Object. + + The \texttt{"} wait\texttt{"} parameter determines what happens if the supplied Object + is curently locked by another thread when this function is invoked. + } + \sstsynopsis{ + void astLock( AstObject $*$this, int wait ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be locked. + } + \sstsubsection{ + wait + }{ + If the Object is curently locked by another thread then this + function will either report an error or block. If a non-zero value + is supplied for \texttt{"} wait\texttt{"} , the calling thread waits until the object + is available for it to use. Otherwise, an error is reported and + the function returns immediately without locking the Object. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The \htmlref{astAnnul}{astAnnul} function is exceptional in that it can be used on + pointers for Objects that are not currently locked by the calling + thread. All other AST functions will report an error. + + \sstitem + The Locked object will belong to the current AST context. + + \sstitem + This function returns without action if the Object is already + locked by the calling thread. + + \sstitem + If simultaneous use of the same object is required by two or more + threads, \htmlref{astCopy}{astCopy} should be used to to produce a deep copy of + the Object for each thread. Each copy should then be unlocked by + the parent thread (i.e. the thread that created the copy), and then + locked by the child thread (i.e. the thread that wants to use the + copy). + + \sstitem + This function is only available in the C interface. + + \sstitem + This function returns without action if the AST library has + been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} + option was not specified when running the \texttt{"} configure\texttt{"} script). + } + } +} +\sstroutine{ + astLutMap +}{ + Create a LutMap +}{ + \sstdescription{ + This function creates a new \htmlref{LutMap}{LutMap} and optionally initialises + its attributes. + + A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms + 1-dimensional coordinates by using linear interpolation in a + lookup table. Each input coordinate value is first scaled to + give the index of an entry in the table by subtracting a + starting value (the input coordinate corresponding to the first + table entry) and dividing by an increment (the difference in + input coordinate value between adjacent table entries). + + The resulting index will usually contain a fractional part, so + the output coordinate value is then generated by interpolating + linearly between the appropriate entries in the table. If the + index lies outside the range of the table, linear extrapolation + is used based on the two nearest entries (i.e. the two entries + at the start or end of the table, as appropriate). + + If the lookup table entries increase or decrease monotonically, + then the inverse transformation may also be performed. + } + \sstsynopsis{ + AstLutMap $*$astLutMap( int nlut, const double lut[], + double start, double inc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nlut + }{ + The number of entries in the lookup table. This value must be + at least 2. + } + \sstsubsection{ + lut + }{ + An array containing the \texttt{"} nlut\texttt{"} + lookup table entries. + } + \sstsubsection{ + start + }{ + The input coordinate value which corresponds to the first lookup + table entry. + } + \sstsubsection{ + inc + }{ + The lookup table spacing (the increment in input coordinate + value between successive lookup table entries). This value + may be positive or negative, but must not be zero. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new LutMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astLutMap() + }{ + A pointer to the new LutMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the entries in the lookup table either increase or decrease + monotonically, then the new LutMap\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute will + have a value of one, indicating that the inverse transformation + can be performed. Otherwise, it will have a value of zero, so + that any attempt to use the inverse transformation will result + in an error. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astMapBox +}{ + Find a bounding box for a Mapping +}{ + \sstdescription{ + This function allows you to find the \texttt{"} bounding box\texttt{"} which just + encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping} + (using either its forward or inverse transformation). A typical + use might be to calculate the size of an image after being + transformed by a Mapping. + + The function works on one dimension at a time. When supplied + with the lower and upper bounds of a rectangular region (box) of + input coordinate space, it finds the lowest and highest values + taken by a nominated output coordinate within that + region. Optionally, it also returns the input coordinates where + these bounding values are attained. It should be used repeatedly + to obtain the extent of the bounding box in more than one + dimension. + } + \sstsynopsis{ + void astMapBox( AstMapping $*$this, + const double lbnd\_in[], const double ubnd\_in[], + int forward, int coord\_out, + double $*$lbnd\_out, double $*$ubnd\_out, + double xl[], double xu[] ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping. + } + \sstsubsection{ + lbnd\_in + }{ + Pointer to an array of double, with one element for each + Mapping input coordinate. This should contain the lower bound + of the input box in each input dimension. + } + \sstsubsection{ + ubnd\_in + }{ + Pointer to an array of double, with one element for each + Mapping input coordinate. This should contain the upper bound + of the input box in each input dimension. + + Note that it is permissible for the upper bound to be less + than the corresponding lower bound, as the values will simply + be swapped before use. + } + \sstsubsection{ + forward + }{ + If this value is non-zero, then the Mapping\texttt{'} s forward + transformation will be used to transform the input + box. Otherwise, its inverse transformation will be used. + + (If the inverse transformation is selected, then references + to \texttt{"} input\texttt{"} and \texttt{"} output\texttt{"} coordinates in this description + should be transposed. For example, the size of the \texttt{"} lbnd\_in\texttt{"} + and \texttt{"} ubnd\_in\texttt{"} arrays should match the number of output + coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout} + attribute. Similarly, the \texttt{"} coord\_out\texttt{"} parameter, below, + should nominate one of the Mapping\texttt{'} s input coordinates.) + } + \sstsubsection{ + coord\_out + }{ + The index of the output coordinate for which the lower and + upper bounds are required. This value should be at least one, + and no larger than the number of Mapping output coordinates. + } + \sstsubsection{ + lbnd\_out + }{ + Pointer to a double in which to return the lowest value taken + by the nominated output coordinate within the specified + region of input coordinate space. + } + \sstsubsection{ + ubnd\_out + }{ + Pointer to a double in which to return the highest value + taken by the nominated output coordinate within the specified + region of input coordinate space. + } + \sstsubsection{ + xl + }{ + An optional pointer to an array of double, with one element + for each Mapping input coordinate. If given, this array will + be filled with the coordinates of an input point (although + not necessarily a unique one) for which the nominated output + coordinate attains the lower bound value returned in + \texttt{"} $*$lbnd\_out\texttt{"} . + + If these coordinates are not required, a NULL pointer may be + supplied. + } + \sstsubsection{ + xu + }{ + An optional pointer to an array of double, with one element + for each Mapping input coordinate. If given, this array will + be filled with the coordinates of an input point (although + not necessarily a unique one) for which the nominated output + coordinate attains the upper bound value returned in + \texttt{"} $*$ubnd\_out\texttt{"} . + + If these coordinates are not required, a NULL pointer may be + supplied. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Any input points which are transformed by the Mapping to give + output coordinates containing the value AST\_\_BAD are regarded as + invalid and are ignored. They will make no contribution to + determining the output bounds, even although the nominated + output coordinate might still have a valid value at such points. + + \sstitem + An error will occur if the required output bounds cannot be + found. Typically, this might happen if all the input points + which the function considers turn out to be invalid (see + above). The number of points considered before generating such + an error is quite large, so this is unlikely to occur by + accident unless valid points are restricted to a very small + subset of the input coordinate space. + + \sstitem + The values returned via \texttt{"} lbnd\_out\texttt{"} , \texttt{"} ubnd\_out\texttt{"} , \texttt{"} xl\texttt{"} and \texttt{"} xu\texttt{"} + will be set to the value AST\_\_BAD if this function should fail + for any reason. Their initial values on entry will not be + altered if the function is invoked with the AST error status + set. + } + } +} +\sstroutine{ + astMapCopy +}{ + Copy entries from one KeyMap into another +}{ + \sstdescription{ + This function + copies all entries from one \htmlref{KeyMap}{KeyMap} into another. + } + \sstsynopsis{ + void astMapCopy( AstKeyMap $*$this, AstKeyMap $*$that ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the destination KeyMap. + } + \sstsubsection{ + that + }{ + Pointer to the source KeyMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Entries from the source KeyMap will replace any existing entries in + the destination KeyMap that have the same key. + + \sstitem + The one exception to the above rule is that if a source entry + contains a scalar KeyMap entry, and the destination contains a + scalar KeyMap entry with the same key, then the source KeyMap entry + will be copied into the destination KeyMap entry using this function, + rather than simply replacing the destination KeyMap entry. + + \sstitem + If the destination entry has a non-zero value for its \htmlref{MapLocked}{MapLocked} + attribute, then an error will be reported if the source KeyMap + contains any keys that do not already exist within the destination + KeyMap. + } + } +} +\sstroutine{ + astMapDefined +}{ + Check if a KeyMap contains a defined value for a key +}{ + \sstdescription{ + This function checks to see if a \htmlref{KeyMap}{KeyMap} contains a defined value for + a given key. If the key is present in the KeyMap but has an + undefined value it returns + zero (unlike \htmlref{astMapHasKey}{astMapHasKey} which would return non-zero). + } + \sstsynopsis{ + int astMapDefined( AstKeyMap $*$this, const char $*$key ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. The supplied string is converted to upper + case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapDefined() + }{ + A non-zero value + is returned if the requested key name is present in the KeyMap + and has a defined value. + } + } +} +\sstroutine{ + astMapGet0$<$X$>$ +}{ + Get a scalar value from a KeyMap +}{ + \sstdescription{ + This is a set of functions for retrieving a scalar value from a \htmlref{KeyMap}{KeyMap}. + You should replace $<$X$>$ in the generic function name + astMapGet0$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + The stored value is converted to the data type indiced by $<$X$>$ + before being returned (an error is reported if it is not possible to + convert the stored value to the requested data type). + } + \sstsynopsis{ + int astMapGet0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type $*$value ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. The supplied string is converted to upper + case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + value + }{ + A pointer to a buffer in which to return the requested value. + If the requested key is not found, or if it is found but has an + undefined value (see + \htmlref{astMapPutU}{astMapPutU}), + then the contents of the + buffer on entry to this function will be unchanged on exit. + For pointer types (\texttt{"} A\texttt{"} and \texttt{"} C\texttt{"} ), the buffer should be a suitable + pointer, and the address of this pointer should be supplied as the + \texttt{"} value\texttt{"} parameter. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapGet0$<$X$>$() + }{ + A non-zero value + is returned if the requested key name was found, and does not have + an undefined value (see + astMapPutU). Zero + is returned otherwise. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No error is reported if the requested key cannot be found in the + given KeyMap, but a + zero + value will be returned as the function value. The supplied buffer + will be returned unchanged. + + \sstitem + If the stored value is a vector value, then the first value in + the vector will be returned. + + \sstitem + A string pointer returned by astMapGet0C is guaranteed to remain valid + and the string to which it points will not be over-written for a + total of 50 successive invocations of this function. After this, + the memory containing the string may be re-used, so a copy of + the string should be made if it is needed for longer than this. The + calling code should never attempt to free the returned pointer + (for instance, using \htmlref{astFree}{astFree}). + + \sstitem + If the returned value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference + count is incremented by this call. Any subsequent changes made to + the Object using the returned pointer will be reflected in any + any other active pointers for the Object. The returned pointer + should be annulled using + \htmlref{astAnnul}{astAnnul} + when it is no longer needed. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + F: float + + \sstitem + D: double + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: Unsigned byte (i.e. word) + + } + For example, astMapGet0D would be used to get a \texttt{"} double\texttt{"} value, + while astMapGet0I would be used to get an \texttt{"} int\texttt{"} , etc. + } +} +\sstroutine{ + astMapGet1$<$X$>$ +}{ + Get a vector value from a KeyMap +}{ + \sstdescription{ + This is a set of functions for retrieving a vector value from a \htmlref{KeyMap}{KeyMap}. + You should replace $<$X$>$ in the generic function name + astMapGet1$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + The stored value is converted to the data type indiced by $<$X$>$ + before being returned (an error is reported if it is not possible to + convert the stored value to the requested data type). + Note, the astMapGet1C function has an extra parameter \texttt{"} l\texttt{"} which + specifies the maximum length of each string to be stored in the + \texttt{"} value\texttt{"} buffer (see the \texttt{"} astMapGet1C\texttt{"} section below). + } + \sstsynopsis{ + int astMapGet1$<$X$>$( AstKeyMap $*$this, const char $*$key, int mxval, + int $*$nval, $<$X$>$type $*$value ) + int astMapGet1C( AstKeyMap $*$this, const char $*$key, int l, int mxval, + int $*$nval, const char $*$value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + mxval + }{ + The number of elements in the + \texttt{"} value\texttt{"} array. + } + \sstsubsection{ + nval + }{ + The address of an integer in which to put the + number of elements stored in the + \texttt{"} value\texttt{"} array. + Any unused elements of the array are left unchanged. + } + \sstsubsection{ + value + }{ + A pointer to an array in which to return the requested values. + If the requested key is not found, or if it is found but has an + undefined value (see + \htmlref{astMapPutU}{astMapPutU}), + then the contents of the + buffer on entry to this function will be unchanged on exit. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapGet1$<$X$>$() + }{ + A non-zero value + is returned if the requested key name was found, and does not have + an undefined value (see + astMapPutU). Zero + is returned otherwise. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No error is reported if the requested key cannot be found in the + given KeyMap, but a + zero + value will be returned as the function value. The supplied array + will be returned unchanged. + + \sstitem + If the stored value is a scalar value, then the value will be + returned in the first element of the supplied array, and + \texttt{"} nval\texttt{"} + will be returned set to 1. + } + } + \sstdiytopic{ + astMapGet1C + }{ + The \texttt{"} value\texttt{"} buffer supplied to the astMapGet1C function should be a + pointer to a character array with \texttt{"} mxval$*$l\texttt{"} elements, where \texttt{"} l\texttt{"} is + the maximum length of a string to be returned. The value of \texttt{"} l\texttt{"} + should be supplied as an extra parameter following \texttt{"} key\texttt{"} when + invoking astMapGet1C, and should include space for a terminating + null character. + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: Unsigned byte (i.e. char) + + } + For example, astMapGet1D would be used to get \texttt{"} double\texttt{"} values, while + astMapGet1I would be used to get \texttt{"} int\texttt{"} values, etc. For D or I, the + supplied \texttt{"} value\texttt{"} parameter should be a pointer to an array of doubles + or ints, with \texttt{"} mxval\texttt{"} elements. For C, the supplied \texttt{"} value\texttt{"} parameter + should be a pointer to a character string with \texttt{"} mxval$*$l\texttt{"} elements. + For A, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to an + array of AstObject pointers. + } +} +\sstroutine{ + astMapGetElem$<$X$>$ +}{ + Get a single element of a vector value from a KeyMap +}{ + \sstdescription{ + This is a set of functions for retrieving a single element of a vector + value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name + astMapGetElem$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + The stored value is converted to the data type indiced by $<$X$>$ + before being returned (an error is reported if it is not possible to + convert the stored value to the requested data type). + Note, the astMapGetElemC function has an extra parameter \texttt{"} l\texttt{"} which + specifies the maximum length of the string to be stored in the + \texttt{"} value\texttt{"} buffer (see the \texttt{"} astMapGetElemC\texttt{"} section below). + } + \sstsynopsis{ + int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, + $<$X$>$type $*$value ) + int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem, + char $*$value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + elem + }{ + The index of the required vector element, starting at + zero. + An error will be reported if the value is outside the range of + the vector. + } + \sstsubsection{ + value + }{ + A pointer to a buffer in which to return the requested value. + If the requested key is not found, or if it is found but has an + undefined value (see + \htmlref{astMapPutU}{astMapPutU}), + then the contents of the + buffer on entry to this function will be unchanged on exit. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapGetElem$<$X$>$() + }{ + A non-zero value + is returned if the requested key name was found, and does not have + an undefined value (see + astMapPutU). Zero + is returned otherwise. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No error is reported if the requested key cannot be found in the + given KeyMap, or if it has an undefined value, but a + zero + value will be returned as the function value. + } + } + \sstdiytopic{ + astMapGetElemC + }{ + The \texttt{"} value\texttt{"} buffer supplied to the astMapGetElemC function should be a + pointer to a character array with \texttt{"} l\texttt{"} elements, where \texttt{"} l\texttt{"} is the + maximum length of the string to be returned. The value of \texttt{"} l\texttt{"} + should be supplied as an extra parameter following \texttt{"} key\texttt{"} when + invoking astMapGetElemC, and should include space for a terminating + null character. + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name + astMapGetElem$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: Unsigned byte (i.e. char) + + } + For example, astMapGetElemD would be used to get a \texttt{"} double\texttt{"} value, while + astMapGetElemI would be used to get an \texttt{"} int\texttt{"} value, etc. For D or I, the + supplied \texttt{"} value\texttt{"} parameter should be a pointer to a double or int. For + C, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a character + string with \texttt{"} l\texttt{"} elements. For A, the supplied \texttt{"} value\texttt{"} parameter should + be a pointer to an AstObject pointer. + } +} +\sstroutine{ + astMapHasKey +}{ + Check if an entry with a given key exists in a KeyMap +}{ + \sstdescription{ + This function returns a flag indicating if the \htmlref{KeyMap}{KeyMap} contains an + entry with the given key. + } + \sstsynopsis{ + int astMapHasKey( AstKeyMap $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the KeyMap entry. Trailing spaces are + ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapHasKey() + }{ + Non-zero if the key was found, and zero otherwise. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A non-zero function value + is returned if the key exists but has an undefined value (that is, + the returned value does not depend on whether the entry has a + defined value or not). See also + \htmlref{astMapDefined}{astMapDefined}, which returns zero in such a case. + + \sstitem + A function value of + zero + will be returned if an error has already occurred, or if this + function should fail for any reason. + } + } +} +\sstroutine{ + astMapKey +}{ + Get the key at a given index within the KeyMap +}{ + \sstdescription{ + This function returns a string holding the key for the entry with + the given index within the \htmlref{KeyMap}{KeyMap}. + + This function is intended primarily as a means of iterating round all + the elements in a KeyMap. For this purpose, the number of entries in + the KeyMap should first be found using + \htmlref{astMapSize}{astMapSize} + and this function should then be called in a loop, with the index + value going from + zero to one less than the size of the KeyMap. + The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy} + attribute. + } + \sstsynopsis{ + const char $*$astMapKey( AstKeyMap $*$this, int index ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + index + }{ + The index into the KeyMap. The first entry has index + zero, and the last has index \texttt{"} size-1\texttt{"} , where \texttt{"} size\texttt{"} is the value + returned by the astMapSize function. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapKey() + }{ + A pointer to a null-terminated string containing the key. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned pointer is guaranteed to remain valid and the + string to which it points will not be over-written for a total + of 50 successive invocations of this function. After this, the + memory containing the string may be re-used, so a copy of the + string should be made if it is needed for longer than this. + + \sstitem + A NULL pointer will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astMapLenC +}{ + Get the number of characters in a character entry in a KeyMap +}{ + \sstdescription{ + This function returns the minimum length which a character variable + which must have in order to be able to store a specified entry in + the supplied \htmlref{KeyMap}{KeyMap}. If the named entry is a vector entry, then the + returned value is the length of the longest element of the vector + value. + } + \sstsynopsis{ + int astMapLenC( AstKeyMap $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the KeyMap entry. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapLenC() + }{ + The length (i.e. number of characters) of the longest formatted + value associated with the named entry. + This does not include the trailing null character. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A function value of zero will be returned without error if the + named entry cannot be formatted as a character string. + + \sstitem + A function value of zero will be returned if an error has already + occurred, or if this function should fail for any reason. + } + } +} +\sstroutine{ + astMapLength +}{ + Get the vector length of an entry in a KeyMap +}{ + \sstdescription{ + This function returns the vector length of a named entry in a \htmlref{KeyMap}{KeyMap}, + (that is, how many values are associated with the entry). + } + \sstsynopsis{ + int astMapLength( AstKeyMap $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the KeyMap entry. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapLength() + }{ + The length of the entry. One for a scalar, greater than one for + a vector. A value of zero is returned if the KeyMap does not + contain the named entry. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A function value of zero will be returned if an error has already + occurred, or if this function should fail for any reason. + } + } +} +\sstroutine{ + astMapPut0$<$X$>$ +}{ + Add a scalar value to a KeyMap +}{ + \sstdescription{ + This is a set of functions + for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a + function + which matches the data type of the data you wish to add to the KeyMap + by replacing $<$X$>$ in the generic + function name astMapPut0$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + } + \sstsynopsis{ + void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value, + const char $*$comment ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap in which to store the supplied value. + } + \sstsubsection{ + key + }{ + A character string to be stored with the value, which can later + be used to identify the value. Trailing spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + value + }{ + The value to be stored. The data type of this value should match the + 1-character type code appended to the + function name (e.g. if you are using astMapPut0A, the type of this + value should be \texttt{"} pointer to AstObject\texttt{"} ). + } + \sstsubsection{ + comment + }{ + A pointer to a null-terminated comment string to be stored with the + value. A NULL pointer may be supplied, in which case no comment is + stored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the supplied key is already in use in the KeyMap, the new value + will replace the old value. + + \sstitem + If the stored value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference + count is incremented by this call. Any subsequent changes made to + the Object using the returned pointer will be reflected in any + any other active pointers for the Object, including any obtained + later using + astMapget0A. + The reference count for the Object will be decremented when the + KeyMap is destroyed, or the entry is removed or over-written with a + different pointer. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name astMapPut0$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: unsigned byte (i.e. unsigned char) + + } + For example, astMapPut0D would be used to store a \texttt{"} double\texttt{"} value, + while astMapPut0I would be used to store an \texttt{"} int\texttt{"} , etc. + + Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"} pointers cannot be + written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if + this is attempted. + } +} +\sstroutine{ + astMapPut1$<$X$>$ +}{ + Add a vector value to a KeyMap +}{ + \sstdescription{ + This is a set of functions + for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a + function + which matches the data type of the data you wish to add to the KeyMap + by replacing $<$X$>$ in the generic + function name astMapPut1$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + } + \sstsynopsis{ + void astMapPut1$<$X$>$( AstKeyMap $*$this, const char $*$key, int size, + const $<$X$>$type value[], const char $*$comment ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap in which to store the supplied values. + } + \sstsubsection{ + key + }{ + A character string to be stored with the values, which can later + be used to identify the values. Trailing spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + size + }{ + The number of elements in the supplied array of values. + } + \sstsubsection{ + value + }{ + The array of values to be stored. The data type of this value should + match the 1-character type code appended to the + function name (e.g. if you are using astMapPut1A, the type of this + value should be \texttt{"} array of pointers to AstObject\texttt{"} ). + } + \sstsubsection{ + comment + }{ + A pointer to a null-terminated comment string to be stored with the + values. A NULL pointer may be supplied, in which case no comment is + stored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the supplied key is already in use in the KeyMap, the new values + will replace the old values. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name astMapPut1$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: Unsigned byte (i.e. char) + + } + For example, astMapPut1D would be used to store \texttt{"} double\texttt{"} values, + while astMapPut1I would be used to store \texttt{"} int\texttt{"} , etc. + + Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"} pointers cannot be + written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if + this is attempted. + } +} +\sstroutine{ + astMapPutElem$<$X$>$ +}{ + Put a value into an element of a vector value in a KeyMap +}{ + \sstdescription{ + This is a set of functions for storing a value in a single element of + a vector value in a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic + function name + astMapPutElem$<$X$>$ + by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"} + section below for the code appropriate to each supported data type). + The supplied value is converted from the data type indicated by $<$X$>$ + to the data type of the KeyMap entry before being stored (an error + is reported if it is not possible to convert the value to the + required data type). + } + \sstsynopsis{ + void astMapPutElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, + $<$X$>$type $*$value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + elem + }{ + The index of the vector element to modify, starting at + zero. + } + \sstsubsection{ + value + }{ + The value to store. + } + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + If the + \texttt{"} elem\texttt{"} + index is outside the range of the vector, the length of + the vector will be increased by one element and the supplied + value will be stored at the end of the vector in the new element. + } + \sstsubsection{ + \htmlref{Table}{Table} + }{ + If the + \texttt{"} elem\texttt{"} + index is outside the range of the vector, an error will be + reported. The number of elements in each cell of a column is + specified when the column is created using + \htmlref{astAddColumn}{astAddColumn}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the entry originally holds a scalar value, it will be treated + like a vector entry of length 1. + + \sstitem + If the specified key cannot be found in the given KeyMap, or is + found but has an undefined value, a new + vector entry with the given name, and data type implied by $<$X$>$, is + created and the supplied value is stored in its first entry. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate + function, you should replace $<$X$>$ in the generic function name + astMapPutElem$<$X$>$ + with a 1-character data type code, so as to match the data type $<$X$>$type + of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + C: \texttt{"} const\texttt{"} pointer to null terminated character string + + \sstitem + A: Pointer to AstObject + + \sstitem + P: Generic \texttt{"} void $*$\texttt{"} pointer + + \sstitem + S: short int + + \sstitem + B: Unsigned byte (i.e. char) + + } + For example, astMapPutElemD would be used to put a \texttt{"} double\texttt{"} value, while + astMapPutElemI would be used to put an \texttt{"} int\texttt{"} value, etc. For D or I, the + supplied \texttt{"} value\texttt{"} parameter should be a double or int. For + C, the supplied \texttt{"} value\texttt{"} parameter should be a pointer to a character + string. For A, the supplied \texttt{"} value\texttt{"} parameter should be an AstObject + pointer. + } +} +\sstroutine{ + astMapPutU +}{ + Add an entry to a KeyMap with an undefined value +}{ + \sstdescription{ + This function + adds a new entry to a \htmlref{KeyMap}{KeyMap}, but no value is stored with the + entry. The entry therefore has a special data type represented by + symbolic constant AST\_\_UNDEFTYPE. + + An example use is to add entries with undefined values to a KeyMap + prior to locking them with the \htmlref{MapLocked}{MapLocked} attribute. Such entries + can act as placeholders for values that can be added to the KeyMap + later. + } + \sstsynopsis{ + void astMapPutU( AstKeyMap $*$this, const char $*$key, const char $*$comment ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap in which to store the supplied value. + } + \sstsubsection{ + key + }{ + A character string to be stored with the value, which can later + be used to identify the value. Trailing spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + comment + }{ + A pointer to a null-terminated comment string to be stored with the + value. A NULL pointer may be supplied, in which case no comment is + stored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the supplied key is already in use in the KeyMap, the value + associated with the key will be removed. + } + } +} +\sstroutine{ + astMapRegion +}{ + Transform a Region into a new Frame using a given Mapping +}{ + \sstdescription{ + This function returns a pointer to a new \htmlref{Region}{Region} which corresponds to + supplied Region described by some other specified coordinate system. A + \htmlref{Mapping}{Mapping} is supplied which transforms positions between the old and new + coordinate systems. The new Region may not be of the same class as + the original region. + } + \sstsynopsis{ + AstRegion $*$astMapRegion( AstRegion $*$this, AstMapping $*$map, + AstFrame $*$frame ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + map + }{ + Pointer to a Mapping which transforms positions from the + coordinate system represented by the supplied Region to the + coordinate system specified by + \texttt{"} frame\texttt{"} . + The supplied Mapping should define both forward and inverse + transformations, and these transformations should form a genuine + inverse pair. That is, transforming a position using the forward + transformation and then using the inverse transformation should + produce the original input position. Some Mapping classes (such + as \htmlref{PermMap}{PermMap}, \htmlref{MathMap}{MathMap}, \htmlref{SphMap}{SphMap}) can result in Mappings for which this + is not true. + } + \sstsubsection{ + frame + }{ + Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which + the new Region is required. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapRegion() + }{ + A pointer to a new Region. This Region will represent the area + within the coordinate system specified by + \texttt{"} frame\texttt{"} + which corresponds to the supplied Region. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The uncertainty associated with the supplied Region is modified + using the supplied Mapping. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astMapRemove +}{ + Removed a named entry from a KeyMap +}{ + \sstdescription{ + This function + removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the + KeyMap does not contain the specified key. + } + \sstsynopsis{ + void astMapRemove( AstKeyMap $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the value to be retrieved. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } +} +\sstroutine{ + astMapRename +}{ + Rename an existing KeyMap entry +}{ + \sstdescription{ + This function + associated a new key with an existing entry in a \htmlref{KeyMap}{KeyMap}. It returns + without action if the oldkey does not exist in the KeyMap. + } + \sstsynopsis{ + void astMapRename( AstKeyMap $*$this, const char $*$oldkey, const char $*$newkey ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + oldkey + }{ + The character string identifying the entry to be renamed. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + \sstsubsection{ + newkey + }{ + The new character string to associated with the renamed entry. + Trailing spaces are ignored. + The supplied string is converted to upper case before use if the + KeyCase attribute is currently set to zero. + } + } +} +\sstroutine{ + astMapSize +}{ + Get the number of entries in a KeyMap +}{ + \sstdescription{ + This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}. + } + \sstsynopsis{ + int astMapSize( AstKeyMap $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapSize() + }{ + The number of entries in the KeyMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A function value of zero will be returned if an error has already + occurred, or if this function should fail for any reason. + } + } +} +\sstroutine{ + astMapSplit +}{ + Split a Mapping up into parallel component Mappings +}{ + \sstdescription{ + This function + creates a new \htmlref{Mapping}{Mapping} which connects specified inputs within a + supplied Mapping to the corresponding outputs of the supplied Mapping. + This is only possible if the specified inputs correspond to some + subset of the Mapping outputs. That is, there must exist a subset of + the Mapping outputs for which each output depends only on the selected + Mapping inputs, and not on any of the inputs which have not been + selected. Also, any output which is not in this subset must not depend + on any of the selected inputs. If these conditions are not met by the + supplied Mapping, then + a NULL + Mapping pointer is returned. + } + \sstsynopsis{ + void astMapSplit( AstMapping $*$this, int nin, const int $*$in, int $*$out, + AstMapping $*$$*$map ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be split. + } + \sstsubsection{ + nin + }{ + The number of inputs to pick from \texttt{"} this\texttt{"} . + } + \sstsubsection{ + in + }{ + Pointer to an + array holding the indices within the supplied Mapping of the inputs + which are to be picked from the Mapping. + This array should have \texttt{"} nin\texttt{"} elements. + If \texttt{"} \htmlref{Nin}{Nin}\texttt{"} is the number of inputs of the supplied Mapping, then each + element should have a value in the range 1 to Nin. + } + \sstsubsection{ + out + }{ + Pointer to an + array in which to return the indices of the outputs of the supplied + Mapping which are fed by the picked inputs. A value of one is + used to refer to the first Mapping output. The supplied array should + have a length at least equal to the number of outputs in the + supplied Mapping. The number of values stored in the array on + exit will equal the number of outputs in the returned Mapping. + The i\texttt{'} th element in the returned array holds the index within + the supplied Mapping which corresponds to the i\texttt{'} th output of + the returned Mapping. + } + \sstsubsection{ + map + }{ + Address of a location at which to return a pointer to the + returned Mapping. This Mapping will have + \texttt{"} nin\texttt{"} inputs (the number of outputs may be different to \texttt{"} nin\texttt{"} ). NULL + is returned if the supplied Mapping has no subset of outputs which + depend only on the selected inputs. The returned Mapping is a + deep copy of the required parts of the supplied Mapping. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If this + function + is invoked with the global error status set, or if it should fail for + any reason, then + a NULL value + will be returned for + the \texttt{"} map\texttt{"} pointer. + } + } +} +\sstroutine{ + astMapType +}{ + Get the data type of an entry in a KeyMap +}{ + \sstdescription{ + This function returns a value indicating the data type of a + named entry in a \htmlref{KeyMap}{KeyMap}. This is the data type which was used when the + entry was added to the KeyMap. + } + \sstsynopsis{ + int astMapType( AstKeyMap $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the KeyMap. + } + \sstsubsection{ + key + }{ + The character string identifying the KeyMap entry. Trailing + spaces are ignored. + The supplied string is converted to upper case before use if the + \htmlref{KeyCase}{KeyCase} attribute is currently set to zero. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMapType() + }{ + One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for + short int), + AST\_\_BYTETYPE (for unsigned bytes + \sstitemlist{ + + \sstitem + i.e. unsigned chars + ) AST\_\_DOUBLETYPE (for double + precision floating point), AST\_\_FLOATTYPE (for single + precision floating point), AST\_\_STRINGTYPE (for character string), + AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for + arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values + created by + \htmlref{astMapPutU}{astMapPutU}). + AST\_\_BADTYPE is returned if the supplied key is not found in the KeyMap. + } + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A function value of AST\_\_BADTYPE will be returned if an error has + already occurred, or if this function should fail for any reason. + } + } +} +\sstroutine{ + astMark +}{ + Draw a set of markers for a Plot +}{ + \sstdescription{ + This function draws a set of markers (symbols) at positions + specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The + positions are transformed into graphical coordinates to + determine where the markers should appear within the plotting + area. + } + \sstsynopsis{ + void astMark( AstPlot $*$this, int nmark, int ncoord, int indim, + const double $*$in, int type ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + nmark + }{ + The number of markers to draw. This may be zero, in which + case nothing will be drawn. + } + \sstsubsection{ + ncoord + }{ + The number of coordinates being supplied for each mark + (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as + given by its \htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + indim + }{ + The number of elements along the second dimension of the \texttt{"} in\texttt{"} + array (which contains the marker coordinates). This value is + required so that the coordinate values can be correctly + located if they do not entirely fill this array. The value + given should not be less than \texttt{"} nmark\texttt{"} . + } + \sstsubsection{ + in + }{ + The address of the first element of a 2-dimensional array of + shape \texttt{"} [ncoord][indim]\texttt{"} giving the + physical coordinates of the points where markers are to be + drawn. These should be stored such that the value of + coordinate number \texttt{"} coord\texttt{"} for input mark number \texttt{"} mark\texttt{"} is + found in element \texttt{"} in[coord][mark]\texttt{"} . + } + \sstsubsection{ + type + }{ + A value specifying the type (e.g. shape) of marker to be + drawn. The set of values which may be used (and the shapes + that will result) is determined by the underlying graphics + system. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Markers are not drawn at positions which have any coordinate + equal to the value AST\_\_BAD (or where the transformation into + graphical coordinates yields coordinates containing the value + AST\_\_BAD). + + \sstitem + If any marker position is clipped (see \htmlref{astClip}{astClip}), then the + entire marker is not drawn. + + \sstitem + An error results if the base Frame of the Plot is not 2-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astMask$<$X$>$ +}{ + Mask a region of a data grid +}{ + \sstdescription{ + This is a set of functions for masking out regions within gridded data + (e.g. an image). The functions modifies a given data grid by + assigning a specified value to all samples which are inside (or outside + if \texttt{"} inside\texttt{"} is zero) + the specified \htmlref{Region}{Region}. + + You should use a masking function which matches the numerical + type of the data you are processing by replacing $<$X$>$ in + the generic function name astMask$<$X$>$ by an appropriate 1- or + 2-character type code. For example, if you are masking data + with type \texttt{"} float\texttt{"} , you should use the function astMaskF (see + the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to + other numerical types). + } + \sstsynopsis{ + int astMask$<$X$>$( AstRegion $*$this, AstMapping $*$map, int inside, int ndim, + const int lbnd[], const int ubnd[], $<$Xtype$>$ in[], + $<$Xtype$>$ val ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to a Region. + } + \sstsubsection{ + map + }{ + Pointer to a \htmlref{Mapping}{Mapping}. The forward transformation should map + positions in the coordinate system of the supplied Region + into pixel coordinates as defined by the + \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} parameters. A NULL pointer + can be supplied if the coordinate system of the supplied Region + corresponds to pixel coordinates. This is equivalent to + supplying a \htmlref{UnitMap}{UnitMap}. + + The number of inputs for this Mapping (as given by its \htmlref{Nin}{Nin} attribute) + should match the number of axes in the supplied Region (as given + by the \htmlref{Naxes}{Naxes} attribute of the Region). + The number of outputs for the Mapping (as given by its \htmlref{Nout}{Nout} attribute) + should match the number of + grid dimensions given by the value of \texttt{"} ndim\texttt{"} + below. + } + \sstsubsection{ + inside + }{ + A boolean value which indicates which pixel are to be masked. If + a non-zero value + is supplied, then all grid pixels with centres inside the supplied + Region are assigned the value given by + \texttt{"} val\texttt{"} , + and all other pixels are left unchanged. If + zero + is supplied, then all grid pixels with centres not inside the supplied + Region are assigned the value given by + \texttt{"} val\texttt{"} , + and all other pixels are left unchanged. Note, the \htmlref{Negated}{Negated} + attribute of the Region is used to determine which pixel are + inside the Region and which are outside. So the inside of a Region + which has not been negated is the same as the outside of the + corresponding negated Region. + + For types of Region such as \htmlref{PointList}{PointList} which have zero volume, + pixel centres will rarely fall exactly within the Region. For + this reason, the inclusion criterion is changed for zero-volume + Regions so that pixels are included (or excluded) if any part of + the Region passes through the pixel. For a PointList, this means + that pixels are included (or excluded) if they contain at least + one of the points listed in the PointList. + } + \sstsubsection{ + ndim + }{ + The number of dimensions in the input grid. This should be at + least one. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre. + } + \sstsubsection{ + in + }{ + Pointer to an array, with one element for each pixel in the + input grid, containing the data to be masked. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astMaskF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + + On exit, the samples specified by + \texttt{"} inside\texttt{"} are set to the value of \texttt{"} val\texttt{"} . + All other samples are left unchanged. + } + \sstsubsection{ + val + }{ + This argument should have the same type as the elements of + the \texttt{"} in\texttt{"} array. It specifies the value used to flag the + masked data (see + \texttt{"} inside\texttt{"} ). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMask$<$X$>$() + }{ + The number of pixels to which a value of + \texttt{"} badval\texttt{"} + has been assigned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero will be returned if this function is invoked + with the global error status set, or if it should fail for any + reason. + + \sstitem + An error will be reported if the overlap of the Region and + the array cannot be determined. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate masking function, you should + replace $<$X$>$ in the generic function name astMask$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + L: long int + + \sstitem + UL: unsigned long int + + \sstitem + I: int + + \sstitem + UI: unsigned int + + \sstitem + S: short int + + \sstitem + US: unsigned short int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astMaskD would be used to process \texttt{"} double\texttt{"} + data, while astMaskS would be used to process \texttt{"} short int\texttt{"} + data, etc. + } +} +\sstroutine{ + astMatchAxes +}{ + Find any corresponding axes in two Frames +}{ + \sstdescription{ + This function looks for corresponding axes within two supplied + Frames. An array of integers is returned that contains an element + for each axis in the second supplied \htmlref{Frame}{Frame}. An element in this array + will be set to zero if the associated axis within the second Frame + has no corresponding axis within the first Frame. Otherwise, it + will be set to the index (a non-zero positive integer) of the + corresponding axis within the first supplied Frame. + } + \sstsynopsis{ + void astMatchAxes( AstFrame $*$frm1, AstFrame $*$frm2, int $*$axes ) + } + \sstparameters{ + \sstsubsection{ + frm1 + }{ + Pointer to the first Frame. + } + \sstsubsection{ + frm2 + }{ + Pointer to the second Frame. + } + \sstsubsection{ + axes + }{ + Pointer to an + integer array in which to return the indices of the axes (within + the first Frame) that correspond to each axis within the second + Frame. \htmlref{Axis}{Axis} indices start at 1. A value of zero will be stored + in the returned array for each axis in the second Frame that has + no corresponding axis in the first Frame. + + The number of elements in this array must be greater than or + equal to the number of axes in the second Frame. + } + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + This function applies to all Frames. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Corresponding axes are identified by the fact that a \htmlref{Mapping}{Mapping} can + be found between them using + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}. + Thus, \texttt{"} corresponding axes\texttt{"} are not necessarily identical. For + instance, \htmlref{SkyFrame}{SkyFrame} axes in two Frames will match even if they + describe different celestial coordinate systems + } + } +} +\sstroutine{ + astMathMap +}{ + Create a MathMap +}{ + \sstdescription{ + This function creates a new \htmlref{MathMap}{MathMap} and optionally initialises its + attributes. + + A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward + and/or inverse transformation functions using arithmetic operations + and mathematical functions similar to those available in C. The + MathMap interprets these functions at run-time, whenever its forward + or inverse transformation is required. Because the functions are not + compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to + describe coordinate transformations in a transportable manner. A + MathMap therefore provides a flexible way of defining new types of + Mapping whose descriptions may be stored as part of a dataset and + interpreted by other programs. + } + \sstsynopsis{ + AstMathMap $*$astMathMap( int nin, int nout, + int nfwd, const char $*$fwd[], + int ninv, const char $*$inv[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nin + }{ + Number of input variables for the MathMap. This determines the + value of its \htmlref{Nin}{Nin} attribute. + } + \sstsubsection{ + nout + }{ + Number of output variables for the MathMap. This determines the + value of its \htmlref{Nout}{Nout} attribute. + } + \sstsubsection{ + nfwd + }{ + The number of forward transformation functions being supplied. + This must be at least equal to \texttt{"} nout\texttt{"} , but may be increased to + accommodate any additional expressions which define intermediate + variables for the forward transformation (see the \texttt{"} Calculating + Intermediate Values\texttt{"} section below). + } + \sstsubsection{ + fwd + }{ + An array (with \texttt{"} nfwd\texttt{"} elements) of pointers to null terminated strings + which contain the expressions defining the forward transformation. + The syntax of these expressions is described below. + } + \sstsubsection{ + ninv + }{ + The number of inverse transformation functions being supplied. + This must be at least equal to \texttt{"} nin\texttt{"} , but may be increased to + accommodate any additional expressions which define intermediate + variables for the inverse transformation (see the \texttt{"} Calculating + Intermediate Values\texttt{"} section below). + } + \sstsubsection{ + inv + }{ + An array (with \texttt{"} ninv\texttt{"} elements) of pointers to null terminated strings + which contain the expressions defining the inverse transformation. + The syntax of these expressions is described below. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new MathMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMathMap() + }{ + A pointer to the new MathMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The sequence of numbers produced by the random number functions + available within a MathMap is normally unpredictable and different for + each MathMap. However, this behaviour may be controlled by means of + the MathMap\texttt{'} s \htmlref{Seed}{Seed} attribute. + + \sstitem + Normally, compound Mappings (CmpMaps) which involve MathMaps will + not be subject to simplification (e.g. using \htmlref{astSimplify}{astSimplify}) because AST + cannot know how different MathMaps will interact. However, in the + special case where a MathMap occurs in series with its own inverse, + then simplification may be possible. Whether simplification does, in + fact, occur under these circumstances is controlled by the MathMap\texttt{'} s + \htmlref{SimpFI}{SimpFI} and \htmlref{SimpIF}{SimpIF} attributes. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Defining Transformation Functions + }{ + A MathMap\texttt{'} s transformation functions are supplied as a set of + expressions in an array of character strings. Normally you would + supply the same number of expressions for the forward transformation, + via the \texttt{"} fwd\texttt{"} parameter, as there are output variables (given by the + MathMap\texttt{'} s Nout attribute). For instance, if Nout is 2 you might use: + \sstitemlist{ + + \sstitem + \texttt{"} r = sqrt( x $*$ x $+$ y $*$ y )\texttt{"} + + \sstitem + \texttt{"} theta = atan2( y, x )\texttt{"} + + } + which defines a transformation from Cartesian to polar + coordinates. Here, the variables that appear on the left of each + expression (\texttt{"} r\texttt{"} and \texttt{"} theta\texttt{"} ) provide names for the output variables + and those that appear on the right (\texttt{"} x\texttt{"} and \texttt{"} y\texttt{"} ) are references to + input variables. + + To complement this, you must also supply expressions for the inverse + transformation via the \texttt{"} inv\texttt{"} parameter. In this case, the number of + expressions given would normally match the number of MathMap input + coordinates (given by the Nin attribute). If Nin is 2, you might use: + \sstitemlist{ + + \sstitem + \texttt{"} x = r $*$ cos( theta )\texttt{"} + + \sstitem + \texttt{"} y = r $*$ sin( theta )\texttt{"} + + } + which expresses the transformation from polar to Cartesian + coordinates. Note that here the input variables (\texttt{"} x\texttt{"} and \texttt{"} y\texttt{"} ) are + named on the left of each expression, and the output variables (\texttt{"} r\texttt{"} + and \texttt{"} theta\texttt{"} ) are referenced on the right. + + Normally, you cannot refer to a variable on the right of an expression + unless it is named on the left of an expression in the complementary + set of functions. Therefore both sets of functions (forward and + inverse) must be formulated using the same consistent set of variable + names. This means that if you wish to leave one of the transformations + undefined, you must supply dummy expressions which simply name each of + the output (or input) variables. For example, you might use: + \sstitemlist{ + + \sstitem + \texttt{"} x\texttt{"} + + \sstitem + \texttt{"} y\texttt{"} + + } + for the inverse transformation above, which serves to name the input + variables but without defining an inverse transformation. + } + \sstdiytopic{ + Calculating Intermediate Values + }{ + It is sometimes useful to calculate intermediate values and then to + use these in the final expressions for the output (or input) + variables. This may be done by supplying additional expressions for + the forward (or inverse) transformation functions. For instance, the + following array of five expressions describes 2-dimensional pin-cushion + distortion: + \sstitemlist{ + + \sstitem + \texttt{"} r = sqrt( xin $*$ xin $+$ yin $*$ yin )\texttt{"} + + \sstitem + \texttt{"} rout = r $*$ ( 1 $+$ 0.1 $*$ r $*$ r )\texttt{"} + + \sstitem + \texttt{"} theta = atan2( yin, xin )\texttt{"} + + \sstitem + \texttt{"} xout = rout $*$ cos( theta )\texttt{"} + + \sstitem + \texttt{"} yout = rout $*$ sin( theta )\texttt{"} + + } + Here, we first calculate three intermediate results (\texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"} + and \texttt{"} theta\texttt{"} ) and then use these to calculate the final results (\texttt{"} xout\texttt{"} + and \texttt{"} yout\texttt{"} ). The MathMap knows that only the final two results + constitute values for the output variables because its Nout attribute + is set to 2. You may define as many intermediate variables in this + way as you choose. Having defined a variable, you may then refer to it + on the right of any subsequent expressions. + + Note that when defining the inverse transformation you may only refer + to the output variables \texttt{"} xout\texttt{"} and \texttt{"} yout\texttt{"} . The intermediate variables + \texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"} and \texttt{"} theta\texttt{"} (above) are private to the forward + transformation and may not be referenced by the inverse + transformation. The inverse transformation may, however, define its + own private intermediate variables. + } + \sstdiytopic{ + Expression Syntax + }{ + The expressions given for the forward and inverse transformations + closely follow the syntax of the C programming language (with some + extensions for compatibility with Fortran). They may contain + references to variables and literal constants, together with + arithmetic, boolean, relational and bitwise operators, and function + invocations. A set of symbolic constants is also available. Each of + these is described in detail below. Parentheses may be used to + over-ride the normal order of evaluation. There is no built-in limit + to the length of expressions and they are insensitive to case or the + presence of additional white space. + } + \sstdiytopic{ + Variables + }{ + Variable names must begin with an alphabetic character and may contain + only alphabetic characters, digits, and the underscore character + \texttt{"} \_\texttt{"} . There is no built-in limit to the length of variable names. + } + \sstdiytopic{ + Literal Constants + }{ + Literal constants, such as \texttt{"} 0\texttt{"} , \texttt{"} 1\texttt{"} , \texttt{"} 0.007\texttt{"} or \texttt{"} 2.505e-16\texttt{"} may appear + in expressions, with the decimal point and exponent being optional (a + \texttt{"} D\texttt{"} may also be used as an exponent character for compatibility with + Fortran). A unary minus \texttt{"} -\texttt{"} may be used as a prefix. + } + \sstdiytopic{ + Arithmetic Precision + }{ + All arithmetic is floating point, performed in double precision. + } + \sstdiytopic{ + Propagation of Missing Data + }{ + Unless indicated otherwise, if any argument of a function or operator + has the value AST\_\_BAD (indicating missing data), then the result of + that function or operation is also AST\_\_BAD, so that such values are + propagated automatically through all operations performed by MathMap + transformations. The special value AST\_\_BAD can be represented in + expressions by the symbolic constant \texttt{"} $<$bad$>$\texttt{"} . + + A $<$bad$>$ result (i.e. equal to AST\_\_BAD) is also produced in response + to any numerical error (such as division by zero or numerical + overflow), or if an invalid argument value is provided to a function + or operator. + } + \sstdiytopic{ + Arithmetic Operators + }{ + The following arithmetic operators are available: + \sstitemlist{ + + \sstitem + x1 $+$ x2: Sum of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . + + \sstitem + x1 - x2: Difference of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . + + \sstitem + x1 $*$ x2: Product of \texttt{"} x1\texttt{"} and \texttt{"} x1\texttt{"} . + + \sstitem + x1 / x2: Ratio of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} . + + \sstitem + x1 $*$$*$ x2: \texttt{"} x1\texttt{"} raised to the power of \texttt{"} x2\texttt{"} . + + \sstitem + $+$ x: Unary plus, has no effect on its argument. + + \sstitem + - x: Unary minus, negates its argument. + } + } + \sstdiytopic{ + Boolean Operators + }{ + Boolean values are represented using zero to indicate false and + non-zero to indicate true. In addition, the value AST\_\_BAD is taken to + mean \texttt{"} unknown\texttt{"} . The values returned by boolean operators may therefore + be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"} logic is + implemented. For example, \texttt{"} a$|$$|$b\texttt{"} may evaluate to 1 if \texttt{"} a\texttt{"} is non-zero, + even if \texttt{"} b\texttt{"} has the value AST\_\_BAD. This is because the result of the + operation would not be affected by the value of \texttt{"} b\texttt{"} , so long as \texttt{"} a\texttt{"} is + non-zero. + + The following boolean operators are available: + \sstitemlist{ + + \sstitem + x1 \&\& x2: Boolean AND between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning 1 if both \texttt{"} x1\texttt{"} + and \texttt{"} x2\texttt{"} are non-zero, and 0 otherwise. This operator implements + tri-state logic. (The synonym \texttt{"} .and.\texttt{"} is also provided for compatibility + with Fortran.) + + \sstitem + x1 $|$$|$ x2: Boolean OR between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning 1 if either \texttt{"} x1\texttt{"} + or \texttt{"} x2\texttt{"} are non-zero, and 0 otherwise. This operator implements + tri-state logic. (The synonym \texttt{"} .or.\texttt{"} is also provided for compatibility + with Fortran.) + + \sstitem + x1 $\wedge$$\wedge$ x2: Boolean exclusive OR (XOR) between \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} , returning + 1 if exactly one of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} is non-zero, and 0 otherwise. Tri-state + logic is not used with this operator. (The synonyms \texttt{"} .neqv.\texttt{"} and \texttt{"} .xor.\texttt{"} + are also provided for compatibility with Fortran, although the second + of these is not standard.) + + \sstitem + x1 .eqv. x2: This is provided only for compatibility with Fortran + and tests whether the boolean states of \texttt{"} x1\texttt{"} and \texttt{"} x2\texttt{"} (i.e. true/false) + are equal. It is the negative of the exclusive OR (XOR) function. + Tri-state logic is not used with this operator. + + \sstitem + ! x: Boolean unary NOT operation, returning 1 if \texttt{"} x\texttt{"} is zero, and + 0 otherwise. (The synonym \texttt{"} .not.\texttt{"} is also provided for compatibility + with Fortran.) + } + } + \sstdiytopic{ + Relational Operators + }{ + Relational operators return the boolean result (0 or 1) of comparing + the values of two floating point values for equality or inequality. The + value AST\_\_BAD may also be returned if either argument is $<$bad$>$. + + The following relational operators are available: + \sstitemlist{ + + \sstitem + x1 == x2: Tests whether \texttt{"} x1\texttt{"} equals \texttt{"} x1\texttt{"} . (The synonym \texttt{"} .eq.\texttt{"} is + also provided for compatibility with Fortran.) + + \sstitem + x1 != x2: Tests whether \texttt{"} x1\texttt{"} is unequal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .ne.\texttt{"} + is also provided for compatibility with Fortran.) + + \sstitem + x1 $>$ x2: Tests whether \texttt{"} x1\texttt{"} is greater than \texttt{"} x2\texttt{"} . (The synonym + \texttt{"} .gt.\texttt{"} is also provided for compatibility with Fortran.) + + \sstitem + x1 $>$= x2: Tests whether \texttt{"} x1\texttt{"} is greater than or equal to \texttt{"} x2\texttt{"} . (The + synonym \texttt{"} .ge.\texttt{"} is also provided for compatibility with Fortran.) + + \sstitem + x1 $<$ x2: Tests whether \texttt{"} x1\texttt{"} is less than \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .lt.\texttt{"} + is also provided for compatibility with Fortran.) + + \sstitem + x1 $<$= x2: Tests whether \texttt{"} x1\texttt{"} is less than or equal to \texttt{"} x2\texttt{"} . (The + synonym \texttt{"} .le.\texttt{"} is also provided for compatibility with Fortran.) + + } + Note that relational operators cannot usefully be used to compare + values with the $<$bad$>$ value (representing missing data), because the + result is always $<$bad$>$. The isbad() function should be used instead. + } + \sstdiytopic{ + Bitwise Operators + }{ + The bitwise operators provided by C are often useful when operating on + raw data (e.g. from instruments), so they are also provided for use in + MathMap expressions. In this case, however, the values on which they + operate are floating point values rather than pure integers. In order + to produce results which match the pure integer case, the operands are + regarded as fixed point binary numbers (i.e. with the binary + equivalent of a decimal point) with negative numbers represented using + twos-complement notation. For integer values, the resulting bit + pattern corresponds to that of the equivalent signed integer (digits + to the right of the point being zero). Operations on the bits + representing the fractional part are also possible, however. + + The following bitwise operators are available: + \sstitemlist{ + + \sstitem + x1 $>$$>$ x2: Rightward bit shift. The integer value of \texttt{"} x2\texttt{"} is taken + (rounding towards zero) and the bits representing \texttt{"} x1\texttt{"} are then + shifted this number of places to the right (or to the left if the + number of places is negative). This is equivalent to dividing \texttt{"} x1\texttt{"} by + the corresponding power of 2. + + \sstitem + x1 $<$$<$ x2: Leftward bit shift. The integer value of \texttt{"} x2\texttt{"} is taken + (rounding towards zero), and the bits representing \texttt{"} x1\texttt{"} are then + shifted this number of places to the left (or to the right if the + number of places is negative). This is equivalent to multiplying \texttt{"} x1\texttt{"} + by the corresponding power of 2. + + \sstitem + x1 \& x2: Bitwise AND between the bits of \texttt{"} x1\texttt{"} and those of \texttt{"} x2\texttt{"} + (equivalent to a boolean AND applied at each bit position in turn). + + \sstitem + x1 $|$ x2: Bitwise OR between the bits of \texttt{"} x1\texttt{"} and those of \texttt{"} x2\texttt{"} + (equivalent to a boolean OR applied at each bit position in turn). + + \sstitem + x1 $\wedge$ x2: Bitwise exclusive OR (XOR) between the bits of \texttt{"} x1\texttt{"} and + those of \texttt{"} x2\texttt{"} (equivalent to a boolean XOR applied at each bit + position in turn). + + } + Note that no bit inversion operator (\texttt{"} $\sim$\texttt{"} in C) is provided. This is + because inverting the bits of a twos-complement fixed point binary + number is equivalent to simply negating it. This differs from the + pure integer case because bits to the right of the binary point are + also inverted. To invert only those bits to the left of the binary + point, use a bitwise exclusive OR with the value -1 (i.e. \texttt{"} x$\wedge$-1\texttt{"} ). + } + \sstdiytopic{ + Functions + }{ + The following functions are available: + \sstitemlist{ + + \sstitem + abs(x): Absolute value of \texttt{"} x\texttt{"} (sign removal), same as fabs(x). + + \sstitem + acos(x): Inverse cosine of \texttt{"} x\texttt{"} , in radians. + + \sstitem + acosd(x): Inverse cosine of \texttt{"} x\texttt{"} , in degrees. + + \sstitem + acosh(x): Inverse hyperbolic cosine of \texttt{"} x\texttt{"} . + + \sstitem + acoth(x): Inverse hyperbolic cotangent of \texttt{"} x\texttt{"} . + + \sstitem + acsch(x): Inverse hyperbolic cosecant of \texttt{"} x\texttt{"} . + + \sstitem + aint(x): Integer part of \texttt{"} x\texttt{"} (round towards zero), same as int(x). + + \sstitem + asech(x): Inverse hyperbolic secant of \texttt{"} x\texttt{"} . + + \sstitem + asin(x): Inverse sine of \texttt{"} x\texttt{"} , in radians. + + \sstitem + asind(x): Inverse sine of \texttt{"} x\texttt{"} , in degrees. + + \sstitem + asinh(x): Inverse hyperbolic sine of \texttt{"} x\texttt{"} . + + \sstitem + atan(x): Inverse tangent of \texttt{"} x\texttt{"} , in radians. + + \sstitem + atand(x): Inverse tangent of \texttt{"} x\texttt{"} , in degrees. + + \sstitem + atanh(x): Inverse hyperbolic tangent of \texttt{"} x\texttt{"} . + + \sstitem + atan2(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in radians. + + \sstitem + atan2d(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in degrees. + + \sstitem + ceil(x): Smallest integer value not less then \texttt{"} x\texttt{"} (round towards + plus infinity). + + \sstitem + cos(x): Cosine of \texttt{"} x\texttt{"} in radians. + + \sstitem + cosd(x): Cosine of \texttt{"} x\texttt{"} in degrees. + + \sstitem + cosh(x): Hyperbolic cosine of \texttt{"} x\texttt{"} . + + \sstitem + coth(x): Hyperbolic cotangent of \texttt{"} x\texttt{"} . + + \sstitem + csch(x): Hyperbolic cosecant of \texttt{"} x\texttt{"} . + + \sstitem + dim(x1, x2): Returns \texttt{"} x1-x2\texttt{"} if \texttt{"} x1\texttt{"} is greater than \texttt{"} x2\texttt{"} , otherwise 0. + + \sstitem + exp(x): Exponential function of \texttt{"} x\texttt{"} . + + \sstitem + fabs(x): Absolute value of \texttt{"} x\texttt{"} (sign removal), same as abs(x). + + \sstitem + floor(x): Largest integer not greater than \texttt{"} x\texttt{"} (round towards + minus infinity). + + \sstitem + fmod(x1, x2): Remainder when \texttt{"} x1\texttt{"} is divided by \texttt{"} x2\texttt{"} , same as + mod(x1, x2). + + \sstitem + gauss(x1, x2): Random sample from a Gaussian distribution with mean + \texttt{"} x1\texttt{"} and standard deviation \texttt{"} x2\texttt{"} . + + \sstitem + int(x): Integer part of \texttt{"} x\texttt{"} (round towards zero), same as aint(x). + + \sstitem + isbad(x): Returns 1 if \texttt{"} x\texttt{"} has the $<$bad$>$ value (AST\_\_BAD), otherwise 0. + + \sstitem + log(x): Natural logarithm of \texttt{"} x\texttt{"} . + + \sstitem + log10(x): Logarithm of \texttt{"} x\texttt{"} to base 10. + + \sstitem + max(x1, x2, ...): Maximum of two or more values. + + \sstitem + min(x1, x2, ...): Minimum of two or more values. + + \sstitem + mod(x1, x2): Remainder when \texttt{"} x1\texttt{"} is divided by \texttt{"} x2\texttt{"} , same as + fmod(x1, x2). + + \sstitem + nint(x): Nearest integer to \texttt{"} x\texttt{"} (round to nearest). + + \sstitem + poisson(x): Random integer-valued sample from a Poisson + distribution with mean \texttt{"} x\texttt{"} . + + \sstitem + pow(x1, x2): \texttt{"} x1\texttt{"} raised to the power of \texttt{"} x2\texttt{"} . + + \sstitem + qif(x1, x2, x3): Returns \texttt{"} x2\texttt{"} if \texttt{"} x1\texttt{"} is true, and \texttt{"} x3\texttt{"} otherwise. + + \sstitem + rand(x1, x2): Random sample from a uniform distribution in the + range \texttt{"} x1\texttt{"} to \texttt{"} x2\texttt{"} inclusive. + + \sstitem + sech(x): Hyperbolic secant of \texttt{"} x\texttt{"} . + + \sstitem + sign(x1, x2): Absolute value of \texttt{"} x1\texttt{"} with the sign of \texttt{"} x2\texttt{"} + (transfer of sign). + + \sstitem + sin(x): Sine of \texttt{"} x\texttt{"} in radians. + + \sstitem + sinc(x): Sinc function of \texttt{"} x\texttt{"} [= \texttt{"} sin(x)/x\texttt{"} ]. + + \sstitem + sind(x): Sine of \texttt{"} x\texttt{"} in degrees. + + \sstitem + sinh(x): Hyperbolic sine of \texttt{"} x\texttt{"} . + + \sstitem + sqr(x): Square of \texttt{"} x\texttt{"} (= \texttt{"} x$*$x\texttt{"} ). + + \sstitem + sqrt(x): Square root of \texttt{"} x\texttt{"} . + + \sstitem + tan(x): Tangent of \texttt{"} x\texttt{"} in radians. + + \sstitem + tand(x): Tangent of \texttt{"} x\texttt{"} in degrees. + + \sstitem + tanh(x): Hyperbolic tangent of \texttt{"} x\texttt{"} . + } + } + \sstdiytopic{ + Symbolic Constants + }{ + The following symbolic constants are available (the enclosing \texttt{"} $<$$>$\texttt{"} + brackets must be included): + \sstitemlist{ + + \sstitem + $<$bad$>$: The \texttt{"} bad\texttt{"} value (AST\_\_BAD) used to flag missing data. Note + that you cannot usefully compare values with this constant because the + result is always $<$bad$>$. The isbad() function should be used instead. + + \sstitem + $<$dig$>$: Number of decimal digits of precision available in a + floating point (double) value. + + \sstitem + $<$e$>$: \htmlref{Base}{Base} of natural logarithms. + + \sstitem + $<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is + distinguishable from unity. + + \sstitem + $<$mant\_dig$>$: The number of base $<$radix$>$ digits stored in the + mantissa of a floating point (double) value. + + \sstitem + $<$max$>$: Maximum representable floating point (double) value. + + \sstitem + $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power + can be represented as a floating point (double) value. + + \sstitem + $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that + power minus 1 can be represented as a floating point (double) value. + + \sstitem + $<$min$>$: Smallest positive number which can be represented as a + normalised floating point (double) value. + + \sstitem + $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that + power can be represented as a normalised floating point (double) value. + + \sstitem + $<$min\_exp$>$: Minimum negative integer such that $<$radix$>$ raised to + that power minus 1 can be represented as a normalised floating point + (double) value. + + \sstitem + $<$pi$>$: Ratio of the circumference of a circle to its diameter. + + \sstitem + $<$radix$>$: The radix (number base) used to represent the mantissa of + floating point (double) values. + + \sstitem + $<$rounds$>$: The mode used for rounding floating point results after + addition. Possible values include: -1 (indeterminate), 0 (toward + zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus + infinity). Other values indicate machine-dependent behaviour. + } + } + \sstdiytopic{ + Evaluation Precedence and Associativity + }{ + Items appearing in expressions are evaluated in the following order + (highest precedence first): + \sstitemlist{ + + \sstitem + Constants and variables + + \sstitem + Function arguments and parenthesised expressions + + \sstitem + Function invocations + + \sstitem + Unary $+$ - ! .not. + + \sstitem + $*$$*$ + + \sstitem + $*$ / + + \sstitem + $+$ - + + \sstitem + $<$$<$ $>$$>$ + + \sstitem + $<$ .lt. $<$= .le. $>$ .gt. $>$= .ge. + + \sstitem + == .eq. != .ne. + + \sstitem + \& + + \sstitem + $\wedge$ + + \sstitem + $|$ + + \sstitem + \&\& .and. + + \sstitem + $\wedge$$\wedge$ + + \sstitem + $|$$|$ .or + + \sstitem + .eqv. .neqv. .xor. + + } + All operators associate from left-to-right, except for unary $+$, + unary -, !, .not. and $*$$*$ which associate from right-to-left. + } +} +\sstroutine{ + astMatrixMap +}{ + Create a MatrixMap +}{ + \sstdescription{ + This function creates a new \htmlref{MatrixMap}{MatrixMap} and optionally initialises + its attributes. + + A MatrixMap is a form of \htmlref{Mapping}{Mapping} which performs a general linear + transformation. Each set of input coordinates, regarded as a + column-vector, are pre-multiplied by a matrix (whose elements + are specified when the MatrixMap is created) to give a new + column-vector containing the output coordinates. If appropriate, + the inverse transformation may also be performed. + } + \sstsynopsis{ + AstMatrixMap $*$astMatrixMap( int nin, int nout, int form, + const double matrix[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nin + }{ + The number of input coordinates, which determines the number + of columns in the matrix. + } + \sstsubsection{ + nout + }{ + The number of output coordinates, which determines the number + of rows in the matrix. + } + \sstsubsection{ + form + }{ + An integer which indicates the form in which the matrix + elements will be supplied. + + A value of zero indicates that a full \texttt{"} nout\texttt{"} x \texttt{"} nin\texttt{"} matrix + of values will be supplied via the \texttt{"} matrix\texttt{"} parameter + (below). In this case, the elements should be given in row + order (the elements of the first row, followed by the + elements of the second row, etc.). + + A value of 1 indicates that only the diagonal elements of the + matrix will be supplied, and that all others should be + zero. In this case, the elements of \texttt{"} matrix\texttt{"} should contain + only the diagonal elements, stored consecutively. + + A value of 2 indicates that a \texttt{"} unit\texttt{"} matrix is required, + whose diagonal elements are set to unity (with all other + elements zero). In this case, the \texttt{"} matrix\texttt{"} parameter is + ignored and a NULL pointer may be supplied. + } + \sstsubsection{ + matrix + }{ + The array of matrix elements to be used, stored according to + the value of \texttt{"} form\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new MatrixMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMatrixMap() + }{ + A pointer to the new MatrixMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + In general, a MatrixMap\texttt{'} s forward transformation will always + be available (as indicated by its \htmlref{TranForward}{TranForward} attribute), but + its inverse transformation (\htmlref{TranInverse}{TranInverse} attribute) will only be + available if the associated matrix is square and non-singular. + + \sstitem + As an exception to this, the inverse transformation is always + available if a unit or diagonal matrix is specified. In this + case, if the matrix is not square, one or more of the input + coordinate values may not be recoverable from a set of output + coordinates. Any coordinates affected in this way will simply be + set to the value zero. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astMirrorVariants +}{ + Make the current Frame mirror the variant Mappings in another Frame +}{ + \sstdescription{ + This function + indicates that all access to the \htmlref{Variant}{Variant} attribute of the current + \htmlref{Frame}{Frame} should should be forwarded to some other nominated Frame in + the \htmlref{FrameSet}{FrameSet}. For instance, if a value is set subsequently for the + Variant attribute of the current Frame, the current Frame will be left + unchanged and the setting is instead applied to the nominated Frame. + Likewise, if the value of the Variant attribute is requested, the + value returned is the value stored for the nominated Frame rather + than the current Frame itself. + + This provides a mechanism for propagating the effects of variant + Mappings around a FrameSet. If a new Frame is added to a FrameSet + by connecting it to an pre-existing Frame that has two or more variant + Mappings, then it may be appropriate to set the new Frame so that it + mirrors the variants Mappings of the pre-existing Frame. If this is + done, then it will be possible to select a specific variant \htmlref{Mapping}{Mapping} + using either the pre-existing Frame or the new Frame. + } + \sstsynopsis{ + void astMirrorVariants( AstFrameSet $*$this, int iframe, int $*$status ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe + }{ + The index of the Frame within the FrameSet which is to be + mirrored by the current Frame. This value should lie in the range + from 1 to the number of Frames in the FrameSet (as given by its + \htmlref{Nframe}{Nframe} attribute). If AST\_\_NOFRAME is supplied (or the current + Frame is specified), then any mirroring established by a previous + call to this + function + is disabled. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Mirrors can be chained. That is, if Frame B is set to be a mirror + of Frame A, and Frame C is set to be a mirror of Frame B, then + Frame C will act as a mirror of Frame A. + + \sstitem + Variant Mappings cannot be added to the current Frame if it is + mirroring another Frame. So calls to the + \htmlref{astAddVariant}{astAddVariant} function + will cause an error to be reported if the current Frame is + mirroring another Frame. + + \sstitem + A value of AST\_\_BASE may be given for the + \texttt{"} iframe\texttt{"} parameter + to specify the base Frame. + + \sstitem + Any variant Mappings explicitly added to the current Frame using + astAddVariant + will be ignored if the current Frame is mirroring another Frame. + } + } +} +\sstroutine{ + astNegate +}{ + Negate the area represented by a Region +}{ + \sstdescription{ + This function negates the area represented by a \htmlref{Region}{Region}. That is, + points which were previously inside the region will then be + outside, and points which were outside will be inside. This is + acomplished by toggling the state of the \htmlref{Negated}{Negated} attribute for + the supplied region. + } + \sstsynopsis{ + void astNegate( AstRegion $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + } +} +\sstroutine{ + astNorm +}{ + Normalise a set of Frame coordinates +}{ + \sstdescription{ + This function normalises a set of \htmlref{Frame}{Frame} coordinate values which + might be unsuitable for display (e.g. may lie outside the + expected range) into a set of acceptable values suitable for + display. + } + \sstsynopsis{ + void astNorm( AstFrame $*$this, double value[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + value + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). Initially, this should contain a set of + coordinate values representing a point in the space which the + Frame describes. If these values lie outside the expected + range for the Frame, they will be replaced with more + acceptable (normalised) values. Otherwise, they will be + returned unchanged. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For some classes of Frame, whose coordinate values are not + constrained, this function will never modify the values + supplied. However, for Frames whose axes represent cyclic + quantities (such as angles or positions on the sky), coordinates + will typically be wrapped into an appropriate standard range, + such as zero to 2$*$pi. + + \sstitem + The \htmlref{NormMap}{NormMap} class is a \htmlref{Mapping}{Mapping} which can be used to normalise a + set of points using the + astNorm function + of a specified Frame. + + \sstitem + It is intended to be possible to put any set of coordinates + into a form suitable for display by using this function to + normalise them, followed by appropriate formatting + (using \htmlref{astFormat}{astFormat}). + } + } +} +\sstroutine{ + astNormMap +}{ + Create a NormMap +}{ + \sstdescription{ + This function creates a new \htmlref{NormMap}{NormMap} and optionally initialises its + attributes. + + A NormMap is a \htmlref{Mapping}{Mapping} which normalises coordinate values using the + \htmlref{astNorm}{astNorm} function + of the supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap + are both equal to the number of axes in the supplied Frame. + + The forward and inverse transformation of a NormMap are both + defined but are identical (that is, they do not form a real inverse + pair in that the inverse transformation does not undo the + normalisation, instead it reapplies it). However, the + \htmlref{astSimplify}{astSimplify} + function will replace neighbouring pairs of forward and inverse + NormMaps by a single \htmlref{UnitMap}{UnitMap}. + } + \sstsynopsis{ + AstNormMap $*$astNormMap( AstFrame $*$frame, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame which is to be used to normalise the + supplied axis values. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new NormMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astNormMap() + }{ + A pointer to the new NormMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astNullRegion +}{ + Create a NullRegion +}{ + \sstdescription{ + This function creates a new \htmlref{NullRegion}{NullRegion} and optionally initialises its + attributes. + + A NullRegion is a \htmlref{Region}{Region} with no bounds. If the \htmlref{Negated}{Negated} attribute of a + NullRegion is false, the NullRegion represents a Region containing no + points. If the Negated attribute of a NullRegion is true, the NullRegion + represents an infinite Region containing all points within the + coordinate system. + } + \sstsynopsis{ + AstNullRegion $*$astNullRegion( AstFrame $*$frame, AstRegion $*$unc, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the \htmlref{Frame}{Frame} in which the region is defined. A deep + copy is taken of the supplied Frame. This means that any + subsequent changes made to the Frame using the supplied pointer + will have no effect the Region. + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with positions in the supplied Frame. + The uncertainty in any point in the Frame is found by shifting the + supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point + being considered. The area covered by the shifted uncertainty + Region then represents the uncertainty in the position. The + uncertainty is assumed to be the same for all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created NullRegion. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty of zero is + used. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new NullRegion. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astNullRegion() + }{ + A pointer to the new NullRegion. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astOK +}{ + Test whether AST functions have been successful +}{ + \sstdescription{ + This macro returns a boolean value (0 or 1) to indicate if + preceding AST functions have completed successfully + (i.e. without setting the AST error status). If the error status + is set to an error value, a value of zero is returned, otherwise + the result is one. + } + \sstsynopsis{ + int astOK + } + \sstreturnedvalue{ + \sstsubsection{ + astOK + }{ + One if the AST error status is OK, otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the AST error status is set to an error value (after an + error), most AST functions will not execute and will simply + return without action. To clear the error status and restore + normal behaviour, use \htmlref{astClearStatus}{astClearStatus}. + } + } +} +\sstroutine{ + astOffset +}{ + Calculate an offset along a geodesic curve +}{ + \sstdescription{ + This function finds the \htmlref{Frame}{Frame} coordinate values of a point which + is offset a specified distance along the geodesic curve between + two other points. + + For example, in a basic Frame, this offset will be along the + straight line joining two points. For a more specialised Frame + describing a sky coordinate system, however, it would be along + the great circle passing through two sky positions. + } + \sstsynopsis{ + void astOffset( AstFrame $*$this, + const double point1[], const double point2[], + double offset, double point3[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + point1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the + point marking the start of the geodesic curve. + } + \sstsubsection{ + point2 + }{ + An array of double, with one element for each Frame axis + This should contain the coordinates of the point marking the + end of the geodesic curve. + } + \sstsubsection{ + offset + }{ + The required offset from the first point along the geodesic + curve. If this is positive, it will be towards the second + point. If it is negative, it will be in the opposite + direction. This offset need not imply a position lying + between the two points given, as the curve will be + extrapolated if necessary. + } + \sstsubsection{ + point3 + }{ + An array of double, with one element for each Frame axis + in which the coordinates of the required point will be returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The geodesic curve used by this function is the path of + shortest distance between two points, as defined by the + \htmlref{astDistance}{astDistance} function. + + \sstitem + This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) + if any of the input coordinates has this value. + + \sstitem + \texttt{"} Bad\texttt{"} coordinate values will also be returned if the two + points supplied are coincident (or otherwise fail to uniquely + specify a geodesic curve) but the requested offset is non-zero. + } + } +} +\sstroutine{ + astOffset2 +}{ + Calculate an offset along a geodesic curve in a 2D Frame +}{ + \sstdescription{ + This function finds the \htmlref{Frame}{Frame} coordinate values of a point which + is offset a specified distance along the geodesic curve at a + given angle from a specified starting point. It can only be + used with 2-dimensional Frames. + + For example, in a basic Frame, this offset will be along the + straight line joining two points. For a more specialised Frame + describing a sky coordinate system, however, it would be along + the great circle passing through two sky positions. + } + \sstsynopsis{ + double astOffset2( AstFrame $*$this, const double point1[2], double angle, + double offset, double point2[2] ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + point1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the + point marking the start of the geodesic curve. + } + \sstsubsection{ + angle + }{ + The angle (in radians) from the positive direction of the second + axis, to the direction of the required position, as seen from + the starting position. Positive rotation is in the sense of + rotation from the positive direction of axis 2 to the positive + direction of axis 1. + } + \sstsubsection{ + offset + }{ + The required offset from the first point along the geodesic + curve. If this is positive, it will be in the direction of the + given angle. If it is negative, it will be in the opposite + direction. + } + \sstsubsection{ + point2 + }{ + An array of double, with one element for each Frame axis + in which the coordinates of the required point will be returned. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astOffset2 + }{ + The direction of the geodesic curve at the end point. That is, the + angle (in radians) between the positive direction of the second + axis and the continuation of the geodesic curve at the requested + end point. Positive rotation is in the sense of rotation from + the positive direction of axis 2 to the positive direction of axis + 1. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The geodesic curve used by this function is the path of + shortest distance between two points, as defined by the + \htmlref{astDistance}{astDistance} function. + + \sstitem + An error will be reported if the Frame is not 2-dimensional. + + \sstitem + This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) + if any of the input coordinates has this value. + } + } +} +\sstroutine{ + astOutline$<$X$>$ +}{ + Create a new Polygon outling values in a 2D data grid +}{ + \sstdescription{ + This is a set of functions that create a \htmlref{Polygon}{Polygon} enclosing a single + contiguous set of pixels that have a specified value within a gridded + 2-dimensional data array (e.g. an image). + + A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate + system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to + \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the + Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other + attributes are left unset. The nature of the pixel coordinate system + is determined by parameter + \texttt{"} starpix\texttt{"} . + + The + \texttt{"} maxerr\texttt{"} and \texttt{"} maxvert\texttt{"} + parameters can be used to control how accurately the returned + Polygon represents the required region in the data array. The + number of vertices in the returned Polygon will be the minimum + needed to achieve the required accuracy. + + You should use a function which matches the numerical type of the + data you are processing by replacing $<$X$>$ in the generic function + name + astOutline$<$X$>$ + by an appropriate 1- or 2-character type code. For example, if you + are procesing data with type + \texttt{"} float\texttt{"} , you should use the function astOutlineF + (see the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to + other numerical types). + } + \sstsynopsis{ + AstPolygon $*$astOutline$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[], + const int lbnd[2], const int ubnd[2], double maxerr, + int maxvert, const int inside[2], int starpix ) + } + \sstparameters{ + \sstsubsection{ + value + }{ + A data value that specifies the pixels to be outlined. + } + \sstsubsection{ + oper + }{ + Indicates how the + \texttt{"} value\texttt{"} + parameter is used to select the outlined pixels. It can + have any of the following values: + \sstitemlist{ + + \sstitem + AST\_\_LT: outline pixels with value less than \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_LE: outline pixels with value less than or equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_EQ: outline pixels with value equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_NE: outline pixels with value not equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_GE: outline pixels with value greater than or equal to \texttt{"} value\texttt{"} . + + \sstitem + AST\_\_GT: outline pixels with value greater than \texttt{"} value\texttt{"} . + } + } + \sstsubsection{ + array + }{ + Pointer to a + 2-dimensional array containing the data to be processed. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astOutlineF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the second dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of two integers + containing the pixel index of the first pixel in the input grid + along each dimension. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of two integers + containing the pixel index of the last pixel in the input grid + along each dimension. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape + and size of the input pixel grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 pixels. + For FITS images, + the lbnd values will be 1 and the ubnd + values will be equal to the NAXISi header values. Other + data systems, such as the Starlink NDF system, allow an + arbitrary pixel origin to be used (i.e. lbnd + is not necessarily 1). + + These bounds also define the input grid\texttt{'} s floating point coordinate + system, each pixel having unit extent along each dimension with + integral coordinate values at its centre or upper corner, as selected + by parameter + \texttt{"} starpix\texttt{"} . + } + \sstsubsection{ + maxerr + }{ + Together with + \texttt{"} maxvert\texttt{"} , + this determines how accurately the returned Polygon represents + the required region of the data array. It gives the target + discrepancy between the returned Polygon and the accurate outline + in the data array, expressed as a number of pixels. Insignificant + vertices are removed from the accurate outline, one by one, until + the number of vertices remaining in the returned Polygon equals + \texttt{"} maxvert\texttt{"} , + or the largest discrepancy between the accurate outline and the + returned Polygon is greater than + \texttt{"} maxerr\texttt{"} . If \texttt{"} maxerr\texttt{"} + is zero or less, its value is ignored and the returned Polygon will + have the number of vertices specified by + \texttt{"} maxvert\texttt{"} . + } + \sstsubsection{ + maxvert + }{ + Together with + \texttt{"} maxerr\texttt{"} , + this determines how accurately the returned Polygon represents + the required region of the data array. It gives the maximum + allowed number of vertices in the returned Polygon. Insignificant + vertices are removed from the accurate outline, one by one, until + the number of vertices remaining in the returned Polygon equals + \texttt{"} maxvert\texttt{"} , + or the largest discrepancy between the accurate outline and the + returned Polygon is greater than + \texttt{"} maxerr\texttt{"} . If \texttt{"} maxvert\texttt{"} + is less than 3, its value is ignored and the number of vertices in + the returned Polygon will be the minimum needed to ensure that the + discrepancy between the accurate outline and the returned + Polygon is less than + \texttt{"} maxerr\texttt{"} . + } + \sstsubsection{ + inside + }{ + Pointer to an array of two integers + containing the pixel indices of a pixel known to be inside the + required region. This is needed because the supplied data + array may contain several disjoint areas of pixels that satisfy + the criterion specified by + \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} . + In such cases, the area described by the returned Polygon will + be the one that contains the pixel specified by + \texttt{"} inside\texttt{"} . + If the specified pixel is outside the bounds given by + \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} , + or has a value that does not meet the criterion specified by + \texttt{"} value\texttt{"} and \texttt{"} oper\texttt{"} , + then this function will search for a suitable pixel. The search + starts at the central pixel and proceeds in a spiral manner until + a pixel is found that meets the specified crierion. + } + \sstsubsection{ + starpix + }{ + A flag indicating the nature of the pixel coordinate system used + to describe the vertex positions in the returned Polygon. If + non-zero, + the standard Starlink definition of pixel coordinate is used in + which a pixel with integer index I spans a range of pixel coordinate + from (I-1) to I (i.e. pixel corners have integral pixel coordinates). + If zero, + the definition of pixel coordinate used by other AST functions + such as astResample, astMask, + etc., is used. In this definition, a pixel with integer index I + spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. + pixel centres have integral pixel coordinates). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astOutline$<$X$>$() + }{ + A pointer to the required Polygon. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function proceeds by first finding a very accurate polygon, + and then removing insignificant vertices from this fine polygon + using + \htmlref{astDownsize}{astDownsize}. + + \sstitem + The returned Polygon is the outer boundary of the contiguous set + of pixels that includes ths specified \texttt{"} inside\texttt{"} point, and satisfy + the specified value requirement. This set of pixels may potentially + include \texttt{"} holes\texttt{"} where the pixel values fail to meet the specified + value requirement. Such holes will be ignored by this function. + + \sstitem + NULL + will be returned if this function is invoked with the global + error status set, or if it should fail for any reason. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate masking function, you should + replace $<$X$>$ in the generic function name astOutline$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + L: long int + + \sstitem + UL: unsigned long int + + \sstitem + I: int + + \sstitem + UI: unsigned int + + \sstitem + S: short int + + \sstitem + US: unsigned short int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astOutlineD would be used to process \texttt{"} double\texttt{"} + data, while astOutlineS would be used to process \texttt{"} short int\texttt{"} + data, etc. + } +} +\sstroutine{ + astOverlap +}{ + Test if two regions overlap each other +}{ + \sstdescription{ + This function returns an integer value indicating if the two + supplied Regions overlap. The two Regions are converted to a commnon + coordinate system before performing the check. If this conversion is + not possible (for instance because the two Regions represent areas in + different domains), then the check cannot be performed and a zero value + is returned to indicate this. + } + \sstsynopsis{ + int astOverlap( AstRegion $*$this, AstRegion $*$that ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the first \htmlref{Region}{Region}. + } + \sstsubsection{ + that + }{ + Pointer to the second Region. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astOverlap() + }{ + A value indicating if there is any overlap between the two Regions. + Possible values are: + + 0 - The check could not be performed because the second Region + could not be mapped into the coordinate system of the first + Region. + + 1 - There is no overlap between the two Regions. + + 2 - The first Region is completely inside the second Region. + + 3 - The second Region is completely inside the first Region. + + 4 - There is partial overlap between the two Regions. + + 5 - The Regions are identical to within their uncertainties. + + 6 - The second Region is the exact negation of the first Region + to within their uncertainties. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned values 5 and 6 do not check the value of the \htmlref{Closed}{Closed} + attribute in the two Regions. + + \sstitem + A value of zero will be returned if this function is invoked with the + AST error status set, or if it should fail for any reason. + } + } +} +\sstroutine{ + astParameterName +}{ + Get the name of the global parameter at a given index within the Table +}{ + \sstdescription{ + This function returns a string holding the name of the global parameter with + the given index within the \htmlref{Table}{Table}. + + This function is intended primarily as a means of iterating round all + the parameters in a Table. For this purpose, the number of parameters in + the Table is given by the \htmlref{Nparameter}{Nparameter} attribute of the Table. This function + could then be called in a loop, with the index value going from + zero to one less than Nparameter. + + Note, the index associated with a parameter decreases monotonically with + the age of the parameter: the oldest Parameter in the Table will have index + one, and the Parameter added most recently to the Table will have the + largest index. + } + \sstsynopsis{ + const char $*$astParameterName( AstTable $*$this, int index ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + index + }{ + The index into the list of parameters. The first parameter has index + one, and the last has index \texttt{"} Nparameter\texttt{"} . + } + } + \sstreturnedvalue{ + \sstsubsection{ + astParameterName() + }{ + A pointer to a null-terminated string containing the + upper case parameter name. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned pointer is guaranteed to remain valid and the + string to which it points will not be over-written for a total + of 50 successive invocations of this function. After this, the + memory containing the string may be re-used, so a copy of the + string should be made if it is needed for longer than this. + + \sstitem + A NULL pointer will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astPcdMap +}{ + Create a PcdMap +}{ + \sstdescription{ + This function creates a new \htmlref{PcdMap}{PcdMap} and optionally initialises its + attributes. + + A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional + positions to correct for the radial distortion introduced by some + cameras and telescopes. This can take the form either of pincushion + or barrel distortion, and is characterized by a single distortion + coefficient. + + A PcdMap is specified by giving this distortion coefficient and the + coordinates of the centre of the radial distortion. The forward + transformation of a PcdMap applies the distortion: + + RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) + + where R is the undistorted radial distance from the distortion + centre (specified by attribute PcdCen), RD is the radial distance + from the same centre in the presence of distortion, and C is the + distortion coefficient (given by attribute \htmlref{Disco}{Disco}). + + The inverse transformation of a PcdMap removes the distortion + produced by the forward transformation. The expression used to derive + R from RD is an approximate inverse of the expression above, obtained + from two iterations of the Newton-Raphson method. The mismatch between + the forward and inverse expressions is negligible for astrometric + applications (to reach 1 milliarcsec at the edge of the Anglo-Australian + Telescope triplet or a Schmidt field would require field diameters of + 2.4 and 42 degrees respectively). + + If a PcdMap is inverted (e.g. using \htmlref{astInvert}{astInvert}) then the roles of the + forward and inverse transformations are reversed; the forward + transformation will remove the distortion, and the inverse + transformation will apply it. + } + \sstsynopsis{ + AstPcdMap $*$astPcdMap( double disco, const double pcdcen[2], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + disco + }{ + The distortion coefficient. Negative values give barrel + distortion, positive values give pincushion distortion, and + zero gives no distortion. + } + \sstsubsection{ + pcdcen + }{ + A 2-element array containing the coordinates of the centre of the + distortion. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new PcdMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPcdMap() + }{ + A pointer to the new PcdMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astPermAxes +}{ + Permute the axis order in a Frame +}{ + \sstdescription{ + This function permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur. + } + \sstsynopsis{ + void astPermAxes( AstFrame $*$this, const int perm[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + perm + }{ + An array with one element for each axis of the Frame (\htmlref{Naxes}{Naxes} + attribute). This should list the axes in their new order, + using the original axis numbering (which starts at 1 for the + first axis). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Only genuine permutations of the axis order are permitted, so + each axis must be referenced exactly once in the \texttt{"} perm\texttt{"} array. + + \sstitem + If successive axis permutations are applied to a Frame, then + the effects are cumulative. + } + } +} +\sstroutine{ + astPermMap +}{ + Create a PermMap +}{ + \sstdescription{ + This function creates a new \htmlref{PermMap}{PermMap} and optionally initialises its + attributes. + + A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, + and possibly also changes the number of coordinates, between its + input and output. + + In addition to permuting the coordinate order, a PermMap may + also assign constant values to coordinates. This is useful when + the number of coordinates is being increased as it allows fixed + values to be assigned to any new ones. + } + \sstsynopsis{ + AstPermMap $*$astPermMap( int nin, const int inperm[], int nout, + const int outperm[], double constant[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nin + }{ + The number of input coordinates. + } + \sstsubsection{ + inperm + }{ + An optional array with \texttt{"} nin\texttt{"} elements which, for each input + coordinate, should contain the number of the output + coordinate whose value is to be used (note that this array + therefore defines the inverse coordinate transformation). + Coordinates are numbered starting from 1. + + For details of additional special values that may be used in + this array, see the description of the \texttt{"} constant\texttt{"} parameter. + + If a NULL pointer is supplied instead of an array, each input + coordinate will obtain its value from the corresponding + output coordinate (or will be assigned the value AST\_\_BAD if + there is no corresponding output coordinate). + } + \sstsubsection{ + nout + }{ + The number of output coordinates. + } + \sstsubsection{ + outperm + }{ + An optional array with \texttt{"} nout\texttt{"} elements which, for each output + coordinate, should contain the number of the input coordinate + whose value is to be used (note that this array therefore + defines the forward coordinate transformation). Coordinates + are numbered starting from 1. + + For details of additional special values that may be used in + this array, see the description of the \texttt{"} constant\texttt{"} parameter. + + If a NULL pointer is supplied instead of an array, each output + coordinate will obtain its value from the corresponding + input coordinate (or will be assigned the value AST\_\_BAD if + there is no corresponding input coordinate). + } + \sstsubsection{ + constant + }{ + An optional array containing values which may be assigned to + input and/or output coordinates instead of deriving them + from other coordinate values. If either of the \texttt{"} inperm\texttt{"} or + \texttt{"} outperm\texttt{"} arrays contains a negative value, it is used to + address this \texttt{"} constant\texttt{"} array (such that -1 addresses the + first element, -2 addresses the second element, etc.) and the + value obtained is used as the corresponding coordinate value. + + Care should be taken to ensure that locations lying outside + the extent of this array are not accidentally addressed. The + array is not used if the \texttt{"} inperm\texttt{"} and \texttt{"} outperm\texttt{"} arrays do not + contain negative values. + + If a NULL pointer is supplied instead of an array, the + behaviour is as if the array were of infinite length and + filled with the value AST\_\_BAD. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new PermMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPermMap() + }{ + A pointer to the new PermMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If either of the \texttt{"} inperm\texttt{"} or \texttt{"} outperm\texttt{"} arrays contains a + zero value (or a positive value which does not identify a valid + output/input coordinate, as appropriate), then the value + AST\_\_BAD is assigned as the new coordinate value. + + \sstitem + This function does not attempt to ensure that the forward and + inverse transformations performed by the PermMap are + self-consistent in any way. You are therefore free to supply + coordinate permutation arrays that achieve whatever effect is + desired. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPickAxes +}{ + Create a new Frame by picking axes from an existing one +}{ + \sstdescription{ + This function creates a new \htmlref{Frame}{Frame} whose axes are copied from an + existing Frame along with other Frame attributes, such as its + \htmlref{Title}{Title}. Any number (zero or more) of the original Frame\texttt{'} s axes + may be copied, in any order, and additional axes with default + attributes may also be included in the new Frame. + + Optionally, a \htmlref{Mapping}{Mapping} that converts between the coordinate + systems described by the two Frames will also be returned. + } + \sstsynopsis{ + AstFrame $*$astPickAxes( AstFrame $*$this, int naxes, const int axes[], + AstMapping $*$$*$map ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the original Frame. + } + \sstsubsection{ + naxes + }{ + The number of axes required in the new Frame. + } + \sstsubsection{ + axes + }{ + An array, with \texttt{"} naxes\texttt{"} elements, which lists the axes to be + copied. These should be given in the order required in the + new Frame, using the axis numbering in the original Frame + (which starts at 1 for the first axis). Axes may be selected + in any order, but each may only be used once. If additional + (default) axes are also to be included, the corresponding + elements of this array should be set to zero. + } + \sstsubsection{ + map + }{ + Address of a location in which to return a pointer to a new + Mapping. This will be a \htmlref{PermMap}{PermMap} (or a \htmlref{UnitMap}{UnitMap} as a special + case) that describes the axis permutation that has taken + place between the original and new Frames. The Mapping\texttt{'} s + forward transformation will convert coordinates from the + original Frame into the new one, and vice versa. + + If this Mapping is not required, a NULL value may be supplied + for this parameter. + } + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + This function applies to all Frames. The class of Frame returned + may differ from that of the original Frame, depending on which + axes are selected. For example, if a single axis is picked from a + \htmlref{SkyFrame}{SkyFrame} (which must always have two axes) then the resulting + Frame cannot be a valid SkyFrame, so will revert to the parent + class (Frame) instead. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + Using this function on a FrameSet is identical to using it on + the current Frame in the FrameSet. The returned Frame will not + be a FrameSet. + } + \sstsubsection{ + \htmlref{Region}{Region} + }{ + If this function is used on a Region, an attempt is made to + retain the bounds information on the selected axes. If + succesful, the returned Frame will be a Region of some class. + Otherwise, the returned Frame is obtained by calling this + function on the Frame represented by the supplied Region (the + returned Frame will then not be a Region). In order to be + succesful, the selected axes in the Region must be independent + of the others. For instance, a \htmlref{Box}{Box} can be split in this way but + a \htmlref{Circle}{Circle} cannot. Another requirement for success is that no + default axes are added (that is, the + \texttt{"} axes\texttt{"} + array must not contain any zero values. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPickAxes() + }{ + A pointer to the new Frame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The new Frame will contain a \texttt{"} deep\texttt{"} copy (c.f. \htmlref{astCopy}{astCopy}) of all + the data selected from the original Frame. Modifying any aspect + of the new Frame will therefore not affect the original one. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPlot +}{ + Create a Plot +}{ + \sstdescription{ + This function creates a new \htmlref{Plot}{Plot} and optionally initialises its + attributes. + + A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base + \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is + associated with a rectangular plotting area in the underlying + graphics system. This plotting area is where graphical output + appears. It is defined when the Plot is created. + + The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate + system, which is the coordinate system in which plotting + operations are specified. The results of each plotting operation + are automatically transformed into graphical coordinates so as + to appear in the plotting area (subject to any clipping which + may be in effect). + + Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates + may often be non-linear, or even discontinuous, most plotting + does not result in simple straight lines. The basic plotting + element is therefore not a straight line, but a geodesic curve + (see \htmlref{astCurve}{astCurve}). A Plot also provides facilities for drawing + markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines + (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with + optional coordinate grids (\htmlref{astGrid}{astGrid}). + A range of Plot attributes is available to allow precise control + over the appearance of graphical output produced by these + functions. + + You may select different physical coordinate systems in which to + plot (including the native graphical coordinate system itself) + by selecting different Frames as the current Frame of a Plot, + using its \htmlref{Current}{Current} attribute. You may also set up clipping (see + \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and + this may be done in any of the coordinate systems associated + with the Plot, not necessarily the one you are plotting in. + + Like any FrameSet, a Plot may also be used as a Frame. In this + case, it behaves like its current Frame, which describes the + physical coordinate system. + + When used as a Mapping, a Plot describes the inter-relation + between graphical coordinates (its base Frame) and physical + coordinates (its current Frame). It differs from a normal + FrameSet, however, in that an attempt to transform points which + lie in clipped areas of the Plot will result in bad coordinate + values (AST\_\_BAD). + } + \sstsynopsis{ + AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ], + const double basebox[ 4 ], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + Pointer to a Frame describing the physical coordinate system + in which to plot. A pointer to a FrameSet may also be given, + in which case its current Frame will be used to define the + physical coordinate system and its base Frame will be mapped + on to graphical coordinates (see below). + + If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default + 2-dimensional Frame will be used to describe the physical + coordinate system. Labels, etc. may then be attached to this + by setting the appropriate Frame attributes + (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. + } + \sstsubsection{ + graphbox + }{ + An array giving the position and extent of the plotting area + (on the plotting surface of the underlying graphics system) + in which graphical output is to appear. This must be + specified using graphical coordinates appropriate to the + underlying graphics system. + + The first pair of values should give the coordinates of the + bottom left corner of the plotting area and the second pair + should give the coordinates of the top right corner. The + coordinate on the horizontal axis should be given first in + each pair. Note that the order in which these points are + given is important because it defines up, down, left and + right for subsequent graphical operations. + } + \sstsubsection{ + basebox + }{ + An array giving the coordinates of two points in the supplied + Frame (or in the base Frame if a FrameSet was supplied) which + correspond to the bottom left and top right corners of the + plotting area, as specified above. This range of coordinates + will be mapped linearly on to the plotting area. The + coordinates should be given in the same order as above. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Plot. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPlot() + }{ + A pointer to the new Plot. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The base Frame of the returned Plot will be a new Frame which + is created by this function to represent the coordinate system + of the underlying graphics system (graphical coordinates). It is + given a Frame index of 1 within the Plot. The choice of base + Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a + Plot has been created (although you could use this as a way of + moving the plotting area around on the plotting surface). + + \sstitem + If a Frame is supplied (via the \texttt{"} frame\texttt{"} pointer), then it + becomes the current Frame of the new Plot and is given a Frame + index of 2. + + \sstitem + If a FrameSet is supplied (via the \texttt{"} frame\texttt{"} pointer), then + all the Frames within this FrameSet become part of the new Plot + (where their Frame indices are increased by 1), with the + FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot. + + \sstitem + If a null Object pointer (AST\_\_NULL) is supplied (via the + \texttt{"} frame\texttt{"} pointer), then the returned Plot will contain two + Frames, both created by this function. The base Frame will + describe graphics coordinates (as above) and the current Frame + will be a basic Frame with no attributes set (this will + therefore give default values for such things as the Plot \htmlref{Title}{Title} + and the Label on each axis). Physical coordinates will be mapped + linearly on to graphical coordinates. + + \sstitem + An error will result if the Frame supplied (or the base Frame + if a FrameSet was supplied) is not 2-dimensional. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPlot3D +}{ + Create a Plot3D +}{ + \sstdescription{ + This function creates a new \htmlref{Plot3D}{Plot3D} and optionally initialises + its attributes. + + A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities + for producing 3D graphical output. + } + \sstsynopsis{ + AstPlot3D $*$astPlot3D( AstFrame $*$frame, const float graphbox[ 6 ], + const double basebox[ 6 ], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + Pointer to a \htmlref{Frame}{Frame} describing the physical coordinate system + in which to plot. A pointer to a \htmlref{FrameSet}{FrameSet} may also be given, + in which case its current Frame will be used to define the + physical coordinate system and its base Frame will be mapped + on to graphical coordinates (see below). + + If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default + 3-dimensional Frame will be used to describe the physical + coordinate system. Labels, etc. may then be attached to this + by setting the appropriate Frame attributes + (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot. + } + \sstsubsection{ + graphbox + }{ + An array giving the position and extent of the plotting volume + (within the plotting space of the underlying graphics system) + in which graphical output is to appear. This must be + specified using graphical coordinates appropriate to the + underlying graphics system. + + The first triple of values should give the coordinates of the + bottom left corner of the plotting volume and the second triple + should give the coordinates of the top right corner. The + coordinate on the horizontal axis should be given first in + each pair. Note that the order in which these points are + given is important because it defines up, down, left and + right for subsequent graphical operations. + } + \sstsubsection{ + basebox + }{ + An array giving the coordinates of two points in the supplied + Frame (or in the base Frame if a FrameSet was supplied) which + correspond to the bottom left and top right corners of the + plotting volume, as specified above. This range of coordinates + will be mapped linearly on to the plotting area. The + coordinates should be given in the same order as above. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Plot3D. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPlot3D() + }{ + A pointer to the new Plot3D. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The base Frame of the returned Plot3D will be a new Frame which + is created by this function to represent the coordinate system + of the underlying graphics system (graphical coordinates). It is + given a Frame index of 1 within the Plot3D. The choice of base + Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a + Plot3D has been created (although you could use this as a way of + moving the plotting area around on the plotting surface). + + \sstitem + If a Frame is supplied (via the \texttt{"} frame\texttt{"} pointer), then it + becomes the current Frame of the new Plot3D and is given a Frame + index of 2. + + \sstitem + If a FrameSet is supplied (via the \texttt{"} frame\texttt{"} pointer), then + all the Frames within this FrameSet become part of the new Plot3D + (where their Frame indices are increased by 1), with the + FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot3D. + + \sstitem + At least one of the three axes of the current Frame must be + independent of the other two current Frame axes. + + \sstitem + If a null Object pointer (AST\_\_NULL) is supplied (via the + \texttt{"} frame\texttt{"} pointer), then the returned Plot3D will contain two + Frames, both created by this function. The base Frame will + describe graphics coordinates (as above) and the current Frame + will be a basic Frame with no attributes set (this will + therefore give default values for such things as the Plot3D \htmlref{Title}{Title} + and the Label on each axis). Physical coordinates will be mapped + linearly on to graphical coordinates. + + \sstitem + An error will result if the Frame supplied (or the base Frame + if a FrameSet was supplied) is not 3-dimensional. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPointList +}{ + Create a PointList +}{ + \sstdescription{ + This function creates a new \htmlref{PointList}{PointList} object and optionally initialises + its attributes. + + A PointList object is a specialised type of \htmlref{Region}{Region} which represents a + collection of points in a coordinate \htmlref{Frame}{Frame}. + } + \sstsynopsis{ + AstPointList $*$astPointList( AstFrame $*$frame, int npnt, int ncoord, int dim, + const double $*$points, AstRegion $*$unc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. A deep + copy is taken of the supplied Frame. This means that any + subsequent changes made to the Frame using the supplied pointer + will have no effect the Region. + } + \sstsubsection{ + npnt + }{ + The number of points in the Region. + } + \sstsubsection{ + ncoord + }{ + The number of coordinates being supplied for each point. This + must equal the number of axes in the supplied Frame, given by + its \htmlref{Naxes}{Naxes} attribute. + } + \sstsubsection{ + dim + }{ + The number of elements along the second dimension of the \texttt{"} points\texttt{"} + array (which contains the point coordinates). This value is + required so that the coordinate values can be correctly + located if they do not entirely fill this array. The value + given should not be less than \texttt{"} npnt\texttt{"} . + } + \sstsubsection{ + points + }{ + The address of the first element of a 2-dimensional array of + shape \texttt{"} [ncoord][dim]\texttt{"} giving the physical coordinates of the + points. These should be stored such that the value of coordinate + number \texttt{"} coord\texttt{"} for point number \texttt{"} pnt\texttt{"} is found in element + \texttt{"} in[coord][pnt]\texttt{"} . + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the uncertainties + associated with each point in the PointList being created. The + uncertainty at any point in the PointList is found by shifting the + supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at the point + being considered. The area covered by the shifted uncertainty Region + then represents the uncertainty in the position. The uncertainty is + assumed to be the same for all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Box. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the bounding box of the + PointList being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new PointList. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPointList() + }{ + A pointer to the new PointList. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astPolyCurve +}{ + Draw a series of connected geodesic curves +}{ + \sstdescription{ + This function joins a series of points specified in the physical + coordinate system of a \htmlref{Plot}{Plot} by drawing a sequence of geodesic + curves. It is equivalent to making repeated use of the \htmlref{astCurve}{astCurve} + function (q.v.), except that astPolyCurve will generally be more + efficient when drawing many geodesic curves end-to-end. A + typical application of this might be in drawing contour lines. + + As with astCurve, full account is taken of the \htmlref{Mapping}{Mapping} between + physical and graphical coordinate systems. This includes any + discontinuities and clipping established using \htmlref{astClip}{astClip}. + } + \sstsynopsis{ + void astPolyCurve( AstPlot $*$this, int npoint, int ncoord, int indim, + const double $*$in ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + npoint + }{ + The number of points between which geodesic curves are to be drawn. + } + \sstsubsection{ + ncoord + }{ + The number of coordinates being supplied for each point (i.e. + the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given + by its \htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + indim + }{ + The number of elements along the second dimension of the \texttt{"} in\texttt{"} + array (which contains the input coordinates). This value is + required so that the coordinate values can be correctly + located if they do not entirely fill this array. The value + given should not be less than \texttt{"} npoint\texttt{"} . + } + \sstsubsection{ + in + }{ + The address of the first element in a 2-dimensional array of shape + \texttt{"} [ncoord][indim]\texttt{"} giving the + physical coordinates of the points which are to be joined in + sequence by geodesic curves. These should be stored such that + the value of coordinate number \texttt{"} coord\texttt{"} for point number + \texttt{"} point\texttt{"} is found in element \texttt{"} in[coord][point]\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + No curve is drawn on either side of any point which has any + coordinate equal to the value AST\_\_BAD. + + \sstitem + An error results if the base Frame of the Plot is not + 2-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astPolyMap +}{ + Create a PolyMap +}{ + \sstdescription{ + This function creates a new \htmlref{PolyMap}{PolyMap} and optionally initialises + its attributes. + + A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial + transformation. Each output coordinate is a polynomial function of + all the input coordinates. The coefficients are specified separately + for each output coordinate. The forward and inverse transformations + are defined independantly by separate sets of coefficients. If no + inverse transformation is supplied, an iterative method can be used + to evaluate the inverse based only on the forward transformation. + } + \sstsynopsis{ + AstPolyMap $*$astPolyMap( int nin, int nout, int ncoeff\_f, const double coeff\_f[], + int ncoeff\_i, const double coeff\_i[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nin + }{ + The number of input coordinates. + } + \sstsubsection{ + nout + }{ + The number of output coordinates. + } + \sstsubsection{ + ncoeff\_f + }{ + The number of non-zero coefficients necessary to define the + forward transformation of the PolyMap. If zero is supplied, the + forward transformation will be undefined. + } + \sstsubsection{ + coeff\_f + }{ + An array containing + \texttt{"} ncoeff\_f$*$( 2 $+$ nin )\texttt{"} elements. Each group of \texttt{"} 2 $+$ nin\texttt{"} + adjacent elements describe a single coefficient of the forward + transformation. Within each such group, the first element is the + coefficient value; the next element is the integer index of the + PolyMap output which uses the coefficient within its defining + polynomial (the first output has index 1); the remaining elements + of the group give the integer powers to use with each input + coordinate value (powers must not be negative, and floating + point values are rounded to the nearest integer). + If \texttt{"} ncoeff\_f\texttt{"} is zero, a NULL pointer may be supplied for \texttt{"} coeff\_f\texttt{"} . + + For instance, if the PolyMap has 3 inputs and 2 outputs, each group + consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"} + describes a coefficient with value 1.2 which is used within the + definition of output 2. The output value is incremented by the + product of the coefficient value, the value of input coordinate + 1 raised to the power 1, and the value of input coordinate 2 raised + to the power 3. Input coordinate 3 is not used since its power is + specified as zero. As another example, the group \texttt{"} (-1.0, 1.0, + 0.0, 0.0, 0.0 )\texttt{"} describes adds a constant value -1.0 onto + output 1 (it is a constant value since the power for every input + axis is given as zero). + + Each final output coordinate value is the sum of the \texttt{"} ncoeff\_f\texttt{"} terms + described by the \texttt{"} ncoeff\_f\texttt{"} groups within the supplied array. + } + \sstsubsection{ + ncoeff\_i + }{ + The number of non-zero coefficients necessary to define the + inverse transformation of the PolyMap. If zero is supplied, the + inverse transformation will be undefined. + } + \sstsubsection{ + coeff\_i + }{ + An array containing + \texttt{"} ncoeff\_i$*$( 2 $+$ nout )\texttt{"} elements. Each group of \texttt{"} 2 $+$ nout\texttt{"} + adjacent elements describe a single coefficient of the inverse + transformation, using the same schame as \texttt{"} coeff\_f\texttt{"} , + except that \texttt{"} inputs\texttt{"} and \texttt{"} outputs\texttt{"} are transposed. + If \texttt{"} ncoeff\_i\texttt{"} is zero, a NULL pointer may be supplied for \texttt{"} coeff\_i\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new PolyMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPolyMap() + }{ + A pointer to the new PolyMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPolyTran +}{ + Fit a PolyMap inverse or forward transformation +}{ + \sstdescription{ + This function creates a new \htmlref{PolyMap}{PolyMap} which is a copy of the supplied + PolyMap, in which a specified transformation (forward or inverse) + has been replaced by a new polynomial transformation. The + coefficients of the new transformation are estimated by sampling + the other transformation and performing a least squares polynomial + fit in the opposite direction to the sampled positions and values. + + This method can only be used on (1-input,1-output) or (2-input,2-output) + PolyMaps. + + The transformation to create is specified by the + \texttt{"} forward\texttt{"} parameter. + In what follows \texttt{"} X\texttt{"} refers to the inputs of the PolyMap, and \texttt{"} Y\texttt{"} to + the outputs of the PolyMap. The forward transformation transforms + input values (X) into output values (Y), and the inverse transformation + transforms output values (Y) into input values (X). Within a PolyMap, + each transformation is represented by an independent set of + polynomials, P\_f or P\_i: Y=P\_f(X) for the forward transformation and + X=P\_i(Y) for the inverse transformation. + + The \texttt{"} forward\texttt{"} + parameter specifies the transformation to be replaced. If it is + non-zero, + a new forward transformation is created + by first finding the input values (X) using the inverse transformation + (which must be available) at a regular grid of points (Y) covering a + rectangular region of the PolyMap\texttt{'} s output space. The coefficients of + the required forward polynomial, Y=P\_f(X), are chosen in order to + minimise the sum of the squared residuals between the sampled values + of Y and P\_f(X). + + If \texttt{"} forward\texttt{"} is zero (probably the most likely case), + a new inverse transformation is created by + first finding the output values (Y) using the forward transformation + (which must be available) at a regular grid of points (X) covering a + rectangular region of the PolyMap\texttt{'} s input space. The coefficients of + the required inverse polynomial, X=P\_i(Y), are chosen in order to + minimise the sum of the squared residuals between the sampled values + of X and P\_i(Y). + + This fitting process is performed repeatedly with increasing + polynomial orders (starting with linear) until the target + accuracy is achieved, or a specified maximum order is reached. If + the target accuracy cannot be achieved even with this maximum-order + polynomial, the best fitting maximum-order polynomial is returned so + long as its accuracy is better than + \texttt{"} maxacc\texttt{"} . + If it is not, an error is reported. + } + \sstsynopsis{ + AstPolyMap $*$astPolyTran( AstPolyMap $*$this, int forward, double acc, + double maxacc, int maxorder, const double $*$lbnd, + const double $*$ubnd ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the original \htmlref{Mapping}{Mapping}. + } + \sstsubsection{ + forward + }{ + If non-zero, + the forward PolyMap transformation is replaced. Otherwise the + inverse transformation is replaced. + } + \sstsubsection{ + acc + }{ + The target accuracy, expressed as a geodesic distance within + the PolyMap\texttt{'} s input space (if + \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). + } + \sstsubsection{ + maxacc + }{ + The maximum allowed accuracy for an acceptable polynomial, + expressed as a geodesic distance within the PolyMap\texttt{'} s input + space (if + \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). + } + \sstsubsection{ + maxorder + }{ + The maximum allowed polynomial order. This is one more than the + maximum power of either input axis. So for instance, a value of + 3 refers to a quadratic polynomial. Note, cross terms with total + powers greater than or equal to + maxorder + are not inlcuded in the fit. So the maximum number of terms in + each of the fitted polynomials is + maxorder$*$(maxorder$+$1)/2. + } + \sstsubsection{ + lbnd + }{ + Pointer to an + array holding the lower bounds of a rectangular region within + the PolyMap\texttt{'} s input space (if + \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). + The new polynomial will be evaluated over this rectangle. The + length of this array should equal the value of the PolyMap\texttt{'} s \htmlref{Nin}{Nin} + or \htmlref{Nout}{Nout} attribute, depending on + \texttt{"} forward\texttt{"} . + } + \sstsubsection{ + ubnd + }{ + Pointer to an + array holding the upper bounds of a rectangular region within + the PolyMap\texttt{'} s input space (if + \texttt{"} forward\texttt{"} is zero) or output space (if \texttt{"} forward\texttt{"} is non-zero). + The new polynomial will be evaluated over this rectangle. The + length of this array should equal the value of the PolyMap\texttt{'} s Nin + or Nout attribute, depending on + \texttt{"} forward\texttt{"} . + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPolyTran() + }{ + A pointer to the new PolyMap. + A NULL pointer + will be returned if the fit fails to achieve the accuracy + specified by + \texttt{"} maxacc\texttt{"} , + but no error will be reported. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function can only be used on 1D or 2D PolyMaps which have + the same number of inputs and outputs. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPolygon +}{ + Create a Polygon +}{ + \sstdescription{ + This function creates a new \htmlref{Polygon}{Polygon} object and optionally initialises + its attributes. + + The Polygon class implements a polygonal area, defined by a + collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices + are connected together by geodesic curves within the encapsulated Frame. + For instance, if the encapsulated Frame is a simple Frame then the + geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then + the geodesics will be great circles. Note, the vertices must be + supplied in an order such that the inside of the polygon is to the + left of the boundary as the vertices are traversed. Supplying them + in the reverse order will effectively negate the polygon. + + Within a SkyFrame, neighbouring vertices are always joined using the + shortest path. Thus if an edge of 180 degrees or more in length is + required, it should be split into section each of which is less + than 180 degrees. The closed path joining all the vertices in order + will divide the celestial sphere into two disjoint regions. The + inside of the polygon is the region which is circled in an + anti-clockwise manner (when viewed from the inside of the celestial + sphere) when moving through the list of vertices in the order in + which they were supplied when the Polygon was created (i.e. the + inside is to the left of the boundary when moving through the + vertices in the order supplied). + } + \sstsynopsis{ + AstPolygon $*$astPolygon( AstFrame $*$frame, int npnt, int dim, + const double $*$points, AstRegion $*$unc, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame + }{ + A pointer to the Frame in which the region is defined. It must + have exactly 2 axes. A deep copy is taken of the supplied Frame. + This means that any subsequent changes made to the Frame using the + supplied pointer will have no effect the \htmlref{Region}{Region}. + } + \sstsubsection{ + npnt + }{ + The number of points in the Region. + } + \sstsubsection{ + dim + }{ + The number of elements along the second dimension of the \texttt{"} points\texttt{"} + array (which contains the point coordinates). This value is + required so that the coordinate values can be correctly + located if they do not entirely fill this array. The value + given should not be less than \texttt{"} npnt\texttt{"} . + } + \sstsubsection{ + points + }{ + The address of the first element of a 2-dimensional array of + shape \texttt{"} [2][dim]\texttt{"} giving the physical coordinates of the vertices. + These should be stored such that the value of coordinate + number \texttt{"} coord\texttt{"} for point number \texttt{"} pnt\texttt{"} is found in element + \texttt{"} in[coord][pnt]\texttt{"} . + } + \sstsubsection{ + unc + }{ + An optional pointer to an existing Region which specifies the + uncertainties associated with the boundary of the Polygon being created. + The uncertainty in any point on the boundary of the Polygon is found by + shifting the supplied \texttt{"} uncertainty\texttt{"} Region so that it is centred at + the boundary point being considered. The area covered by the + shifted uncertainty Region then represents the uncertainty in the + boundary position. The uncertainty is assumed to be the same for + all points. + + If supplied, the uncertainty Region must be of a class for which + all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.) + or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep + copy of the supplied Region will be taken, so subsequent changes to + the uncertainty Region using the supplied pointer will have no + effect on the created Polygon. Alternatively, + a NULL \htmlref{Object}{Object} pointer + may be supplied, in which case a default uncertainty is used + equivalent to a box 1.0E-6 of the size of the Polygon being created. + + The uncertainty Region has two uses: 1) when the + \htmlref{astOverlap}{astOverlap} + function compares two Regions for equality the uncertainty + Region is used to determine the tolerance on the comparison, and 2) + when a Region is mapped into a different coordinate system and + subsequently simplified (using + \htmlref{astSimplify}{astSimplify}), + the uncertainties are used to determine if the transformed boundary + can be accurately represented by a specific shape of Region. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Polygon. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPolygon() + }{ + A pointer to the new Polygon. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astPrism +}{ + Create a Prism +}{ + \sstdescription{ + This function creates a new \htmlref{Prism}{Prism} and optionally initialises + its attributes. + + A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region + into one or more orthogonal dimensions (specified by another Region). + If the Region to be extruded has N axes, and the Region defining the + extrusion has M axes, then the resulting Prism will have (M$+$N) axes. + A point is inside the Prism if the first N axis values correspond to + a point inside the Region being extruded, and the remaining M axis + values correspond to a point inside the Region defining the extrusion. + + As an example, a cylinder can be represented by extruding an existing + \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the + Interval would have a single axis and would specify the upper and + lower limits of the cylinder along its length. + } + \sstsynopsis{ + AstPrism $*$astPrism( AstRegion $*$region1, AstRegion $*$region2, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region1 + }{ + Pointer to the Region to be extruded. + } + \sstsubsection{ + region2 + }{ + Pointer to the Region defining the extent of the extrusion. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Prism. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astPrism() + }{ + A pointer to the new Prism. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Deep copies are taken of the supplied Regions. This means that + any subsequent changes made to the component Regions using the + supplied pointers will have no effect on the Prism. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astPurgeRows +}{ + Remove all empty rows from a table +}{ + \sstdescription{ + This function removes all empty rows from the \htmlref{Table}{Table}, renaming + the key associated with each table cell accordingly. + } + \sstsynopsis{ + void astPurgeRows( AstTable $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + } +} +\sstroutine{ + astPurgeWCS +}{ + Delete all cards in the FitsChan describing WCS information +}{ + \sstdescription{ + This function + deletes all cards in a \htmlref{FitsChan}{FitsChan} that relate to any of the recognised + WCS encodings. On exit, the current card is the first remaining card + in the FitsChan. + } + \sstsynopsis{ + void astPurgeWCS( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } +} +\sstroutine{ + astPutCards +}{ + Store a set of FITS header cards in a FitsChan +}{ + \sstdescription{ + This function + stores a set of FITS header cards in a \htmlref{FitsChan}{FitsChan}. The cards are + supplied concatenated together into a single character string. + Any existing cards in the FitsChan are removed before the new cards + are added. The FitsChan is \texttt{"} re-wound\texttt{"} on exit by clearing its \htmlref{Card}{Card} + attribute. This means that a subsequent invocation of + \htmlref{astRead}{astRead} + can be made immediately without the need to re-wind the FitsChan + first. + } + \sstsynopsis{ + void astPutCards( AstFitsChan $*$this, const char $*$cards ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + cards + }{ + Pointer to a null-terminated character string + containing the FITS cards to be stored. Each individual card + should occupy 80 characters in this string, and there should be + no delimiters, new lines, etc, between adjacent cards. The final + card may be less than 80 characters long. + This is the format produced by the fits\_hdr2str function in the + CFITSIO library. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error will result if the supplied string contains any cards + which cannot be interpreted. + } + } +} +\sstroutine{ + astPutChannelData +}{ + Store arbitrary data to be passed to a source or sink function +}{ + \sstdescription{ + This function stores a supplied arbitrary pointer in the \htmlref{Channel}{Channel}. + When a source or sink function is invoked by the Channel, the + invoked function can use the \htmlref{astChannelData}{astChannelData} macro to retrieve the + pointer. This provides a thread-safe alternative to passing file + descriptors, etc, via global static variables. + } + \sstsynopsis{ + void astPutChannelData( AstChannel $*$this, void $*$data ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Channel. + } + \sstsubsection{ + data + }{ + A pointer to be made available to the source and sink functions + via the astChannelData macro. May be NULL. + } + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + All Channels have this function. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This routine is not available in the Fortran 77 interface to + the AST library. + } + } +} +\sstroutine{ + astPutColumnData +}{ + Store new data values for all rows of a column +}{ + \sstdescription{ + This function + copies data values from a supplied buffer into a named column. The + first element in the buffer becomes the first element in the first + row of the column. If the buffer does not completely fill the + column, then any trailing rows are filled with null values. + } + \sstsynopsis{ + void astPutColumnData( AstFitsTable $*$this, const char $*$column, + int clen, size\_t size, void $*$coldata ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{FitsTable}{FitsTable}. + } + \sstsubsection{ + column + }{ + The character string holding the name of the column. Trailing + spaces are ignored. + } + \sstsubsection{ + clen + }{ + If the column holds character strings, then this must be set to + the length of each fixed length string in the supplied array. + This is often determined by the appropriate TFORMn keyword in + the binary table header. The supplied value is ignored if the + column does not hold character data. + } + \sstsubsection{ + size + }{ + The size of the + \texttt{"} coldata\texttt{"} + array, in bytes. This should be an integer multiple of the + number of bytes needed to hold the full vector value stored in a + single cell of the column. An error is reported if this is not + the case. + } + \sstsubsection{ + coldata + }{ + A pointer to an + area of memory holding the data to copy into the column. The values + should be stored in row order. If the column holds non-scalar values, + the elements of each value should be stored in \texttt{"} Fortran\texttt{"} order. No + data type conversion is performed. + } + } +} +\sstroutine{ + astPutFits +}{ + Store a FITS header card in a FitsChan +}{ + \sstdescription{ + This function stores a FITS header card in a \htmlref{FitsChan}{FitsChan}. The card + is either inserted before the current card (identified by the + \htmlref{Card}{Card} attribute), or over-writes the current card, as required. + } + \sstsynopsis{ + void astPutFits( AstFitsChan $*$this, const char card[ 80 ], + int overwrite ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + card + }{ + Pointer to a possibly null-terminated character string + containing the FITS card to be stored. No more than 80 + characters will be used from this string (or fewer if a null + occurs earlier). + } + \sstsubsection{ + overwrite + }{ + If this value is zero, the new card is inserted in front of + the current card in the FitsChan (as identified by the + initial value of the Card attribute). If it is non-zero, the + new card replaces the current card. In either case, the Card + attribute is then incremented by one so that it subsequently + identifies the card following the one stored. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the Card attribute initially points at the \texttt{"} end-of-file\texttt{"} + (i.e. exceeds the number of cards in the FitsChan), then the new + card is appended as the last card in the FitsChan. + + \sstitem + An error will result if the supplied string cannot be interpreted + as a FITS header card. + } + } +} +\sstroutine{ + astPutTable +}{ + Store a single FitsTable in a FitsChan +}{ + \sstdescription{ + This function + allows a representation of a single FITS binary table to be + stored in a \htmlref{FitsChan}{FitsChan}. For instance, this may provide the coordinate + look-up tables needed subequently when reading FITS-WCS headers + for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, + the calling application may not know which tables will be needed - + if any - prior to calling + \htmlref{astRead}{astRead}, the astTablesSource function + provides an alternative mechanism in which a caller-supplied + function is invoked to store a named table in the FitsChan. + } + \sstsynopsis{ + void astPutTable( AstFitsChan $*$this, AstFitsTable $*$table, + const char $*$extnam ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + table + }{ + Pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. If a FitsTable + with the associated extension name already exists in the FitsChan, + it is replaced with the new one. A deep copy of the FitsTable is + stored in the FitsChan, so any subsequent changes made to the + FitsTable will have no effect on the behaviour of the FitsChan. + } + \sstsubsection{ + extnam + }{ + The name of the FITS extension associated with the table. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Tables stored in the FitsChan may be retrieved using + \htmlref{astGetTables}{astGetTables}. + + \sstitem + The \htmlref{astPutTables}{astPutTables} method can add multiple FitsTables in a single call. + } + } +} +\sstroutine{ + astPutTableHeader +}{ + Store new FITS headers in a FitsTable +}{ + \sstdescription{ + This function + stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing + headers are first deleted. + } + \sstsynopsis{ + void astPutTableHeader( AstFitsTable $*$this, AstFitsChan $*$header ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsTable. + } + \sstsubsection{ + header + }{ + Pointer to a \htmlref{FitsChan}{FitsChan} holding the headers for the FitsTable. + A deep copy of the supplied FitsChan is stored in the FitsTable, + replacing the current FitsChan in the Fitstable. Keywords that + are fixed either by the properties of the \htmlref{Table}{Table}, or by the FITS + standard, are removed from the copy (see \texttt{"} Notes:\texttt{"} below). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The attributes of the supplied FitsChan, together with any source + and sink functions associated with the FitsChan, are copied to the + FitsTable. + + \sstitem + Values for the following keywords are generated automatically by + the FitsTable (any values for these keywords in the supplied + FitsChan will be ignored): \texttt{"} XTENSION\texttt{"} , \texttt{"} BITPIX\texttt{"} , \texttt{"} NAXIS\texttt{"} , \texttt{"} NAXIS1\texttt{"} , + \texttt{"} NAXIS2\texttt{"} , \texttt{"} PCOUNT\texttt{"} , \texttt{"} GCOUNT\texttt{"} , \texttt{"} TFIELDS\texttt{"} , \texttt{"} TFORM\%d\texttt{"} , \texttt{"} TTYPE\%d\texttt{"} , + \texttt{"} TNULL\%d\texttt{"} , \texttt{"} THEAP\texttt{"} , \texttt{"} TDIM\%d\texttt{"} . + } + } +} +\sstroutine{ + astPutTables +}{ + Store one or more FitsTables in a FitsChan +}{ + \sstdescription{ + This function + allows representations of one or more FITS binary tables to be + stored in a \htmlref{FitsChan}{FitsChan}. For instance, these may provide the coordinate + look-up tables needed subequently when reading FITS-WCS headers + for axes described using the \texttt{"} -TAB\texttt{"} algorithm. Since, in general, + the calling application may not know which tables will be needed - + if any - prior to calling + \htmlref{astRead}{astRead}, the astTablesSource function + provides an alternative mechanism in which a caller-supplied + function is invoked to store a named table in the FitsChan. + } + \sstsynopsis{ + void astPutTables( AstFitsChan $*$this, AstKeyMap $*$tables ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + tables + }{ + Pointer to a \htmlref{KeyMap}{KeyMap} holding the tables that are to be added + to the FitsChan. Each entry should hold a scalar value which is a + pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. Any unusable + entries are ignored. The key associated with each entry should be + the name of the FITS binary extension from which the table was + read. If a FitsTable with the associated key already exists in the + FitsChan, it is replaced with the new one. A deep copy of each + usable FitsTable is stored in the FitsChan, so any subsequent + changes made to the FitsTables will have no effect on the + behaviour of the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Tables stored in the FitsChan may be retrieved using + \htmlref{astGetTables}{astGetTables}. + + \sstitem + The tables in the supplied KeyMap are added to any tables already + in the FitsChan. + + \sstitem + The \htmlref{astPutTable}{astPutTable} + method provides a simpler means of adding a single table to a FitsChan. + } + } +} +\sstroutine{ + astQuadApprox +}{ + Obtain a quadratic approximation to a 2D Mapping +}{ + \sstdescription{ + This function returns the co-efficients of a quadratic fit to the + supplied \htmlref{Mapping}{Mapping} over the input area specified by + \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} . + The Mapping must have 2 inputs, but may have any number of outputs. + The i\texttt{'} th Mapping output is modelled as a quadratic function of the + 2 inputs (x,y): + + output\_i = a\_i\_0 $+$ a\_i\_1$*$x $+$ a\_i\_2$*$y $+$ a\_i\_3$*$x$*$y $+$ a\_i\_4$*$x$*$x $+$ + a\_i\_5$*$y$*$y + + The \texttt{"} fit\texttt{"} + array is returned holding the values of the co-efficients a\_0\_0, + a\_0\_1, etc. + } + \sstsynopsis{ + int QuadApprox( AstMapping $*$this, const double lbnd[2], + const double ubnd[2], int nx, int ny, double $*$fit, + double $*$rms ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of doubles + containing the lower bounds of a box defined within the input + coordinate system of the Mapping. The number of elements in this + array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This + box should specify the region over which the fit is to be + performed. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of doubles + containing the upper bounds of the box specifying the region over + which the fit is to be performed. + } + \sstsubsection{ + nx + }{ + The number of points to place along the first Mapping input. The + first point is at + \texttt{"} lbnd[0]\texttt{"} and the last is at \texttt{"} ubnd[0]\texttt{"} . + If a value less than three is supplied a value of three will be used. + } + \sstsubsection{ + ny + }{ + The number of points to place along the second Mapping input. The + first point is at + \texttt{"} lbnd[1]\texttt{"} and the last is at \texttt{"} ubnd[1]\texttt{"} . + If a value less than three is supplied a value of three will be used. + } + \sstsubsection{ + fit + }{ + Pointer to an array of doubles + in which to return the co-efficients of the quadratic + approximation to the specified transformation. This array should + have at least \texttt{"} 6$*$\htmlref{Nout}{Nout}\texttt{"} , elements. The first 6 elements hold the + fit to the first Mapping output. The next 6 elements hold the + fit to the second Mapping output, etc. So if the Mapping has 2 + inputs and 2 outputs the quadratic approximation to the forward + transformation is: + + X\_out = fit[0] $+$ fit[1]$*$X\_in $+$ fit[2]$*$Y\_in $+$ fit[3]$*$X\_in$*$Y\_in $+$ + fit[4]$*$X\_in$*$X\_in $+$ fit[5]$*$Y\_in$*$Y\_in + Y\_out = fit[6] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in $+$ fit[9]$*$X\_in$*$Y\_in $+$ + fit[10]$*$X\_in$*$X\_in $+$ fit[11]$*$Y\_in$*$Y\_in + } + \sstsubsection{ + rms + }{ + Pointer to a double in which to return the + RMS residual between the fit and the Mapping, summed over all + Mapping outputs. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astQuadApprox() + }{ + If a quadratic approximation was created, + a non-zero value is returned. Otherwise zero is returned + and the fit co-efficients are set to AST\_\_BAD. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function fits the Mapping\texttt{'} s forward transformation. To fit + the inverse transformation, the Mapping should be inverted using + \htmlref{astInvert}{astInvert} + before invoking this function. + + \sstitem + A value of zero + will be returned if this function is invoked + with the global error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astRate +}{ + Calculate the rate of change of a Mapping output +}{ + \sstdescription{ + This function + evaluates the rate of change of a specified output of the supplied + \htmlref{Mapping}{Mapping} with respect to a specified input, at a specified input + position. + + The result is estimated by interpolating the function using a + fourth order polynomial in the neighbourhood of the specified + position. The size of the neighbourhood used is chosen to minimise + the RMS residual per unit length between the interpolating + polynomial and the supplied Mapping function. This method produces + good accuracy but can involve evaluating the Mapping 100 or more + times. + } + \sstsynopsis{ + double astRate( AstMapping $*$this, double $*$at, int ax1, int ax2 ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + at + }{ + The address of an + array holding the axis values at the position at which the rate + of change is to be evaluated. The number of elements in this + array should equal the number of inputs to the Mapping. + } + \sstsubsection{ + ax1 + }{ + The index of the Mapping output for which the rate of change is to + be found (output numbering starts at 1 for the first output). + } + \sstsubsection{ + ax2 + }{ + The index of the Mapping input which is to be varied in order to + find the rate of change (input numbering starts at 1 for the first + input). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astRate() + }{ + The rate of change of Mapping output \texttt{"} ax1\texttt{"} with respect to input + \texttt{"} ax2\texttt{"} , evaluated at \texttt{"} at\texttt{"} , or AST\_\_BAD if the value cannot be + calculated. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of AST\_\_BAD will be returned if this function is invoked + with the global error status set, or if it should fail for any + reason. + } + } +} +\sstroutine{ + astRateMap +}{ + Create a RateMap +}{ + \sstdescription{ + This function creates a new \htmlref{RateMap}{RateMap} and optionally initialises + its attributes. + + A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the + Jacobian matrix of another Mapping. The Mapping for which the + Jacobian is required is specified when the new RateMap is created, + and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. + + The number of inputs to a RateMap is the same as the number of inputs + to its encapsulated Mapping. The number of outputs from a RateMap + is always one. This one output equals the rate of change of a + specified output of the encapsulated Mapping with respect to a + specified input of the encapsulated Mapping (the input and output + to use are specified when the RateMap is created). + + A RateMap which has not been inverted does not define an inverse + transformation. If a RateMap has been inverted then it will define + an inverse transformation but not a forward transformation. + } + \sstsynopsis{ + AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + map + }{ + Pointer to the encapsulated Mapping. + } + \sstsubsection{ + ax1 + }{ + Index of the output from the encapsulated Mapping for which the + rate of change is required. This corresponds to the delta + quantity forming the numerator of the required element of the + Jacobian matrix. The first axis has index 1. + } + \sstsubsection{ + ax2 + }{ + Index of the input to the encapsulated Mapping which is to be + varied. This corresponds to the delta quantity forming the + denominator of the required element of the Jacobian matrix. + The first axis has index 1. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new RateMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astRateMap() + }{ + A pointer to the new RateMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The forward transformation of the encapsulated Mapping must be + defined. + + \sstitem + Note that the component Mappings supplied are not copied by + astRateMap (the new RateMap simply retains a reference to + them). They may continue to be used for other purposes, but + should not be deleted. If a RateMap containing a copy of its + component Mappings is required, then a copy of the RateMap should + be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astRead +}{ + Read an Object from a Channel +}{ + \sstdescription{ + This function reads the next \htmlref{Object}{Object} from a \htmlref{Channel}{Channel} and returns a + pointer to the new Object. + } + \sstsynopsis{ + AstObject $*$astRead( AstChannel $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Channel. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + All successful use of astRead on a FitsChan is destructive, so that + FITS header cards are consumed in the process of reading an Object, + and are removed from the FitsChan (this deletion can be prevented + for specific cards by calling the FitsChan + \htmlref{astRetainFits}{astRetainFits} function). + An unsuccessful call of + astRead + (for instance, caused by the FitsChan not containing the necessary + FITS headers cards needed to create an Object) results in the + contents of the FitsChan being left unchanged. + } + \sstsubsection{ + \htmlref{StcsChan}{StcsChan} + }{ + The AST Object returned by a successful use of + astRead + on an StcsChan, will be either a \htmlref{Region}{Region} or a \htmlref{KeyMap}{KeyMap}, depending + on the values of the \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} + attributes. See the documentation for these attributes for further + information. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astRead() + }{ + A pointer to the new Object. The class to which this will + belong is determined by the input data, so is not known in + advance. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned, without + error, if the Channel contains no further Objects to be read. + + \sstitem + A null Object pointer will also be returned if this function + is invoked with the AST error status set, or if it should fail + for any reason. + } + } +} +\sstroutine{ + astReadFits +}{ + Read cards into a FitsChan from the source function +}{ + \sstdescription{ + This function + reads cards from the source function that was specified when the + \htmlref{FitsChan}{FitsChan} was created, and stores them in the FitsChan. This + normally happens once-only, when the FitsChan is accessed for the + first time. + This function + provides a means of forcing a re-read of the external source, and + may be useful if (say) new cards have been deposited into the + external source. Any newcards read from the source are appended to + the end of the current contents of the FitsChan. + } + \sstsynopsis{ + void astReadFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function returns without action if no source function was + specified when the FitsChan was created. + + \sstitem + The \htmlref{SourceFile}{SourceFile} attribute is ignored by this + function. + New cards are read from the source file whenever a new value is + assigned to the SourceFile attribute. + } + } +} +\sstroutine{ + astRebin$<$X$>$ +}{ + Rebin a region of a data grid +}{ + \sstdescription{ + This is a set of functions for rebinning gridded data (e.g. an + image) under the control of a geometrical transformation, which + is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of + data grids (input and output), each of which may have any number + of dimensions. Rebinning may be restricted to a specified + region of the input grid. An associated grid of error estimates + associated with the input data may also be supplied (in the form + of variance values), so as to produce error estimates for the + rebined output data. Propagation of missing data (bad pixels) + is supported. + + Note, if you will be rebining a sequence of input arrays and then + co-adding them into a single array, the alternative + \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} functions + will in general be more efficient. + + You should use a rebinning function which matches the numerical + type of the data you are processing by replacing $<$X$>$ in + the generic function name astRebin$<$X$>$ by an appropriate 1- or + 2-character type code. For example, if you are rebinning data + with type \texttt{"} float\texttt{"} , you should use the function astRebinF (see + the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to + other numerical types). + + Rebinning of the grid of input data is performed by transforming + the coordinates of the centre of each input grid element (or pixel) + into the coordinate system of the output grid. The input pixel + value is then divided up and assigned to the output pixels in the + neighbourhood of the central output coordinates. A choice of + schemes are provided for determining how each input pixel value is + divided up between the output pixels. In general, each output pixel + may be assigned values from more than one input pixel. All + contributions to a given output pixel are summed to produce the + final output pixel value. Output pixels can be set to the supplied + bad value if they receive contributions from an insufficient number + of input pixels. This is controlled by the + \texttt{"} wlim\texttt{"} parameter. + + Input pixel coordinates are transformed into the coordinate + system of the output grid using the forward transformation of the + Mapping which is supplied. This means that geometrical features + in the input data are subjected to the Mapping\texttt{'} s forward + transformation as they are transferred from the input to the + output grid. + + In practice, transforming the coordinates of every pixel of a + large data grid can be time-consuming, especially if the Mapping + involves complicated functions, such as sky projections. To + improve performance, it is therefore possible to approximate + non-linear Mappings by a set of linear transformations which are + applied piece-wise to separate sub-regions of the data. This + approximation process is applied automatically by an adaptive + algorithm, under control of an accuracy criterion which + expresses the maximum tolerable geometrical distortion which may + be introduced, as a fraction of a pixel. + + This algorithm first attempts to approximate the Mapping with a + linear transformation applied over the whole region of the + input grid which is being used. If this proves to be + insufficiently accurate, the input region is sub-divided into + two along its largest dimension and the process is repeated + within each of the resulting sub-regions. This process of + sub-division continues until a sufficiently good linear + approximation is found, or the region to which it is being + applied becomes too small (in which case the original Mapping is + used directly). + } + \sstsynopsis{ + void astRebin$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in, + const int lbnd\_in[], const int ubnd\_in[], + const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], + int spread, const double params[], int flags, + double tol, int maxpix, + $<$Xtype$>$ badval, int ndim\_out, + const int lbnd\_out[], const int ubnd\_out[], + const int lbnd[], const int ubnd[], + $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to a Mapping, whose forward transformation will be + used to transform the coordinates of pixels in the input + grid into the coordinate system of the output grid. + + The number of input coordinates used by this Mapping (as + given by its \htmlref{Nin}{Nin} attribute) should match the number of input + grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} + below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} + attribute) should match the number of output grid dimensions + given by \texttt{"} ndim\_out\texttt{"} . + } + \sstsubsection{ + wlim + }{ + Gives the required number of input pixel values which must contribute + to an output pixel in order for the output pixel value to be + considered valid. If the sum of the input pixel weights contributing + to an output pixel is less than the supplied + \texttt{"} wlim\texttt{"} + value, then the output pixel value is returned set to the + supplied bad value. + } + \sstsubsection{ + ndim\_in + }{ + The number of dimensions in the input grid. This should be at + least one. + } + \sstsubsection{ + lbnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre. + } + \sstsubsection{ + in + }{ + Pointer to an array, with one element for each pixel in the + input grid, containing the input data to be rebined. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astRebinF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + in\_var + }{ + An optional pointer to a second array with the same size and + type as the \texttt{"} in\texttt{"} array. If given, this should contain a set + of non-negative values which represent estimates of the + statistical variance associated with each element of the \texttt{"} in\texttt{"} + array. If this array is supplied (together with the + corresponding \texttt{"} out\_var\texttt{"} array), then estimates of the + variance of the rebined output data will be calculated. + + If no input variance estimates are being provided, a NULL + pointer should be given. + } + \sstsubsection{ + spread + }{ + This parameter specifies the scheme to be used for dividing + each input data value up amongst the corresponding output pixels. + It may be used to select + from a set of pre-defined schemes by supplying one of the + values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} + section below. If a value of zero is supplied, then the + default linear spreading scheme is used (equivalent to + supplying the value AST\_\_LINEAR). + } + \sstsubsection{ + params + }{ + An optional pointer to an array of double which should contain + any additional parameter values required by the pixel + spreading scheme. If such parameters are required, this + will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} + section below. + + If no additional parameters are required, this array is not + used and a NULL pointer may be given. + } + \sstsubsection{ + flags + }{ + The bitwise OR of a set of flag values which may be used to + provide additional control over the rebinning operation. See + the \texttt{"} Control Flags\texttt{"} section below for a description of the + options available. If no flag values are to be set, a value + of zero should be given. + } + \sstsubsection{ + tol + }{ + The maximum tolerable geometrical distortion which may be + introduced as a result of approximating non-linear Mappings + by a set of piece-wise linear transformations. This should be + expressed as a displacement in pixels in the output grid\texttt{'} s + coordinate system. + + If piece-wise linear approximation is not required, a value + of zero may be given. This will ensure that the Mapping is + used without any approximation, but may increase execution + time. + + If the value is too high, discontinuities between the linear + approximations used in adjacent panel will be higher, and may + cause the edges of the panel to be visible when viewing the output + image at high contrast. If this is a problem, reduce the + tolerance value used. + } + \sstsubsection{ + maxpix + }{ + A value which specifies an initial scale size (in pixels) for + the adaptive algorithm which approximates non-linear Mappings + with piece-wise linear transformations. Normally, this should + be a large value (larger than any dimension of the region of + the input grid being used). In this case, a first attempt to + approximate the Mapping by a linear transformation will be + made over the entire input region. + + If a smaller value is used, the input region will first be + divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} + pixels in any dimension. Only at this point will attempts at + approximation commence. + + This value may occasionally be useful in preventing false + convergence of the adaptive algorithm in cases where the + Mapping appears approximately linear on large scales, but has + irregularities (e.g. holes) on smaller scales. A value of, + say, 50 to 100 pixels can also be employed as a safeguard in + general-purpose software, since the effect on performance is + minimal. + + If too small a value is given, it will have the effect of + inhibiting linear approximation altogether (equivalent to + setting \texttt{"} tol\texttt{"} to zero). Although this may degrade + performance, accurate results will still be obtained. + } + \sstsubsection{ + badval + }{ + This argument should have the same type as the elements of + the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing + data (bad pixels) in the input and output arrays. + + If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, + then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} + (and \texttt{"} in\_var\texttt{"} ) array(s). + + In all cases, this value is also used to flag any output + elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which + rebined values could not be obtained (see the \texttt{"} Propagation + of Missing Data\texttt{"} section below for details of the + circumstances under which this may occur). + } + \sstsubsection{ + ndim\_out + }{ + The number of dimensions in the output grid. This should be + at least one. It need not necessarily be equal to the number + of dimensions in the input grid. + } + \sstsubsection{ + lbnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the output grid along each dimension. + } + \sstsubsection{ + ubnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the output grid along each dimension. + + Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the + shape, size and coordinate system of the output grid in the + same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size + and coordinate system of the input grid. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the first pixel in the region + of the input grid which is to be included in the rebined output + array. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the last pixel in the region of + the input grid which is to be included in the rebined output + array. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and + position of a (hyper-)rectangular region of the input grid + which is to be included in the rebined output array. This region + should lie wholly within the extent of the input grid (as + defined by the \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} arrays). Regions of + the input grid lying outside this region will not be used. + } + \sstsubsection{ + out + }{ + Pointer to an array, with one element for each pixel in the + output grid, in which the rebined data values will be + returned. The numerical type of this array should match that + of the \texttt{"} in\texttt{"} array, and the data storage order should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + out\_var + }{ + An optional pointer to an array with the same type and size + as the \texttt{"} out\texttt{"} array. If given, this array will be used to + return variance estimates for the rebined data values. This + array will only be used if the \texttt{"} in\_var\texttt{"} array has also been + supplied. + + The output variance values will be calculated on the + assumption that errors on the input data values are + statistically independent and that their variance estimates + may simply be summed (with appropriate weighting factors) + when several input pixels contribute to an output data + value. If this assumption is not valid, then the output error + estimates may be biased. In addition, note that the + statistical errors on neighbouring output data values (as + well as the estimates of those errors) may often be + correlated, even if the above assumption about the input data + is correct, because of the pixel spreading schemes + employed. + + If no output variance estimates are required, a NULL pointer + should be given. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate rebinning function, you should + replace $<$X$>$ in the generic function name astRebin$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astRebinD would be used to process \texttt{"} double\texttt{"} + data, while astRebinI would be used to process \texttt{"} int\texttt{"} + data, etc. + + Note that, unlike + \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, the astRebin$<$X$>$ + set of functions does not yet support unsigned integer data types + or integers of different sizes. + } + \sstdiytopic{ + Pixel Spreading Schemes + }{ + The pixel spreading scheme specifies the Point Spread Function (PSF) + applied to each input pixel value as it is copied into the output + array. It can be thought of as the inverse of the sub-pixel + interpolation schemes used by the + astResample$<$X$>$ + group of functions. That is, in a sub-pixel interpolation scheme the + kernel specifies the weight to assign to each input pixel when + forming the weighted mean of the input pixels, whereas the kernel in a + pixel spreading scheme specifies the fraction of the input data value + which is to be assigned to each output pixel. As for interpolation, the + choice of suitable pixel spreading scheme involves stricking a balance + between schemes which tend to degrade sharp features in the data by + smoothing them, and those which attempt to preserve sharp features but + which often tend to introduce unwanted artifacts. See the + astResample$<$X$>$ + documentation for further discussion. + + The binning algorithm used has the ability to introduce artifacts + not seen when using a resampling algorithm. Particularly, when + viewing the output image at high contrast, systems of curves lines + covering the entire image may be visible. These are caused by a + beating effect between the input pixel positions and the output pixels + position, and their nature and strength depend critically upon the + nature of the Mapping and the spreading function being used. In + general, the nearest neighbour spreading function demonstrates this + effect more clearly than the other functions, and for this reason + should be used with caution. + + The following values (defined in the + \texttt{"} ast.h\texttt{"} header file) + may be assigned to the + \texttt{"} spread\texttt{"} + parameter. See the + astResample$<$X$>$ + documentation for details of these schemes including the use of the + \texttt{"} fspread\texttt{"} and \texttt{"} params\texttt{"} parameters: + + \sstitemlist{ + + \sstitem + AST\_\_NEAREST + + \sstitem + AST\_\_LINEAR + + \sstitem + AST\_\_SINC + + \sstitem + AST\_\_SINCSINC + + \sstitem + AST\_\_SINCCOS + + \sstitem + AST\_\_SINCGAUSS + + \sstitem + AST\_\_SOMBCOS + + } + In addition, the following schemes can be used with + astRebin$<$X$>$ but not with astResample$<$X$>$: + + \sstitemlist{ + + \sstitem + AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k + a positive constant determined by the full-width at half-maximum (FWHM). + The FWHM should be supplied in units of output pixels by means of the + \texttt{"} params[1]\texttt{"} + value and should be at least 0.1. The + \texttt{"} params[0]\texttt{"} + value should be used to specify at what point the Gaussian is truncated + to zero. This should be given as a number of output pixels on either + side of the central output point in each dimension (the nearest integer + value is used). + } + } + \sstdiytopic{ + Control Flags + }{ + The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and + may be used to provide additional control over the rebinning + process. Having selected a set of flags, you should supply the + bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: + + \sstitemlist{ + + \sstitem + AST\_\_USEBAD: Indicates that there may be bad pixels in the + input array(s) which must be recognised by comparing with the + value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). + If this flag is not set, all input values are treated literally + and the \texttt{"} badval\texttt{"} value is only used for flagging output array + values. + } + } + \sstdiytopic{ + Propagation of Missing Data + }{ + Instances of missing data (bad pixels) in the output grid are + identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} + array. These are produced if the sum of the weights of the + contributing input pixels is less than + \texttt{"} wlim\texttt{"} . + + An input pixel is considered bad (and is consequently ignored) if + its + data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is + set via the \texttt{"} flags\texttt{"} parameter. + + In addition, associated output variance estimates (if + calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} + value in the \texttt{"} out\_var\texttt{"} array for similar reasons. + } +} +\sstroutine{ + astRebinSeq$<$X$>$ +}{ + Rebin a region of a sequence of data grids +}{ + \sstdescription{ + This set of + functions is identical to \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} + except that the rebinned input data is added into the supplied + output arrays, rather than simply over-writing the contents of the + output arrays. Thus, by calling this + function + repeatedly, a sequence of input arrays can be rebinned and accumulated + into a single output array, effectively forming a mosaic of the + input data arrays. + + In addition, the weights associated with each output pixel are + returned. The weight of an output pixel indicates the number of input + pixels which have been accumulated in that output pixel. If the entire + value of an input pixel is assigned to a single output pixel, then the + weight of that output pixel is incremented by one. If some fraction of + the value of an input pixel is assigned to an output pixel, then the + weight of that output pixel is incremented by the fraction used. + + The start of a new sequence is indicated by specifying the + AST\_\_REBININIT flag via the + \texttt{"} flags\texttt{"} parameter. + This causes the supplied arrays to be filled with zeros before the + rebinned input data is added into them. Subsequenct invocations + within the same sequence should omit the AST\_\_REBININIT flag. + + The last call in a sequence is indicated by specifying the + AST\_\_REBINEND flag. Depending on which flags are supplied, this may + cause the output data and variance arrays to be normalised before + being returned. This normalisation consists of dividing the data + array by the weights array, and can eliminate artifacts which may be + introduced into the rebinned data as a consequence of aliasing + between the input and output grids. This results in each output + pixel value being the weighted mean of the input pixel values that + fall in the neighbourhood of the output pixel (rather like + \htmlref{astResample$<$X$>$}{astResample$<$X$>$}). + Optionally, these normalised + values can then be multiplied by a scaling factor to ensure that the + total data sum in any small area is unchanged. This scaling factor + is equivalent to the number of input pixel values that fall into each + output pixel. In addition to + normalisation of the output data values, any output variances are + also appropriately normalised, and any output data values with + weight less than + \texttt{"} wlim\texttt{"} are set to \texttt{"} badval\texttt{"} . + + Output variances can be generated in two ways; by rebinning the supplied + input variances with appropriate weights, or by finding the spread of + input data values contributing to each output pixel (see the AST\_\_GENVAR + and AST\_\_USEVAR flags). + } + \sstsynopsis{ + void astRebinSeq$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in, + const int lbnd\_in[], const int ubnd\_in[], + const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], + int spread, const double params[], int flags, + double tol, int maxpix, $<$Xtype$>$ badval, + int ndim\_out, const int lbnd\_out[], + const int ubnd\_out[], const int lbnd[], + const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], + double weights[], int64\_t $*$nused ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to a \htmlref{Mapping}{Mapping}, whose forward transformation will be + used to transform the coordinates of pixels in the input + grid into the coordinate system of the output grid. + + The number of input coordinates used by this Mapping (as + given by its \htmlref{Nin}{Nin} attribute) should match the number of input + grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} + below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} + attribute) should match the number of output grid dimensions + given by \texttt{"} ndim\_out\texttt{"} . + If \texttt{"} in\texttt{"} is NULL, the Mapping will not be used, but a valid + Mapping must still be supplied. + } + \sstsubsection{ + wlim + }{ + This value is only used if the AST\_\_REBINEND flag is specified + via the + \texttt{"} flags\texttt{"} parameter. + It gives the required number of input pixel values which must + contribute to an output pixel (i.e. the output pixel weight) in + order for the output pixel value to be considered valid. If the sum + of the input pixel weights contributing to an output pixel is less + than the supplied + \texttt{"} wlim\texttt{"} + value, then the output pixel value is returned set to the + supplied bad value. If the supplied value is less than 1.0E-10 + then 1.0E-10 is used instead. + } + \sstsubsection{ + ndim\_in + }{ + The number of dimensions in the input grid. This should be at + least one. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + lbnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + ubnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + in + }{ + Pointer to an array, with one element for each pixel in the + input grid, containing the input data to be rebined. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astRebinSeqF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + If a NULL pointer is supplied for \texttt{"} in\texttt{"} , then no data is added to + the output arrays, but any initialisation or normalisation + requested by \texttt{"} flags\texttt{"} is still performed. + } + \sstsubsection{ + in\_var + }{ + An optional + pointer to a + second array with the same size and type as the + \texttt{"} in\texttt{"} + array. If given, this should contain a set of non-negative values + which represent estimates of the statistical variance associated + with each element of the + \texttt{"} in\texttt{"} + array. + If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no + input variance estimates are required and this + pointer + will not be used. + A NULL pointer + may then be supplied. + } + \sstsubsection{ + spread + }{ + This parameter specifies the scheme to be used for dividing + each input data value up amongst the corresponding output pixels. + It may be used to select + from a set of pre-defined schemes by supplying one of the + values described in the \texttt{"} Pixel Spreading Schemes\texttt{"} + section in the description of the + astRebin$<$X$>$ functions. + If a value of zero is supplied, then the default linear spreading + scheme is used (equivalent to supplying the value AST\_\_LINEAR). + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + params + }{ + An optional pointer to an array of double which should contain + any additional parameter values required by the pixel + spreading scheme. If such parameters are required, this + will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"} section in the + description of the + astRebin$<$X$>$ functions. + + If no additional parameters are required, this array is not + used and a NULL pointer may be given. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + flags + }{ + The bitwise OR of a set of flag values which may be used to + provide additional control over the rebinning operation. See + the \texttt{"} Control Flags\texttt{"} section below for a description of the + options available. If no flag values are to be set, a value + of zero should be given. + } + \sstsubsection{ + tol + }{ + The maximum tolerable geometrical distortion which may be + introduced as a result of approximating non-linear Mappings + by a set of piece-wise linear transformations. This should be + expressed as a displacement in pixels in the output grid\texttt{'} s + coordinate system. + + If piece-wise linear approximation is not required, a value + of zero may be given. This will ensure that the Mapping is + used without any approximation, but may increase execution + time. + + If the value is too high, discontinuities between the linear + approximations used in adjacent panel will be higher, and may + cause the edges of the panel to be visible when viewing the output + image at high contrast. If this is a problem, reduce the + tolerance value used. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + maxpix + }{ + A value which specifies an initial scale size (in pixels) for + the adaptive algorithm which approximates non-linear Mappings + with piece-wise linear transformations. Normally, this should + be a large value (larger than any dimension of the region of + the input grid being used). In this case, a first attempt to + approximate the Mapping by a linear transformation will be + made over the entire input region. + + If a smaller value is used, the input region will first be + divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} + pixels in any dimension. Only at this point will attempts at + approximation commence. + + This value may occasionally be useful in preventing false + convergence of the adaptive algorithm in cases where the + Mapping appears approximately linear on large scales, but has + irregularities (e.g. holes) on smaller scales. A value of, + say, 50 to 100 pixels can also be employed as a safeguard in + general-purpose software, since the effect on performance is + minimal. + + If too small a value is given, it will have the effect of + inhibiting linear approximation altogether (equivalent to + setting \texttt{"} tol\texttt{"} to zero). Although this may degrade + performance, accurate results will still be obtained. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + badval + }{ + This argument should have the same type as the elements of + the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing + data (bad pixels) in the input and output arrays. + + If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, + then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} + (and \texttt{"} in\_var\texttt{"} ) array(s). + + In all cases, this value is also used to flag any output + elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which + rebined values could not be obtained (see the \texttt{"} Propagation + of Missing Data\texttt{"} section below for details of the + circumstances under which this may occur). + } + \sstsubsection{ + ndim\_out + }{ + The number of dimensions in the output grid. This should be + at least one. It need not necessarily be equal to the number + of dimensions in the input grid. + } + \sstsubsection{ + lbnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the output grid along each dimension. + } + \sstsubsection{ + ubnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the output grid along each dimension. + + Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the + shape, size and coordinate system of the output grid in the + same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size + and coordinate system of the input grid. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the first pixel in the region + of the input grid which is to be included in the rebined output + array. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the last pixel in the region of + the input grid which is to be included in the rebined output + array. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and + position of a (hyper-)rectangular region of the input grid + which is to be included in the rebined output array. This region + should lie wholly within the extent of the input grid (as + defined by the \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} arrays). Regions of + the input grid lying outside this region will not be used. + Not used if \texttt{"} in\texttt{"} is NULL. + } + \sstsubsection{ + out + }{ + Pointer to an array, with one element for each pixel in the + output grid. The rebined data values will be added into the + original contents of this array. The numerical type of this array + should match that of the + \texttt{"} in\texttt{"} array, and the data storage order should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + out\_var + }{ + A + pointer to an + array with the same type and size as the + \texttt{"} out\texttt{"} + array. This + pointer + will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set + in which case variance estimates for the rebined data values will + be added into the array. If neither the AST\_\_USEVAR flag nor the + AST\_\_GENVAR flag is set, no output variance estimates will be + calculated and this + pointer + will not be used. A + NULL pointer + may then be supplied. + } + \sstsubsection{ + weights + }{ + Pointer to an array of double, + with one or two elements for each pixel in the output grid, + depending on whether or not the AST\_\_GENVAR flag has been supplied + via the + \texttt{"} flags\texttt{"} parameter. + If AST\_\_GENVAR has not been specified then the array should have + one element for each output pixel, and it will be used to + accumulate the weight associated with each output pixel. + If AST\_\_GENVAR has been specified then the array should have + two elements for each output pixel. The first half of the array + is again used to accumulate the weight associated with each output + pixel, and the second half is used to accumulate the square of + the weights. In each half, the data storage order should be such that + the index of the first grid dimension varies most rapidly and that of + the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + nused + }{ + A pointer to an int64\_t containing the + number of input data values that have been added into the output + array so far. The supplied value is incremented on exit by the + number of input values used. The value is initially set to zero + if the AST\_\_REBININIT flag is set in + \texttt{"} flags\texttt{"} . + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate rebinning function, you should + replace $<$X$>$ in the generic function name astRebinSeq$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + I: int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astRebinSeqD would be used to process \texttt{"} double\texttt{"} + data, while astRebinSeqI would be used to process \texttt{"} int\texttt{"} + data, etc. + + Note that, unlike + astResample$<$X$>$, the astRebinSeq$<$X$>$ + set of functions does not yet support unsigned integer data types + or integers of different sizes. + } + \sstdiytopic{ + Control Flags + }{ + The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and + may be used to provide additional control over the rebinning + process. Having selected a set of flags, you should supply the + bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: + + \sstitemlist{ + + \sstitem + AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates + that the supplied + \texttt{"} out\texttt{"} , \texttt{"} out\_var\texttt{"} and \texttt{"} weights\texttt{"} + arrays should be filled with zeros (thus over-writing any supplied + values) before adding the rebinned input data into them. This flag + should be used when rebinning the first input array in a sequence. + + \sstitem + AST\_\_REBINEND: Used to mark the last call in a sequence. It causes + each value in the + \texttt{"} out\texttt{"} and \texttt{"} out\_var\texttt{"} + arrays to be divided by a normalisation factor before being + returned. The normalisation factor for each output data value is just + the corresponding value from the weights array. The normalisation + factor for each output variance value is the square of the data value + normalisation factor (see also AST\_\_CONSERVEFLUX). It also causes + output data values to be set bad if the corresponding weight is less + than the value supplied for + parameter \texttt{"} wlim\texttt{"} . + It also causes any temporary values stored in the output variance array + (see flag AST\_\_GENVAR below) to be converted into usable variance values. + Note, this flag is ignored if the AST\_\_NONORM flag is set. + + \sstitem + AST\_\_USEBAD: Indicates that there may be bad pixels in the + input array(s) which must be recognised by comparing with the + value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). + If this flag is not set, all input values are treated literally + and the \texttt{"} badval\texttt{"} value is only used for flagging output array + values. + + \sstitem + AST\_\_USEVAR: Indicates that output variance estimates should be + created by rebinning the supplied input variance estimates. An + error will be reported if both this flag and the AST\_\_GENVAR flag + are supplied. + + \sstitem + AST\_\_GENVAR: Indicates that output variance estimates should be + created based on the spread of input data values contributing to each + output pixel. An error will be reported if both this flag and the + AST\_\_USEVAR flag are supplied. If the AST\_\_GENVAR flag is specified, + the supplied output variance array is first used as a work array to + accumulate the temporary values needed to generate the output + variances. When the sequence ends (as indicated by the + AST\_\_REBINEND flag), the contents of the output variance array are + converted into the required variance estimates. If the generation of + such output variances is required, this flag should be used on every + invocation of this + function + within a sequence, and any supplied input variances will have no effect + on the output variances (although input variances will still be used + to weight the input data if the AST\_\_VARWGT flag is also supplied). + The statistical meaning of these output varianes is determined by + the presence or absence of the AST\_\_DISVAR flag (see below). + + \sstitem + AST\_\_DISVAR: This flag is ignored unless the AST\_\_GENVAR flag + has also been specified. It determines the statistical meaning of + the generated output variances. If AST\_\_DISVAR is not specified, + generated variances represent variances on the output mean values. If + AST\_\_DISVAR is specified, the generated variances represent the variance + of the distribution from which the input values were taken. Each output + variance created with AST\_\_DISVAR will be larger than that created + without AST\_\_DISVAR by a factor equal to the number of input samples + that contribute to the output sample. + + \sstitem + AST\_\_VARWGT: Indicates that the input data should be weighted by + the reciprocal of the input variances. Otherwise, all input data are + given equal weight. If this flag is specified, the calculation of the + output variances (if any) is modified to take account of the + varying weights assigned to the input data values. + + \sstitem + AST\_\_NONORM: If the simple unnormalised sum of all input data falling + in each output pixel is required, then this flag should be set on + each call in the sequence and the AST\_\_REBINEND should not be used + on the last call. In this case + NULL pointers can be supplied for \texttt{"} weights\texttt{"} and \texttt{"} nused\texttt{"} . + This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR + or AST\_\_VARWGT flag. + + \sstitem + AST\_\_CONSERVEFLUX: Indicates that the normalized output pixel values + generated by the AST\_\_REBINEND flag should be scaled in such a way as + to preserve the total data value in a feature on the sky. Without this + flag, each normalised output pixel value represents a weighted mean + of the input data values around the corresponding input position. + is appropriate if the input data represents the spatial density of + some quantity (e.g. surface brightness in Janskys per square + arc-second) because the output pixel values will have the same + normalisation and units as the input pixel values. However, if the + input data values represent flux (or some other physical quantity) + per pixel, then the AST\_\_CONSERVEFLUX flag could be of use. It causes + each output pixel value to be scaled by the ratio of the output pixel + size to the input pixel size. + + } + This flag can only be used if the Mapping is successfully approximated + by one or more linear transformations. Thus an error will be reported + if it used when the + \texttt{"} tol\texttt{"} parameter + is set to zero (which stops the use of linear approximations), or + if the Mapping is too non-linear to be approximated by a piece-wise + linear transformation. The ratio of output to input pixel size is + evaluated once for each panel of the piece-wise linear approximation to + the Mapping, and is assumed to be constant for all output pixels in the + panel. The scaling factors for adjacent panels will in general + differ slightly, and so the joints between panels may be visible when + viewing the output image at high contrast. If this is a problem, + reduce the value of the + \texttt{"} tol\texttt{"} parameter + until the difference between adjacent panels is sufficiently small + to be insignificant. + + This flag should normally be supplied on each invocation of + astRebinSeq$<$X$>$ + within a given sequence. + + Note, this flag cannot be used in conjunction with the AST\_\_NOSCALE + flag (an error will be reported if both flags are specified). + } + \sstdiytopic{ + Propagation of Missing Data + }{ + Instances of missing data (bad pixels) in the output grid are + identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} + array. These are only produced if the AST\_\_REBINEND flag is + specified and a pixel has zero weight. + + An input pixel is considered bad (and is consequently ignored) if + its + data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is + set via the \texttt{"} flags\texttt{"} parameter. + + In addition, associated output variance estimates (if + calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} + value in the \texttt{"} out\_var\texttt{"} array for similar reasons. + } +} +\sstroutine{ + astRegionOutline +}{ + Draw the outline of an AST Region +}{ + \sstdescription{ + This function draws an outline around the supplied AST \htmlref{Region}{Region} object. + } + \sstsynopsis{ + void astRegionOutline( AstPlot $*$this, AstRegion $*$region ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Plot}{Plot}. + } + \sstsubsection{ + region + }{ + Pointer to the Region. + } + } +} +\sstroutine{ + astRemapFrame +}{ + Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet +}{ + \sstdescription{ + This function modifies the relationship (i.e. \htmlref{Mapping}{Mapping}) between a + specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet} and the other Frames in that + FrameSet. + + Typically, this might be required if the FrameSet has been used + to calibrate (say) an image, and that image is re-binned. The + Frame describing the image will then have undergone a coordinate + transformation, and this should be communicated to the associated + FrameSet using this function. + } + \sstsynopsis{ + void astRemapFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe + }{ + The index within the FrameSet of the Frame to be modified. + This value should lie in the range from 1 to the number of + Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). + } + \sstsubsection{ + map + }{ + Pointer to a Mapping whose forward transformation converts + coordinate values from the original coordinate system + described by the Frame to the new one, and whose inverse + transformation converts in the opposite direction. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of AST\_\_BASE or AST\_\_CURRENT may be given for the + \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current + Frame respectively. + + \sstitem + The relationship between the selected Frame and any other + Frame within the FrameSet will be modified by this function, + but the relationship between all other Frames in the FrameSet + remains unchanged. + + \sstitem + The number of input coordinate values accepted by the Mapping + (its \htmlref{Nin}{Nin} attribute) and the number of output coordinate values + generated (its \htmlref{Nout}{Nout} attribute) must be equal and must match the + number of axes in the Frame being modified. + + \sstitem + If a simple change of axis order is required, then the + \htmlref{astPermAxes}{astPermAxes} function may provide a more straightforward method + of making the required changes to the FrameSet. + + \sstitem + This function cannot be used to change the number of Frame + axes. To achieve this, a new Frame must be added to the FrameSet + (\htmlref{astAddFrame}{astAddFrame}) and the original one removed if necessary + (\htmlref{astRemoveFrame}{astRemoveFrame}). + + \sstitem + Any variant Mappings associated with the remapped Frame (except + for the current variant) will be lost as a consequence of calling this + method (see attribute \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). + } + } +} +\sstroutine{ + astRemoveColumn +}{ + Remove a column from a table +}{ + \sstdescription{ + This function removes a specified column from the supplied table. + The + function + returns without action if the named column does not exist in the + \htmlref{Table}{Table} (no error is reported). + } + \sstsynopsis{ + void astRemoveColumn( AstTable $*$this, const char $*$name ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + name + }{ + The column name. Trailing spaces are ignored (all other spaces + are significant). Case is significant. + } + } +} +\sstroutine{ + astRemoveFrame +}{ + Remove a Frame from a FrameSet +}{ + \sstdescription{ + This function removes a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet}. All other Frames + in the FrameSet have their indices re-numbered from one (if + necessary), but are otherwise unchanged. + } + \sstsynopsis{ + void astRemoveFrame( AstFrameSet $*$this, int iframe ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FrameSet. + } + \sstsubsection{ + iframe + }{ + The index within the FrameSet of the Frame to be removed. + This value should lie in the range from 1 to the number of + Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Removing a Frame from a FrameSet does not affect the + relationship between other Frames in the FrameSet, even if they + originally depended on the Frame being removed. + + \sstitem + The number of Frames in a FrameSet cannot be reduced to zero. + An error will result if an attempt is made to remove the only + remaining Frame. + + \sstitem + A value of AST\_\_BASE or AST\_\_CURRENT may be given for the + \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current + Frame respectively. + + \sstitem + If a FrameSet\texttt{'} s base or current Frame is removed, the \htmlref{Base}{Base} or + \htmlref{Current}{Current} attribute (respectively) of the FrameSet will have its + value cleared, so that another Frame will then assume its role + by default. + + \sstitem + If any other Frame is removed, the base and current Frames + will remain the same. To ensure this, the Base and/or Current + attributes of the FrameSet will be changed, if necessary, to + reflect any change in the indices of these Frames. + } + } +} +\sstroutine{ + astRemoveParameter +}{ + Remove a global parameter from a table +}{ + \sstdescription{ + This function removes a specified global parameter from the supplied table. + The + function + returns without action if the named parameter does not exist in the + \htmlref{Table}{Table} (no error is reported). + } + \sstsynopsis{ + void astRemoveParameter( AstTable $*$this, const char $*$name ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + name + }{ + The parameter name. Trailing spaces are ignored (all other spaces + are significant). Case is significant. + } + } +} +\sstroutine{ + astRemoveRegions +}{ + Remove any Regions from a Mapping +}{ + \sstdescription{ + This function searches the suppliedMapping (which may be a + compound \htmlref{Mapping}{Mapping} such as a \htmlref{CmpMap}{CmpMap}) for any component Mappings + that are instances of the AST \htmlref{Region}{Region} class. It then creates a new + Mapping from which all Regions have been removed. If a Region + cannot simply be removed (for instance, if it is a component of a + parallel CmpMap), then it is replaced with an equivalent \htmlref{UnitMap}{UnitMap} + in the returned Mapping. + } + \sstsynopsis{ + AstMapping $*$astRemoveRegions( AstMapping $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the original Mapping. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + If the supplied Mapping is a CmpFrame, any component Frames that + are instances of the Region class are replaced by the equivalent + \htmlref{Frame}{Frame}. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + If the supplied Mapping is a FrameSet, the returned Mapping + will be a copy of the supplied FrameSet in which Regions have + been removed from all the inter-Frame Mappings, and any Frames + which are instances of the Region class are repalced by the + equivalent Frame. + } + \sstsubsection{ + Mapping + }{ + This function applies to all Mappings. + } + \sstsubsection{ + Region + }{ + If the supplied Mapping is a Region, the returned Mapping will + be the equivalent Frame. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astRemoveRegions() + }{ + A new pointer to the (possibly modified) Mapping. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function can safely be applied even to Mappings which + contain no Regions. If no Regions are found, it + behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the + original Mapping. + + \sstitem + The Mapping returned by this function may not be independent + of the original (even if some Regions were removed), and + modifying it may therefore result in indirect modification of + the original. If a completely independent result is required, a + copy should be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astRemoveRow +}{ + Remove a row from a table +}{ + \sstdescription{ + This function removes a specified row from the supplied table. + The + function + returns without action if the row does not exist in the + \htmlref{Table}{Table} (no error is reported). + } + \sstsynopsis{ + void astRemoveRow( AstTable $*$this, int index ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Table. + } + \sstsubsection{ + index + }{ + The index of the row to be removed. The first row has index 1. + } + } +} +\sstroutine{ + astRemoveTables +}{ + Remove one or more tables from a FitsChan +}{ + \sstdescription{ + This function + removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error + is reported if any the tables do not exist). + } + \sstsynopsis{ + void astRemoveTables( AstFitsChan $*$this, const char $*$key ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + key + }{ + The key indicating which tables to exist. A single key or a + comma-separated list of keys can be supplied. If a blank string + is supplied, all tables are removed. + } + } +} +\sstroutine{ + astResample$<$X$>$ +}{ + Resample a region of a data grid +}{ + \sstdescription{ + This is a set of functions for resampling gridded data (e.g. an + image) under the control of a geometrical transformation, which + is specified by a \htmlref{Mapping}{Mapping}. The functions operate on a pair of + data grids (input and output), each of which may have any number + of dimensions. Resampling may be restricted to a specified + region of the output grid. An associated grid of error estimates + associated with the input data may also be supplied (in the form + of variance values), so as to produce error estimates for the + resampled output data. Propagation of missing data (bad pixels) + is supported. + + You should use a resampling function which matches the numerical + type of the data you are processing by replacing $<$X$>$ in + the generic function name astResample$<$X$>$ by an appropriate 1- or + 2-character type code. For example, if you are resampling data + with type \texttt{"} float\texttt{"} , you should use the function astResampleF (see + the \texttt{"} Data Type Codes\texttt{"} section below for the codes appropriate to + other numerical types). + + Resampling of the grid of input data is performed by + transforming the coordinates of the centre of each output grid + element (or pixel) into the coordinate system of the input grid. + Since the resulting coordinates will not, in general, coincide + with the centre of an input pixel, sub-pixel interpolation is + performed between the neighbouring input pixels. This produces a + resampled value which is then assigned to the output pixel. A + choice of sub-pixel interpolation schemes is provided, but you + may also implement your own. + + This algorithm samples the input data value, it does not integrate + it. Thus total data value in the input image will not, in general, + be conserved. However, an option is provided (see the \texttt{"} Control Flags\texttt{"} + section below) which can produce approximate flux conservation by + scaling the output values using the ratio of the output pixel size + to the input pixel size. However, if accurate flux conservation is + important to you, consder using the + \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} or \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} family of functions + instead. + + Output pixel coordinates are transformed into the coordinate + system of the input grid using the inverse transformation of the + Mapping which is supplied. This means that geometrical features + in the input data are subjected to the Mapping\texttt{'} s forward + transformation as they are transferred from the input to the + output grid (although the Mapping\texttt{'} s forward transformation is + not explicitly used). + + In practice, transforming the coordinates of every pixel of a + large data grid can be time-consuming, especially if the Mapping + involves complicated functions, such as sky projections. To + improve performance, it is therefore possible to approximate + non-linear Mappings by a set of linear transformations which are + applied piece-wise to separate sub-regions of the data. This + approximation process is applied automatically by an adaptive + algorithm, under control of an accuracy criterion which + expresses the maximum tolerable geometrical distortion which may + be introduced, as a fraction of a pixel. + + This algorithm first attempts to approximate the Mapping with a + linear transformation applied over the whole region of the + output grid which is being used. If this proves to be + insufficiently accurate, the output region is sub-divided into + two along its largest dimension and the process is repeated + within each of the resulting sub-regions. This process of + sub-division continues until a sufficiently good linear + approximation is found, or the region to which it is being + applied becomes too small (in which case the original Mapping is + used directly). + } + \sstsynopsis{ + int astResample$<$X$>$( AstMapping $*$this, int ndim\_in, + const int lbnd\_in[], const int ubnd\_in[], + const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], + int interp, void ($*$ finterp)( void ), + const double params[], int flags, + double tol, int maxpix, + $<$Xtype$>$ badval, int ndim\_out, + const int lbnd\_out[], const int ubnd\_out[], + const int lbnd[], const int ubnd[], + $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to a Mapping, whose inverse transformation will be + used to transform the coordinates of pixels in the output + grid into the coordinate system of the input grid. This + yields the positions which are used to obtain resampled + values by sub-pixel interpolation within the input grid. + + The number of input coordinates used by this Mapping (as + given by its \htmlref{Nin}{Nin} attribute) should match the number of input + grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"} + below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout} + attribute) should match the number of output grid dimensions + given by \texttt{"} ndim\_out\texttt{"} . + } + \sstsubsection{ + ndim\_in + }{ + The number of dimensions in the input grid. This should be at + least one. + } + \sstsubsection{ + lbnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre. + } + \sstsubsection{ + in + }{ + Pointer to an array, with one element for each pixel in the + input grid, containing the input data to be resampled. The + numerical type of this array should match the 1- or + 2-character type code appended to the function name (e.g. if + you are using astResampleF, the type of each array element + should be \texttt{"} float\texttt{"} ). + + The storage order of data within this array should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + in\_var + }{ + An optional pointer to a second array with the same size and + type as the \texttt{"} in\texttt{"} array. If given, this should contain a set + of non-negative values which represent estimates of the + statistical variance associated with each element of the \texttt{"} in\texttt{"} + array. If this array is supplied (together with the + corresponding \texttt{"} out\_var\texttt{"} array), then estimates of the + variance of the resampled output data will be calculated. + + If no input variance estimates are being provided, a NULL + pointer should be given. + } + \sstsubsection{ + interp + }{ + This parameter specifies the scheme to be used for sub-pixel + interpolation within the input grid. It may be used to select + from a set of pre-defined schemes by supplying one of the + values described in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} + section below. If a value of zero is supplied, then the + default linear interpolation scheme is used (equivalent to + supplying the value AST\_\_LINEAR). + + Alternatively, you may supply a value which indicates that + you will provide your own function to perform sub-pixel + interpolation by means of the \texttt{"} finterp \texttt{"} parameter. Again, see + the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section below for + details. + } + \sstsubsection{ + finterp + }{ + If the value given for the \texttt{"} interp\texttt{"} parameter indicates that + you will provide your own function for sub-pixel + interpolation, then a pointer to that function should be + given here. For details of the interface which the function + should have (several are possible, depending on the value of + \texttt{"} interp\texttt{"} ), see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} section + below. + + If the \texttt{"} interp\texttt{"} parameter has any other value, corresponding + to one of the pre-defined interpolation schemes, then this + function will not be used and you may supply a NULL pointer. + } + \sstsubsection{ + params + }{ + An optional pointer to an array of double which should contain + any additional parameter values required by the sub-pixel + interpolation scheme. If such parameters are required, this + will be noted in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"} + section below (you may also use this array to pass values + to your own interpolation function). + + If no additional parameters are required, this array is not + used and a NULL pointer may be given. + } + \sstsubsection{ + flags + }{ + The bitwise OR of a set of flag values which may be used to + provide additional control over the resampling operation. See + the \texttt{"} Control Flags\texttt{"} section below for a description of the + options available. If no flag values are to be set, a value + of zero should be given. + } + \sstsubsection{ + tol + }{ + The maximum tolerable geometrical distortion which may be + introduced as a result of approximating non-linear Mappings + by a set of piece-wise linear transformations. This should be + expressed as a displacement in pixels in the input grid\texttt{'} s + coordinate system. + + If piece-wise linear approximation is not required, a value + of zero may be given. This will ensure that the Mapping is + used without any approximation, but may increase execution + time. + } + \sstsubsection{ + maxpix + }{ + A value which specifies an initial scale size (in pixels) for + the adaptive algorithm which approximates non-linear Mappings + with piece-wise linear transformations. Normally, this should + be a large value (larger than any dimension of the region of + the output grid being used). In this case, a first attempt to + approximate the Mapping by a linear transformation will be + made over the entire output region. + + If a smaller value is used, the output region will first be + divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} + pixels in any dimension. Only at this point will attempts at + approximation commence. + + This value may occasionally be useful in preventing false + convergence of the adaptive algorithm in cases where the + Mapping appears approximately linear on large scales, but has + irregularities (e.g. holes) on smaller scales. A value of, + say, 50 to 100 pixels can also be employed as a safeguard in + general-purpose software, since the effect on performance is + minimal. + + If too small a value is given, it will have the effect of + inhibiting linear approximation altogether (equivalent to + setting \texttt{"} tol\texttt{"} to zero). Although this may degrade + performance, accurate results will still be obtained. + } + \sstsubsection{ + badval + }{ + This argument should have the same type as the elements of + the \texttt{"} in\texttt{"} array. It specifies the value used to flag missing + data (bad pixels) in the input and output arrays. + + If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"} parameter, + then this value is used to test for bad pixels in the \texttt{"} in\texttt{"} + (and \texttt{"} in\_var\texttt{"} ) array(s). + + Unless the AST\_\_NOBAD flag is set via the \texttt{"} flags\texttt{"} parameter, + this value is also used to flag any output + elements in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) for which + resampled values could not be obtained (see the \texttt{"} Propagation + of Missing Data\texttt{"} section below for details of the + circumstances under which this may occur). The astResample$<$X$>$ + function return value indicates whether any such values have + been produced. If the AST\_\_NOBAD flag is set. then output array + elements for which no resampled value could be obtained are + left set to the value they had on entry to this function. + } + \sstsubsection{ + ndim\_out + }{ + The number of dimensions in the output grid. This should be + at least one. It need not necessarily be equal to the number + of dimensions in the input grid. + } + \sstsubsection{ + lbnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the output grid along each dimension. + } + \sstsubsection{ + ubnd\_out + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the output grid along each dimension. + + Note that \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} together define the + shape, size and coordinate system of the output grid in the + same way as \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} define the shape, size + and coordinate system of the input grid. + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the first pixel in the region + of the output grid for which a resampled value is to be + calculated. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"} elements, + containing the coordinates of the last pixel in the region of + the output grid for which a resampled value is to be + calculated. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape and + position of a (hyper-)rectangular region of the output grid + for which resampled values should be produced. This region + should lie wholly within the extent of the output grid (as + defined by the \texttt{"} lbnd\_out\texttt{"} and \texttt{"} ubnd\_out\texttt{"} arrays). Regions of + the output grid lying outside this region will not be + modified. + } + \sstsubsection{ + out + }{ + Pointer to an array, with one element for each pixel in the + output grid, into which the resampled data values will be + returned. The numerical type of this array should match that + of the \texttt{"} in\texttt{"} array, and the data storage order should be such + that the index of the first grid dimension varies most + rapidly and that of the final dimension least rapidly + (i.e. Fortran array indexing is used). + } + \sstsubsection{ + out\_var + }{ + An optional pointer to an array with the same type and size + as the \texttt{"} out\texttt{"} array. If given, this array will be used to + return variance estimates for the resampled data values. This + array will only be used if the \texttt{"} in\_var\texttt{"} array has also been + supplied. + + The output variance values will be calculated on the + assumption that errors on the input data values are + statistically independent and that their variance estimates + may simply be summed (with appropriate weighting factors) + when several input pixels contribute to an output data + value. If this assumption is not valid, then the output error + estimates may be biased. In addition, note that the + statistical errors on neighbouring output data values (as + well as the estimates of those errors) may often be + correlated, even if the above assumption about the input data + is correct, because of the sub-pixel interpolation schemes + employed. + + If no output variance estimates are required, a NULL pointer + should be given. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astResample$<$X$>$() + }{ + The number of output pixels for which no valid resampled value + could be obtained. Thus, in the absence of any error, a returned + value of zero indicates that all the required output pixels + received valid resampled data values (and variances). See the + \texttt{"} badval\texttt{"} and \texttt{"} flags\texttt{"} parameters. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero will be returned if this function is invoked + with the global error status set, or if it should fail for any + reason. + } + } + \sstdiytopic{ + Data Type Codes + }{ + To select the appropriate resampling function, you should + replace $<$X$>$ in the generic function name astResample$<$X$>$ with a + 1- or 2-character data type code, so as to match the numerical + type $<$Xtype$>$ of the data you are processing, as follows: + \sstitemlist{ + + \sstitem + D: double + + \sstitem + F: float + + \sstitem + L: long int (may be 32 or 64 bit) + + \sstitem + K: 64 bit int + + \sstitem + UL: unsigned long int (may be 32 or 64 bit) + + \sstitem + UK: unsigned 64 bit int + + \sstitem + I: int + + \sstitem + UI: unsigned int + + \sstitem + S: short int + + \sstitem + US: unsigned short int + + \sstitem + B: byte (signed char) + + \sstitem + UB: unsigned byte (unsigned char) + + } + For example, astResampleD would be used to process \texttt{"} double\texttt{"} + data, while astResampleS would be used to process \texttt{"} short int\texttt{"} + data, etc. + } + \sstdiytopic{ + Sub-Pixel Interpolation Schemes + }{ + There is no such thing as a perfect sub-pixel interpolation + scheme and, in practice, all resampling will result in some + degradation of gridded data. A range of schemes is therefore + provided, from which you can choose the one which best suits + your needs. + + In general, a balance must be struck between schemes which tend + to degrade sharp features in the data by smoothing them, and + those which attempt to preserve sharp features. The latter will + often tend to introduce unwanted oscillations, typically visible + as \texttt{"} ringing\texttt{"} around sharp features and edges, especially if the + data are under-sampled (i.e. if the sharpest features are less + than about two pixels across). In practice, a good interpolation + scheme is likely to be a compromise and may exhibit some aspects + of both these features. + + For under-sampled data, some interpolation schemes may appear to + preserve data resolution because they transform single input + pixels into single output pixels, rather than spreading their + data between several output pixels. While this may look + better cosmetically, it can result in a geometrical shift of + sharp features in the data. You should beware of this if you + plan to use such features (e.g.) for image alignment. + + The following are two easy-to-use sub-pixel interpolation + schemes which are generally applicable. They are selected by + supplying the appropriate value (defined in the \texttt{"} ast.h\texttt{"} header + file) via the \texttt{"} interp\texttt{"} parameter. In these cases, the \texttt{"} finterp\texttt{"} + and \texttt{"} params\texttt{"} parameters are not used: + + \sstitemlist{ + + \sstitem + AST\_\_NEAREST: This is the simplest possible scheme, in which + the value of the input pixel with the nearest centre to the + interpolation point is used. This is very quick to execute and + will preserve single-pixel features in the data, but may + displace them by up to half their width along each dimension. It + often gives a good cosmetic result, so is useful for quick-look + processing, but is unsuitable if accurate geometrical + transformation is required. + + \sstitem + AST\_\_LINEAR: This is the default scheme, which uses linear + interpolation between the nearest neighbouring pixels in the + input grid (there are two neighbours in one dimension, four + neighbours in two dimensions, eight in three dimensions, + etc.). It is superior to the nearest-pixel scheme (above) in not + displacing features in the data, yet it still executes fairly + rapidly. It is generally a safe choice if you do not have any + particular reason to favour another scheme, since it cannot + introduce oscillations. However, it does introduce some spatial + smoothing which varies according to the distance of the + interpolation point from the neighbouring pixels. This can + degrade the shape of sharp features in the data in a + position-dependent way. It may also show in the output variance + grid (if used) as a pattern of stripes or fringes. + + } + An alternative set of interpolation schemes is based on forming + the interpolated value from the weighted sum of a set of + surrounding pixel values (not necessarily just the nearest + neighbours). This approach has its origins in the theory of + digital filtering, in which interpolated values are obtained by + conceptually passing the sampled data (represented by a grid of + delta functions) through a linear filter which implements a + convolution. Because the convolution kernel is continuous, the + convolution yields a continuous function which may then be + evaluated at fractional pixel positions. The (possibly + multi-dimensional) kernel is usually regarded as \texttt{"} separable\texttt{"} and + formed from the product of a set of identical 1-dimensional + kernel functions, evaluated along each dimension. Different + interpolation schemes are then distinguished by the choice of + this 1-dimensional interpolation kernel. The number of + surrounding pixels which contribute to the result may also be + varied. + + From a practical standpoint, it is useful to divide the weighted + sum of pixel values by the sum of the weights when determining + the interpolated value. Strictly, this means that a true + convolution is no longer being performed. However, the + distinction is rarely important in practice because (for + slightly subtle reasons) the sum of weights is always + approximately constant for good interpolation kernels. The + advantage of this technique, which is used here, is that it can + easily accommodate missing data and tends to minimise unwanted + oscillations at the edges of the data grid. + + In the following schemes, which are based on a 1-dimensional + interpolation kernel, the first element of the \texttt{"} params\texttt{"} array + should be used to specify how many pixels are to contribute to the + interpolated result on either side of the interpolation point in + each dimension (the nearest integer value is used). Execution time + increases rapidly with this number. Typically, a value of 2 is + appropriate and the minimum value used will be 1 (i.e. two pixels + altogether, one on either side of the interpolation point). + A value of zero or less may be given for \texttt{"} params[0]\texttt{"} + to indicate that a suitable number of pixels should be calculated + automatically. + + In each of these cases, the \texttt{"} finterp\texttt{"} parameter is not used: + + \sstitemlist{ + + \sstitem + AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with + k a positive constant. The full-width at half-maximum (FWHM) is + given by + \texttt{"} params[1]\texttt{"} + to zero will select the number of contributing pixels so as to utilise + the width of the kernel out to where the envelope declines to 1\% of its + maximum value). This kernel suppresses noise at the expense of + smoothing the output array. + + \sstitem + AST\_\_SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the + pixel offset from the interpolation point and sinc(z)=sin(z)/z. This + sometimes features as an \texttt{"} optimal\texttt{"} interpolation kernel in books on + image processing. Its supposed optimality depends on the assumption + that the data are band-limited (i.e. have no spatial frequencies above + a certain value) and are adequately sampled. In practice, astronomical + data rarely meet these requirements. In addition, high spatial + frequencies are often present due (e.g.) to image defects and cosmic + ray events. Consequently, substantial ringing can be experienced with + this kernel. The kernel also decays slowly with distance, so that + many surrounding pixels are required, leading to poor performance. + Abruptly truncating it, by using only a few neighbouring pixels, + improves performance and may reduce ringing (if \texttt{"} params[0]\texttt{"} is set to + zero, then only two pixels will be used on either side). However, a + more gradual truncation, as implemented by other kernels, is generally + to be preferred. This kernel is provided mainly so that you can + convince yourself not to use it! + + \sstitem + AST\_\_SINCSINC: This scheme uses an improved kernel, of the form + sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where + sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor + provides an \texttt{"} envelope\texttt{"} which gradually rolls off the normal sinc(pi$*$x) + kernel at large offsets. The width of this envelope is specified by + giving the number of pixels offset at which it goes to zero by means + of the \texttt{"} params[1]\texttt{"} value, which should be at least 1.0 (in addition, + setting \texttt{"} params[0]\texttt{"} to zero will select the number of contributing + pixels so as to utilise the full width of the kernel, out to where it + reaches zero). The case given by \texttt{"} params[0]=2, params[1]=2\texttt{"} is typically + a good choice and is sometimes known as the Lanczos kernel. This is a + valuable general-purpose interpolation scheme, intermediate in its + visual effect on images between the AST\_\_NEAREST and AST\_\_LINEAR + schemes. Although the kernel is slightly oscillatory, ringing is + adequately suppressed if the data are well sampled. + + \sstitem + AST\_\_SINCCOS: This scheme uses a kernel of the form + sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where + cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor + provides an envelope which gradually rolls off the sinc() kernel + at large offsets. The width of this envelope is specified by giving + the number of pixels offset at which it goes to zero by means + of the \texttt{"} params[1]\texttt{"} value, which should be at least 1.0 (in addition, + setting \texttt{"} params[0]\texttt{"} to zero will select the number of contributing + pixels so as to utilise the full width of the kernel, out to where it + reaches zero). This scheme gives similar results to the + AST\_\_SINCSINC scheme, which it resembles. + + \sstitem + AST\_\_SINCGAUSS: This scheme uses a kernel of the form + sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc() + kernel is rolled off using a Gaussian envelope which is specified by + giving its full-width at half-maximum (FWHM) by means of the \texttt{"} params[1]\texttt{"} + value, which should be at least 0.1 (in addition, setting \texttt{"} params[0]\texttt{"} + to zero will select the number of contributing pixels so as to utilise + the width of the kernel out to where the envelope declines to 1\% of its + maximum value). On astronomical images and spectra, good results are + often obtained by approximately matching the FWHM of the + envelope function, given by \texttt{"} params[1]\texttt{"} , to the point spread function + of the input data. However, there does not seem to be any theoretical + reason for this. + + \sstitem + AST\_\_SOMB: This scheme uses a somb(pi$*$x) kernel (a \texttt{"} sombrero\texttt{"} + function), where x is the pixel offset from the interpolation point + and somb(z)=2$*$J1(z)/z (J1 is a Bessel function of the first kind of + order 1). It is similar to the AST\_\_SINC kernel, and has the same + parameter usage. + + \sstitem + AST\_\_SOMBCOS: This scheme uses a kernel of the form + somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where + cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the + AST\_\_SINCCOS kernel, and has the same parameter usage. + + } + In addition, the following schemes are provided which are not based + on a 1-dimensional kernel: + + \sstitemlist{ + + \sstitem + AST\_\_BLOCKAVE: This scheme simply takes an average of all the + pixels on the input grid in a cube centred on the interpolation + point. The number of pixels in the cube is determined by the + value of the first element of the \texttt{"} params\texttt{"} array, which gives + the number of pixels in each dimension on either side of the + central point. Hence a block of (2 $*$ params[0])$\wedge$ndim\_in + pixels in the input grid will be examined to determine the + value of the output pixel. If the variance is not being used + (var\_in or var\_out = NULL) then all valid pixels in this cube + will be averaged in to the result with equal weight. + If variances are being used, then each input pixel will be + weighted proportionally to the reciprocal of its variance; any + pixel without a valid variance will be discarded. This scheme + is suitable where the output grid is much coarser than the + input grid; if the ratio of pixel sizes is R then a suitable + value of params[0] may be R/2. + + } + Finally, supplying the following values for \texttt{"} interp\texttt{"} allows you + to implement your own sub-pixel interpolation scheme by means of + your own function. You should supply a pointer to this function + via the \texttt{"} finterp\texttt{"} parameter: + + \sstitemlist{ + + \sstitem + AST\_\_UKERN1: In this scheme, you supply a function to evaluate + your own 1-dimensional interpolation kernel, which is then used + to perform sub-pixel interpolation (as described above). The + function you supply should have the same interface as the + fictitious \htmlref{astUkern1}{astUkern1} function (q.v.). In addition, a value + should be given via \texttt{"} params[0]\texttt{"} to specify the number of + neighbouring pixels which are to contribute to each interpolated + value (in the same way as for the pre-defined interpolation + schemes described above). Other elements of the \texttt{"} params\texttt{"} array + are available to pass values to your interpolation function. + + \sstitem + AST\_\_UINTERP: This is a completely general scheme, in which + your interpolation function has access to all of the input + data. This allows you to implement any interpolation algorithm + you choose, which could (for example) be non-linear, or + adaptive. In this case, the astResample$<$X$>$ functions play no + role in the sub-pixel interpolation process and simply handle + the geometrical transformation of coordinates and other + housekeeping. The function you supply should have the same + interface as the fictitious \htmlref{astUinterp}{astUinterp} function (q.v.). In this + case, the \texttt{"} params\texttt{"} parameter is not used by astResample$<$X$>$, but + is available to pass values to your interpolation function. + } + } + \sstdiytopic{ + Control Flags + }{ + The following flags are defined in the \texttt{"} ast.h\texttt{"} header file and + may be used to provide additional control over the resampling + process. Having selected a set of flags, you should supply the + bitwise OR of their values via the \texttt{"} flags\texttt{"} parameter: + + \sstitemlist{ + + \sstitem + AST\_\_NOBAD: Indicates that any output array elements for which no + resampled value could be obtained should be left set to the value + they had on entry to this function. If this flag is not supplied, + such output array elements are set to the value supplied for + parameter \texttt{"} badval\texttt{"} . Note, this flag cannot be used in conjunction + with the AST\_\_CONSERVEFLUX flag (an error will be reported if both + flags are specified). + + \sstitem + AST\_\_URESAMP1, 2, 3 \& 4: A set of four flags which are + reserved for your own use. They may be used to pass private + information to any sub-pixel interpolation function which you + implement yourself. They are ignored by all the pre-defined + interpolation schemes. + + \sstitem + AST\_\_USEBAD: Indicates that there may be bad pixels in the + input array(s) which must be recognised by comparing with the + value given for \texttt{"} badval\texttt{"} and propagated to the output array(s). + If this flag is not set, all input values are treated literally + and the \texttt{"} badval\texttt{"} value is only used for flagging output array + values. + + \sstitem + AST\_\_CONSERVEFLUX: Indicates that the output pixel values should + be scaled in such a way as to preserve (approximately) the total data + value in a feature on the sky. Without this flag, each output pixel + value represents an instantaneous sample of the input data values at + the corresponding input position. This is appropriate if the input + data represents the spatial density of some quantity (e.g. surface + brightness in Janskys per square arc-second) because the output + pixel values will have the same normalisation and units as the + input pixel values. However, if the input data values represent + flux (or some other physical quantity) per pixel, then the + AST\_\_CONSERVEFLUX flag could be used. This causes each output + pixel value to be scaled by the ratio of the output pixel size to + the input pixel size. + + } + This flag can only be used if the Mapping is successfully approximated + by one or more linear transformations. Thus an error will be reported + if it used when the + \texttt{"} tol\texttt{"} parameter + is set to zero (which stops the use of linear approximations), or + if the Mapping is too non-linear to be approximated by a piece-wise + linear transformation. The ratio of output to input pixel size is + evaluated once for each panel of the piece-wise linear approximation to + the Mapping, and is assumed to be constant for all output pixels in the + panel. The scaling factors for adjacent panels will in general + differ slightly, and so the joints between panels may be visible when + viewing the output image at high contrast. If this is a problem, + reduce the value of the + \texttt{"} tol\texttt{"} parameter + until the difference between adjacent panels is sufficiently small + to be insignificant. + + Note, this flag cannot be used in conjunction with the AST\_\_NOBAD + flag (an error will be reported if both flags are specified). + } + \sstdiytopic{ + Propagation of Missing Data + }{ + Unless the AST\_\_NOBAD flag is specified, instances of missing data + (bad pixels) in the output grid are + identified by occurrences of the \texttt{"} badval\texttt{"} value in the \texttt{"} out\texttt{"} + array. These may be produced if any of the following happen: + + \sstitemlist{ + + \sstitem + The input position (the transformed position of the output + pixel\texttt{'} s centre) lies outside the boundary of the grid of input + pixels. + + \sstitem + The input position lies inside the boundary of a bad input + pixel. In this context, an input pixel is considered bad if its + data value is equal to \texttt{"} badval\texttt{"} and the AST\_\_USEBAD flag is + set via the \texttt{"} flags\texttt{"} parameter. + (Positions which have half-integral coordinate values, and + therefore lie on a pixel boundary, are regarded as lying within + the pixel with the larger, i.e. more positive, index.) + + \sstitem + The set of neighbouring input pixels (excluding those which + are bad) is unsuitable for calculating an interpolated + value. Whether this is true may depend on the sub-pixel + interpolation scheme in use. + + \sstitem + The interpolated value lies outside the range which can be + represented using the data type of the \texttt{"} out\texttt{"} array. + + } + In addition, associated output variance estimates (if + calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"} + value in the \texttt{"} out\_var\texttt{"} array under any of the following + circumstances: + + \sstitemlist{ + + \sstitem + The associated resampled data value (in the \texttt{"} out\texttt{"} array) is bad. + + \sstitem + The set of neighbouring input pixels which contributed to the + output data value do not all have valid variance estimates + associated with them. In this context, an input variance + estimate may be regarded as bad either because it has the value + \texttt{"} badval\texttt{"} (and the AST\_\_USEBAD flag is set), or because it is + negative. + + \sstitem + The set of neighbouring input pixels for which valid variance + values are available is unsuitable for calculating an overall + variance value. Whether this is true may depend on the sub-pixel + interpolation scheme in use. + + \sstitem + The variance value lies outside the range which can be + represented using the data type of the \texttt{"} out\_var\texttt{"} array. + + } + If the AST\_\_NOBAD flag is specified via + parameter \texttt{"} flags\texttt{"} , + then output array elements that would otherwise be set to + \texttt{"} badval\texttt{"} + are instead left holding the value they had on entry to this + function. The number of such array elements is returned as + the function value. + } +} +\sstroutine{ + astResolve +}{ + Resolve a vector into two orthogonal components +}{ + \sstdescription{ + This function resolves a vector into two perpendicular components. + The vector from point 1 to point 2 is used as the basis vector. + The vector from point 1 to point 3 is resolved into components + parallel and perpendicular to this basis vector. The lengths of the + two components are returned, together with the position of closest + aproach of the basis vector to point 3. + } + \sstsynopsis{ + void astResolve( AstFrame $*$this, const double point1[], + const double point2[], const double point3[], + double point4[], double $*$d1, double $*$d2 ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{Frame}{Frame}. + } + \sstsubsection{ + point1 + }{ + An array of double, with one element for each Frame axis + (\htmlref{Naxes}{Naxes} attribute). This marks the start of the basis vector, + and of the vector to be resolved. + } + \sstsubsection{ + point2 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute). This marks the end of the basis vector. + } + \sstsubsection{ + point3 + }{ + An array of double, with one element for each Frame axis + (Naxes attribute). This marks the end of the vector to be + resolved. + } + \sstsubsection{ + point4 + }{ + An array of double, with one element for each Frame axis + in which the coordinates of the point of closest approach of the + basis vector to point 3 will be returned. + } + \sstsubsection{ + d1 + }{ + The address of a location at which to return the distance from + point 1 to point 4 (that is, the length of the component parallel + to the basis vector). Positive values are in the same sense as + movement from point 1 to point 2. + } + \sstsubsection{ + d2 + }{ + The address of a location at which to return the distance from + point 4 to point 3 (that is, the length of the component + perpendicular to the basis vector). The value is always positive. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Each vector used in this function is the path of + shortest distance between two points, as defined by the + \htmlref{astDistance}{astDistance} function. + + \sstitem + This function will return \texttt{"} bad\texttt{"} coordinate values (AST\_\_BAD) + if any of the input coordinates has this value, or if the required + output values are undefined. + } + } +} +\sstroutine{ + astRetainFits +}{ + Indicate that the current card in a FitsChan should be retained +}{ + \sstdescription{ + This function + stores a flag with the current card in the \htmlref{FitsChan}{FitsChan} indicating that + the card should not be removed from the FitsChan when an \htmlref{Object}{Object} is + read from the FitsChan using + \htmlref{astRead}{astRead}. + + Cards that have not been flagged in this way are removed when a + read operation completes succesfully, but only if the card was used + in the process of creating the returned AST Object. Any cards that + are irrelevant to the creation of the AST Object are retained whether + or not they are flagged. + } + \sstsynopsis{ + void astRetainFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function returns without action if the FitsChan is + initially positioned at the \texttt{"} end-of-file\texttt{"} (i.e. if the \htmlref{Card}{Card} + attribute exceeds the number of cards in the FitsChan). + + \sstitem + The current card is not changed by this function. + } + } +} +\sstroutine{ + astSame +}{ + Test if two AST pointers refer to the same Object +}{ + \sstdescription{ + This function returns a boolean result (0 or 1) to indicate + whether two pointers refer to the same \htmlref{Object}{Object}. + } + \sstsynopsis{ + int astSame( AstObject $*$this, AstObject $*$that ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the first Object. + } + \sstsubsection{ + that + }{ + Pointer to the second Object. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSame() + }{ + One if the two pointers refer to the same Object, otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Two independent Objects that happen to be identical are not + considered to be the same Object by this function. + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any reason. + } + } +} +\sstroutine{ + astSelectorMap +}{ + Create a SelectorMap +}{ + \sstdescription{ + This function creates a new \htmlref{SelectorMap}{SelectorMap} and optionally initialises + its attributes. + + A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains + a given input position. + + A SelectorMap encapsulates a number of Regions that all have the same + number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of + inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes + spanned by one of the encapsulated Region. All SelectorMaps have only + a single output. SelectorMaps do not define an inverse transformation. + + For each input position, the forward transformation of a SelectorMap + searches through the encapsulated Regions (in the order supplied when + the SelectorMap was created) until a Region is found which contains + the input position. The index associated with this Region is + returned as the SelectorMap output value (the index value is the + position of the Region within the list of Regions supplied when the + SelectorMap was created, starting at 1 for the first Region). If an + input position is not contained within any Region, a value of zero is + returned by the forward transformation. + + If a compound Mapping contains a SelectorMap in series with its own + inverse, the combination of the two adjacent SelectorMaps will be + replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using + \htmlref{astSimplify}{astSimplify}. + + In practice, SelectorMaps are often used in conjunction with SwitchMaps. + } + \sstsynopsis{ + AstSelectorMap $*$astSelectorMap( int nreg, AstRegion $*$regs[], + double badval, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nreg + }{ + The number of supplied Regions. + } + \sstsubsection{ + regs + }{ + An array of pointers to the Regions. All the supplied Regions must + relate to the same coordinate Frame. The number of axes in this + coordinate Frame defines the number of inputs for the SelectorMap. + } + \sstsubsection{ + badval + }{ + The value to be returned by the forward transformation of the + SelectorMap for any input positions that have a bad (AST\_\_BAD) + value on any axis. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SelectorMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSelectorMap() + }{ + A pointer to the new SelectorMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Deep copies are taken of the supplied Regions. This means that + any subsequent changes made to the component Regions using the + supplied pointers will have no effect on the SelectorMap. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSet +}{ + Set attribute values for an Object +}{ + \sstdescription{ + This function assigns a set of attribute values to an \htmlref{Object}{Object}, + over-riding any previous values. The attributes and their new + values are specified via a character string, which should + contain a comma-separated list of the form: + + \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} + + where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value + to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual + representation of the value to be assigned. This value will be + interpreted according to the attribute\texttt{'} s data type. + + The string supplied may also contain \texttt{"} printf\texttt{"} -style format + specifiers, identified by \texttt{"} \%\texttt{"} signs in the usual way. If + present, these will be substituted by values supplied as + additional optional arguments (using the normal \texttt{"} printf\texttt{"} rules) + before the string is used. + } + \sstsynopsis{ + void astSet( AstObject $*$this, const char $*$settings, ... ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + settings + }{ + Pointer to a null-terminated character string containing a + comma-separated list of attribute settings in the form described + above. + } + \sstsubsection{ + ... + }{ + Optional additional arguments which supply values to be + substituted for any \texttt{"} printf\texttt{"} -style format specifiers that + appear in the \texttt{"} settings\texttt{"} string. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstexamples{ + \sstexamplesubsection{ + astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"} ); + }{ + Sets the Report attribute for Object \texttt{"} map\texttt{"} to the value 1 and + the Zoom attribute to 25.0. + } + \sstexamplesubsection{ + astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis ); + }{ + Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"} to a + suitable string, where the axis number is obtained from + \texttt{"} axis\texttt{"} , a variable of type int. + } + \sstexamplesubsection{ + astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring ); + }{ + Sets the Title attribute for Object \texttt{"} frame\texttt{"} to the contents of + the string \texttt{"} mystring\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + White space may also surround attribute values, where it will + generally be ignored (except for string-valued attributes where + it is significant and forms part of the value to be assigned). + + \sstitem + To include a literal comma in the value assigned to an attribute, + the whole attribute value should be enclosed in quotation markes. + Alternatively, you can use \texttt{"} \%s\texttt{"} format and supply the value as a + separate additional argument to astSet (or use the astSetC + function instead). + + \sstitem + The same procedure may be adopted if \texttt{"} \%\texttt{"} signs are to be included + and are not to be interpreted as format specifiers (alternatively, + the \texttt{"} printf\texttt{"} convention of writing \texttt{"} \%\%\texttt{"} may be used). + + \sstitem + An error will result if an attempt is made to set a value for + a read-only attribute. + } + } +} +\sstroutine{ + astSet$<$X$>$ +}{ + Set an attribute value for an Object +}{ + \sstdescription{ + This is a family of functions which set a specified attribute + value for an \htmlref{Object}{Object} using one of several different data + types. The type is selected by replacing $<$X$>$ in the function name + by C, D, F, I or L, to supply a value in const char$*$ (i.e. string), + double, float, int, or long format, respectively. + + If possible, the value you supply is converted to the type of + the attribute. If conversion is not possible, an error will + result. + } + \sstsynopsis{ + void astSet$<$X$>$( AstObject $*$this, const char $*$attrib, $<$X$>$type value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + attrib + }{ + Pointer to a null-terminated character string containing the + name of the attribute whose value is to be set. + } + \sstsubsection{ + value + }{ + The value to be set for the attribute, in the data type corresponding + to $<$X$>$ (or, in the case of astSetC, a pointer to a null-terminated + character string containing this value). + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + These functions apply to all Objects. + } + } + \sstexamples{ + \sstexamplesubsection{ + astSetI( frame, \texttt{"} Preserve\texttt{"} , 1 ); + }{ + Sets the Preserve attribute value for Object \texttt{"} frame\texttt{"} to 1. + } + \sstexamplesubsection{ + astSetC( plot, \texttt{"} Format(1)\texttt{"} , \texttt{"} \%.2g\texttt{"} ); + }{ + Sets the Format(1) attribute value for Object \texttt{"} plot\texttt{"} to the + character string \texttt{"} \%.2g\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + An error will result if an attempt is made to set a value for + a read-only attribute. + } + } +} +\sstroutine{ + astSetActiveUnit +}{ + Specify how the Unit attribute should be used +}{ + \sstdescription{ + This function + sets the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}, which + controls how the Frame behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) + to match another Frame. If the ActiveUnit flag is set in both + template and target Frames then the returned \htmlref{Mapping}{Mapping} takes into account + any differences in axis units. The default value for simple Frames is + zero, which preserves the behaviour of versions of AST prior to + version 2.0. + + If the ActiveUnit flag of either Frame is + zero, + then the Mapping will ignore any difference in the Unit attributes of + corresponding template and target axes. In this mode, the Unit + attributes are purely descriptive commentary for the benefit of + human readers and do not influence the Mappings between Frames. + This is the behaviour which all Frames had in older version of AST, + prior to the introduction of this attribute. + + If the ActiveUnit flag of both Frames is + non-zero, + then the Mapping from template to target will take account of any + difference in the axis Unit attributes, where-ever possible. For + instance, if corresponding target and template axes have Unit strings of + \texttt{"} km\texttt{"} and \texttt{"} m\texttt{"} , then the \htmlref{FrameSet}{FrameSet} class will use a \htmlref{ZoomMap}{ZoomMap} to connect + them which introduces a scaling of 1000. If no Mapping can be found + between the corresponding units string, then an error is reported. + In this mode, it is assumed that values of the Unit attribute conform + to the syntax for units strings described in the FITS WCS Paper I + \texttt{"} Representations of world coordinates in FITS\texttt{"} (Greisen \& Calabretta). + Particularly, any of the named unit symbols, functions, operators or + standard multiplier prefixes listed within that paper can be used within + a units string. A units string may contain symbols for unit which are + not listed in the FITS paper, but transformation to any other units + will then not be possible (except to units which depend only on the + same unknown units - thus \texttt{"} flops\texttt{"} can be transformed to \texttt{"} Mflops\texttt{"} + even though \texttt{"} flops\texttt{"} is not a standard FITS unit symbol). + + A range of common non-standard variations of unit names and multiplier + prefixes are also allowed, such as adding an \texttt{"} s\texttt{"} to the end of Angstrom, + using a lower case \texttt{"} a\texttt{"} at the start of \texttt{"} angstrom\texttt{"} , \texttt{"} micron\texttt{"} instead of + \texttt{"} um\texttt{"} , \texttt{"} sec\texttt{"} instead of \texttt{"} s\texttt{"} , etc. + + If the ActiveUnit flag is non-zero, setting a new Unit value for an + axis may also change its Label and Symbol attributes. For instance, if + an axis has Unit \texttt{"} Hz\texttt{"} and Label \texttt{"} frequency\texttt{"} , then changing its Unit to + \texttt{"} log(Hz)\texttt{"} will change its Label to \texttt{"} log( frequency )\texttt{"} . In addition, + the \htmlref{Axis}{Axis} Format attribute will be cleared when-ever a new value + is assigned to the Unit attribute. + + Note, if a non-zero value is set for the ActiveUnit flag, then changing a + Unit value for the current Frame within a FrameSet will result in the + Frame being re-mapped (that is, the Mappings which define the + relationships between Frames within the FrameSet will be modified to + take into account the change in Units). + } + \sstsynopsis{ + void astSetActiveUnit( AstFrame $*$this, int value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + value + }{ + The new value to use. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The ActiveUnit flag for a SkyFrame is always 0 (any value + supplied using this function is ignored). + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + The ActiveUnit flag for a SpecFrame is always 1 (any value + supplied using this function is ignored). + } + \sstsubsection{ + \htmlref{FluxFrame}{FluxFrame} + }{ + The ActiveUnit flag for a FluxFrame is always 1 (any value + supplied using this function is ignored). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The default ActiveUnit flag for a CmpFrame is 1 if both of the + component Frames are using active units, and zero otherwise. When + a new value is set for the ActiveUnit flag, the flag value + is propagated to the component Frames. This change will be + reflected through all references to the component Frames, not + just those encapsulated within the CmpFrame. + } + \sstsubsection{ + \htmlref{Region}{Region}: + }{ + Regions always use active units if possible. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The ActiveUnit flag resembles a Frame attribute, except that it + cannot be tested or cleared, and it cannot be accessed using the + generic \htmlref{astGet$<$X$>$}{astGet$<$X$>$} and \htmlref{astSet$<$X$>$}{astSet$<$X$>$} functions. + + \sstitem + The \htmlref{astGetActiveUnit}{astGetActiveUnit} function can be used to retrieve the current + value of the ActiveUnit flag. + } + } +} +\sstroutine{ + astSetFits$<$X$>$ +}{ + Store a keyword value in a FitsChan +}{ + \sstdescription{ + This is a family of functions which store values for named keywords + within a \htmlref{FitsChan}{FitsChan} at the current card position. The supplied keyword + value can either over-write an existing keyword value, or can be + inserted as a new header card into the FitsChan. + + The keyword data type is selected by replacing $<$X$>$ in the function name + by one of the following strings representing the recognised FITS data + + types: + + \sstitemlist{ + + \sstitem + CF - Complex floating point values. + + \sstitem + CI - Complex integer values. + + \sstitem + F - Floating point values. + + \sstitem + I - Integer values. + + \sstitem + L - Logical (i.e. boolean) values. + + \sstitem + S - String values. + + \sstitem + CN - A \texttt{"} CONTINUE\texttt{"} value, these are treated like string values, but + are encoded without an equals sign. + + } + The data type of the \texttt{"} value\texttt{"} parameter depends on $<$X$>$ as follows: + + \sstitemlist{ + + \sstitem + CF - \texttt{"} double $*$\texttt{"} (a pointer to a 2 element array holding the real and + imaginary parts of the complex value). + + \sstitem + CI - \texttt{"} int $*$\texttt{"} (a pointer to a 2 element array holding the real and + imaginary parts of the complex value). + + \sstitem + F - \texttt{"} double\texttt{"} . + + \sstitem + I - \texttt{"} int\texttt{"} . + + \sstitem + L - \texttt{"} int\texttt{"} . + + \sstitem + S - \texttt{"} const char $*$\texttt{"} . + + \sstitem + CN - \texttt{"} const char $*$\texttt{"} . + } + } + \sstsynopsis{ + void astSetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type value, + const char $*$comment, int overwrite ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + name + }{ + Pointer to a null-terminated character string + containing the FITS keyword name. This may be a complete FITS + header card, in which case the keyword to use is extracted from + it. No more than 80 characters are read from this string. + } + \sstsubsection{ + value + }{ + The keyword value to store with the named keyword. The data type + of this parameter depends on $<$X$>$ as described above. + } + \sstsubsection{ + comment + }{ + A pointer to a null terminated string + holding a comment to associated with the keyword. + If a NULL pointer or + a blank string is supplied, then any comment included in the string + supplied for the + \texttt{"} name\texttt{"} parameter is used instead. If \texttt{"} name\texttt{"} + contains no comment, then any existing comment in the card being + over-written is retained. Otherwise, no comment is stored with + the card. + } + \sstsubsection{ + overwrite + }{ + If non-zero, + the new card formed from the supplied keyword name, value and comment + string over-writes the current card, and the current card is + incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If + zero, + the new card is inserted in front of the current card and the current + card is left unchanged. In either case, if the current card on entry + points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of + the list. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The + function \htmlref{astSetFitsU}{astSetFitsU} + can be used to indicate that no value is associated with a keyword. + + \sstitem + The + function \htmlref{astSetFitsCM}{astSetFitsCM} + can be used to store a pure comment card (i.e. a card with a blank + keyword). + + \sstitem + To assign a new value for an existing keyword within a FitsChan, + first find the card describing the keyword using \htmlref{astFindFits}{astFindFits}, and + then use one of the astSetFits$<$X$>$ family to over-write the old value. + + \sstitem + If, on exit, there are no cards following the card written by + this function, then the current card is left pointing at the + \texttt{"} end-of-file\texttt{"} . + + \sstitem + An error will be reported if the keyword name does not conform + to FITS requirements. + } + } +} +\sstroutine{ + astSetFitsCM +}{ + Store a comment card in a FitsChan +}{ + \sstdescription{ + This + function + stores a comment card ( i.e. a card with no keyword name or equals + sign) within a \htmlref{FitsChan}{FitsChan} at the current card position. The new card + can either over-write an existing card, or can be inserted as a new + card into the FitsChan. + } + \sstsynopsis{ + void astSetFitsCM( AstFitsChan $*$this, const char $*$comment, + int overwrite ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + comment + }{ + A pointer to a null terminated string + holding the text of the comment card. + If a NULL pointer or + a blank string is supplied, then a totally blank card is produced. + } + \sstsubsection{ + overwrite + }{ + If non-zero, + the new card over-writes the current card, and the current card is + incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If + zero, + the new card is inserted in front of the current card and the current + card is left unchanged. In either case, if the current card on entry + points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of + the list. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If, on exit, there are no cards following the card written by + this function, then the current card is left pointing at the + \texttt{"} end-of-file\texttt{"} . + } + } +} +\sstroutine{ + astSetFitsU +}{ + Store an undefined keyword value in a FitsChan +}{ + \sstdescription{ + This + function + stores an undefined value for a named keyword within + a \htmlref{FitsChan}{FitsChan} at the current card position. The new undefined value + can either over-write an existing keyword value, or can be inserted + as a new header card into the FitsChan. + } + \sstsynopsis{ + void astSetFitsU( AstFitsChan $*$this, const char $*$name, + const char $*$comment, int overwrite ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + name + }{ + Pointer to a null-terminated character string + containing the FITS keyword name. This may be a complete FITS + header card, in which case the keyword to use is extracted from + it. No more than 80 characters are read from this string. + } + \sstsubsection{ + comment + }{ + A pointer to a null terminated string + holding a comment to associated with the keyword. + If a NULL pointer or + a blank string is supplied, then any comment included in the string + supplied for the + \texttt{"} name\texttt{"} parameter is used instead. If \texttt{"} name\texttt{"} + contains no comment, then any existing comment in the card being + over-written is retained. Otherwise, no comment is stored with + the card. + } + \sstsubsection{ + overwrite + }{ + If non-zero, + the new card formed from the supplied keyword name and comment + string over-writes the current card, and the current card is + incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"} attribute). If + zero, + the new card is inserted in front of the current card and the current + card is left unchanged. In either case, if the current card on entry + points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of + the list. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If, on exit, there are no cards following the card written by + this function, then the current card is left pointing at the + \texttt{"} end-of-file\texttt{"} . + + \sstitem + An error will be reported if the keyword name does not conform + to FITS requirements. + } + } +} +\sstroutine{ + astSetRefPos +}{ + Set the reference position in a specified celestial coordinate system +}{ + \sstdescription{ + This function + sets the reference position (see attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) using + axis values (in radians) supplied within the celestial coordinate + system represented by a supplied \htmlref{SkyFrame}{SkyFrame}. + } + \sstsynopsis{ + void astSetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double lon, + double lat ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the \htmlref{SpecFrame}{SpecFrame}. + } + \sstsubsection{ + frm + }{ + Pointer to the SkyFrame which defines the celestial coordinate + system in which the longitude and latitude values are supplied. + If NULL + is supplied, then the supplied longitude and latitude values are + assumed to be FK5 J2000 RA and Dec values. + } + \sstsubsection{ + lon + }{ + The longitude of the reference point, in the coordinate system + represented by the supplied SkyFrame (radians). + } + \sstsubsection{ + lat + }{ + The latitude of the reference point, in the coordinate system + represented by the supplied SkyFrame (radians). + } + } +} +\sstroutine{ + astSetStatus +}{ + Set the AST error status to an explicit value +}{ + \sstdescription{ + This function sets the AST error status to the value supplied. + It does not cause any error message to be produced and should + not be used as part of normal error reporting. Its purpose is + simply to communicate to AST that an error has occurred in some + other item of software. + + For example, a source or sink function supplied as an argument + to \htmlref{astChannel}{astChannel} or \htmlref{astFitsChan}{astFitsChan} might use this to signal that an + input/output error has occurred. AST could then respond by + terminating the current read or write operation. + } + \sstsynopsis{ + void astSetStatus( int status\_value ) + } + \sstparameters{ + \sstsubsection{ + status\_value + }{ + The new error status value to be set. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the AST error status is set to an error value, most AST + functions will not execute and will simply return without + action. To clear the error status and restore normal behaviour, + use \htmlref{astClearStatus}{astClearStatus}. + } + } +} +\sstroutine{ + astSetUnc +}{ + Store uncertainty information in a Region +}{ + \sstdescription{ + Each \htmlref{Region}{Region} (of any class) can have an \texttt{"} uncertainty\texttt{"} which specifies + the uncertainties associated with the boundary of the Region. This + information is supplied in the form of a second Region. The uncertainty + in any point on the boundary of a Region is found by shifting the + associated \texttt{"} uncertainty\texttt{"} Region so that it is centred at the boundary + point being considered. The area covered by the shifted uncertainty + Region then represents the uncertainty in the boundary position. + The uncertainty is assumed to be the same for all points. + + The uncertainty is usually specified when the Region is created, but + this + function + allows it to be changed at any time. + } + \sstsynopsis{ + void astSetUnc( AstRegion $*$this, AstRegion $*$unc ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region which is to be assigned a new uncertainty. + } + \sstsubsection{ + unc + }{ + Pointer to the new uncertainty Region. This must be of a class for + which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, + etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. + A deep copy of the supplied Region will be taken, so subsequent + changes to the uncertainty Region using the supplied pointer will + have no effect on the Region + \texttt{"} this\texttt{"} . + } + } +} +\sstroutine{ + astShiftMap +}{ + Create a ShiftMap +}{ + \sstdescription{ + This function creates a new \htmlref{ShiftMap}{ShiftMap} and optionally initialises its + attributes. + + A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a + specified constant value. + } + \sstsynopsis{ + AstShiftMap $*$astShiftMap( int ncoord, const double shift[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of coordinate values for each point to be + transformed (i.e. the number of dimensions of the space in + which the points will reside). The same number is applicable + to both input and output points. + } + \sstsubsection{ + shift + }{ + An array containing the values to be added on to the input + coordinates in order to create the output coordinates. A separate + value should be supplied for each coordinate. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new ShiftMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astShiftMap() + }{ + A pointer to the new ShiftMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astShow +}{ + Display a textual representation of an Object on standard output +}{ + \sstdescription{ + This function displays a textual description of any AST \htmlref{Object}{Object} + on standard output. It is provided primarily as an aid to + debugging. + } + \sstsynopsis{ + void astShow( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be displayed. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } +} +\sstroutine{ + astShowFits +}{ + Display the contents of a FitsChan on standard output +}{ + \sstdescription{ + This function + formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output. + } + \sstsynopsis{ + void astShowFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } +} +\sstroutine{ + astShowMesh +}{ + Display a mesh of points covering the surface of a Region +}{ + \sstdescription{ + This function + writes a table to standard output containing the axis values at a + mesh of points covering the surface of the supplied \htmlref{Region}{Region}. Each row + of output contains a tab-separated list of axis values, one for + each axis in the \htmlref{Frame}{Frame} encapsulated by the Region. The number of + points in the mesh is determined by the \htmlref{MeshSize}{MeshSize} attribute. + + The table is preceded by a given title string, and followed by a + single line containing the word \texttt{"} ENDMESH\texttt{"} . + } + \sstsynopsis{ + void astShowMesh( AstRegion $*$this, int format, const char $*$ttl ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Region. + } + \sstsubsection{ + format + }{ + A boolean value indicating if the displayed axis values should + be formatted according to the Format attribute associated with + the Frame\texttt{'} s axis. Otherwise, they are displayed as simple + floating point values. + } + \sstsubsection{ + ttl + }{ + A title to display before displaying the first position. + } + } +} +\sstroutine{ + astSimplify +}{ + Simplify a Mapping +}{ + \sstdescription{ + This function simplifies a \htmlref{Mapping}{Mapping} (which may be a compound + Mapping such as a \htmlref{CmpMap}{CmpMap}) to eliminate redundant computational + steps, or to merge separate steps which can be performed more + efficiently in a single operation. + + As a simple example, a Mapping which multiplied coordinates by + 5, and then multiplied the result by 10, could be simplified to + a single step which multiplied by 50. Similarly, a Mapping which + multiplied by 5, and then divided by 5, could be reduced to a + simple copying operation. + + This function should typically be applied to Mappings which have + undergone substantial processing or have been formed by merging + other Mappings. It is of potential benefit, for example, in + reducing execution time if applied before using a Mapping to + transform a large number of coordinates. + } + \sstsynopsis{ + AstMapping $*$astSimplify( AstMapping $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the original Mapping. + } + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + This function applies to all Mappings. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + If the supplied Mapping is a FrameSet, the returned Mapping + will be a copy of the supplied FrameSet in which all the + inter-\htmlref{Frame}{Frame} Mappings have been simplified. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSimplify() + }{ + A new pointer to the (possibly simplified) Mapping. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Mappings that have a set value for their \htmlref{Ident}{Ident} attribute are + left unchanged after simplification. This is so that their + individual identity is preserved. This restriction does not + apply to the simplification of Frames. + + \sstitem + This function can safely be applied even to Mappings which + cannot be simplified. If no simplification is possible, it + behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the + original Mapping. + + \sstitem + The Mapping returned by this function may not be independent + of the original (even if simplification was possible), and + modifying it may therefore result in indirect modification of + the original. If a completely independent result is required, a + copy should be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSkyFrame +}{ + Create a SkyFrame +}{ + \sstdescription{ + This function creates a new \htmlref{SkyFrame}{SkyFrame} and optionally initialises + its attributes. + + A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes + celestial longitude/latitude coordinate systems. The particular + celestial coordinate system to be represented is specified by + setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default + is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or + an \htmlref{Epoch}{Epoch}. + + For each of the supported celestial coordinate systems, a SkyFrame + can apply an optional shift of origin to create a coordinate system + representing offsets within the celestial coordinate system from some + specified point. This offset coordinate system can also be rotated to + define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs} + and SkyRefP + + All the coordinate values used by a SkyFrame are in + radians. These may be formatted in more conventional ways for + display by using \htmlref{astFormat}{astFormat}. + } + \sstsynopsis{ + AstSkyFrame $*$astSkyFrame( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SkyFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSkyFrame() + }{ + A pointer to the new SkyFrame. + } + } + \sstexamples{ + \sstexamplesubsection{ + frame = astSkyFrame( \texttt{"} \texttt{"} ); + }{ + Creates a SkyFrame to describe the default ICRS celestial + coordinate system. + } + \sstexamplesubsection{ + frame = astSkyFrame( \texttt{"} System = FK5, Equinox = J2005, Digits = 10\texttt{"} ); + }{ + Creates a SkyFrame to describe the FK5 celestial + coordinate system, with a mean Equinox of J2005.0. + Because especially accurate coordinates will be used, + additional precision (10 digits) has been requested. This will + be used when coordinate values are formatted for display. + } + \sstexamplesubsection{ + frame = astSkyFrame( \texttt{"} System = FK4, Equinox = 1955-sep-2\texttt{"} ); + }{ + Creates a SkyFrame to describe the old FK4 celestial + coordinate system. A default Epoch value (B1950.0) is used, + but the mean Equinox value is given explicitly as \texttt{"} 1955-sep-2\texttt{"} . + } + \sstexamplesubsection{ + frame = astSkyFrame( \texttt{"} System = GAPPT, Epoch = \%s\texttt{"} , date ); + }{ + Creates a SkyFrame to describe the Geocentric Apparent + celestial coordinate system. The Epoch value, which specifies + the date of observation, is obtained from a date/time string + supplied via the string pointer \texttt{"} date\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Currently, the default celestial coordinate system is + ICRS. However, this default may change in future as new + astrometric standards evolve. The intention is to track the most + modern appropriate standard. For this reason, you should use the + default only if this is what you intend (and can tolerate any + associated slight change in behaviour with future versions of + this function). If you intend to use the ICRS system + indefinitely, then you should specify it explicitly using an + \texttt{"} options\texttt{"} value of \texttt{"} System=ICRS\texttt{"} . + + \sstitem + Whichever celestial coordinate system is represented, it will + have two axes. The first of these will be the longitude axis + and the second will be the latitude axis. This order can be + changed using \htmlref{astPermAxes}{astPermAxes} if required. + + \sstitem + When conversion between two SkyFrames is requested (as when + supplying SkyFrames to \htmlref{astConvert}{astConvert}), + account will be taken of the nature of the celestial coordinate + systems they represent, together with any qualifying mean Equinox or + Epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} attribute will also be taken into + account. The results will therefore fully reflect the + relationship between positions on the sky measured in the two + systems. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSkyOffsetMap +}{ + Returns a Mapping which goes from absolute coordinates to offset + coordinates +}{ + \sstdescription{ + This function returns a \htmlref{Mapping}{Mapping} in which the forward transformation + transforms a position in the coordinate system given by the \htmlref{System}{System} + attribute of the supplied \htmlref{SkyFrame}{SkyFrame}, into the offset coordinate system + specified by the SkyRef, SkyRefP and \htmlref{SkyRefIs}{SkyRefIs} attributes of the + supplied SkyFrame. + + A \htmlref{UnitMap}{UnitMap} is returned if the SkyFrame does not define an offset + coordinate system. + } + \sstsynopsis{ + AstMapping $*$astSkyOffsetMap( AstSkyFrame $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the SkyFrame. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSkyOffsetMap() + }{ + Pointer to the returned Mapping. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSlaAdd +}{ + Add a celestial coordinate conversion to an SlaMap +}{ + \sstdescription{ + This function adds one of the standard celestial coordinate + system conversions provided by the SLALIB Positional Astronomy + Library (Starlink User Note SUN/67) to an existing \htmlref{SlaMap}{SlaMap}. + + When an SlaMap is first created (using \htmlref{astSlaMap}{astSlaMap}), it simply + performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSlaAdd (repeatedly + if necessary), one or more coordinate conversion steps may then + be added, which the SlaMap will perform in sequence. This allows + multi-step conversions between a variety of celestial coordinate + systems to be assembled out of the building blocks provided by + SLALIB. + + Normally, if an SlaMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), + then its forward transformation is performed by carrying out + each of the individual coordinate conversions specified by + astSlaAdd in the order given (i.e. with the most recently added + conversion applied last). + + This order is reversed if the SlaMap\texttt{'} s Invert attribute is + non-zero (or if the inverse transformation is requested by any + other means) and each individual coordinate conversion is also + replaced by its own inverse. This process inverts the overall + effect of the SlaMap. In this case, the first conversion to be + applied would be the inverse of the one most recently added. + } + \sstsynopsis{ + void astSlaAdd( AstSlaMap $*$this, const char $*$cvt, const double args[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the SlaMap. + } + \sstsubsection{ + cvt + }{ + Pointer to a null-terminated string which identifies the + celestial coordinate conversion to be added to the + SlaMap. See the \texttt{"} SLALIB Conversions\texttt{"} section for details of + those available. + } + \sstsubsection{ + args + }{ + An array containing argument values for the celestial + coordinate conversion. The number of arguments required, and + hence the number of array elements used, depends on the + conversion specified (see the \texttt{"} SLALIB Conversions\texttt{"} + section). This array is ignored + and a NULL pointer may be supplied + if no arguments are needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + All coordinate values processed by an SlaMap are in + radians. The first coordinate is the celestial longitude and the + second coordinate is the celestial latitude. + + \sstitem + When assembling a multi-stage conversion, it can sometimes be + difficult to determine the most economical conversion path. For + example, converting to the standard FK5 coordinate system as an + intermediate stage is often sensible in formulating the problem, + but may introduce unnecessary extra conversion steps. A solution + to this is to include all the steps which are (logically) + necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting + SlaMap. The simplification process will eliminate any steps + which turn out not to be needed. + + \sstitem + This function does not check to ensure that the sequence of + coordinate conversions added to an SlaMap is physically + meaningful. + } + } + \sstdiytopic{ + SLALIB Conversions + }{ + The following strings (which are case-insensitive) may be supplied + via the \texttt{"} cvt\texttt{"} parameter to indicate which celestial coordinate + conversion is to be added to the SlaMap. Each string is derived + from the name of the SLALIB routine that performs the + conversion and the relevant documentation (SUN/67) should be + consulted for details. Where arguments are needed by + the conversion, they are listed in parentheses. Values for + these arguments should be given, via the \texttt{"} args\texttt{"} array, in the + order indicated. The argument names match the corresponding + SLALIB routine arguments and their values should be given using + exactly the same units, time scale, calendar, etc. as described + in SUN/67: + + \sstitemlist{ + + \sstitem + \texttt{"} ADDET\texttt{"} (EQ): Add E-terms of aberration. + + \sstitem + \texttt{"} SUBET\texttt{"} (EQ): Subtract E-terms of aberration. + + \sstitem + \texttt{"} PREBN\texttt{"} (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4) + precession model. + + \sstitem + \texttt{"} PREC\texttt{"} (EP0,EP1): Apply IAU 1975 (FK5) precession model. + + \sstitem + \texttt{"} FK45Z\texttt{"} (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax). + + \sstitem + \texttt{"} FK54Z\texttt{"} (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax). + + \sstitem + \texttt{"} AMP\texttt{"} (DATE,EQ): Convert geocentric apparent to mean place. + + \sstitem + \texttt{"} MAP\texttt{"} (EQ,DATE): Convert mean place to geocentric apparent. + + \sstitem + \texttt{"} ECLEQ\texttt{"} (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial. + + \sstitem + \texttt{"} EQECL\texttt{"} (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates. + + \sstitem + \texttt{"} GALEQ\texttt{"} : Convert galactic coordinates to FK5 J2000.0 equatorial. + + \sstitem + \texttt{"} EQGAL\texttt{"} : Convert FK5 J2000.0 equatorial to galactic coordinates. + + \sstitem + \texttt{"} HFK5Z\texttt{"} (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial. + + \sstitem + \texttt{"} FK5HZ\texttt{"} (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS. + + \sstitem + \texttt{"} GALSUP\texttt{"} : Convert galactic to supergalactic coordinates. + + \sstitem + \texttt{"} SUPGAL\texttt{"} : Convert supergalactic coordinates to galactic. + + \sstitem + \texttt{"} J2000H\texttt{"} : Convert dynamical J2000.0 to ICRS. + + \sstitem + \texttt{"} HJ2000\texttt{"} : Convert ICRS to dynamical J2000.0. + + \sstitem + \texttt{"} R2H\texttt{"} (LAST): Convert RA to Hour Angle. + + \sstitem + \texttt{"} H2R\texttt{"} (LAST): Convert Hour Angle to RA. + + } + For example, to use the \texttt{"} ADDET\texttt{"} conversion, which takes a single + argument EQ, you should consult the documentation for the SLALIB + routine SLA\_ADDET. This describes the conversion in detail and + shows that EQ is the Besselian epoch of the mean equator and + equinox. + This value should then be supplied to astSlaAdd in args[0]. + + In addition the following strings may be supplied for more complex + conversions which do not correspond to any one single SLALIB routine + (DIURAB is the magnitude of the diurnal aberration vector in units + of \texttt{"} day/(2.PI)\texttt{"} , DATE is the Modified Julian Date of the observation, + and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian + coordinates, in metres, of the observer): + + \sstitemlist{ + + \sstitem + \texttt{"} HPCEQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial. + + \sstitem + \texttt{"} EQHPC\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian. + + \sstitem + \texttt{"} HPREQ\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial. + + \sstitem + \texttt{"} EQHPR\texttt{"} (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial. + + \sstitem + \texttt{"} HEEQ\texttt{"} (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial. + + \sstitem + \texttt{"} EQHE\texttt{"} (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic. + + \sstitem + \texttt{"} H2E\texttt{"} (LAT,DIRUAB): Convert horizon coordinates to equatorial. + + \sstitem + \texttt{"} E2H\texttt{"} (LAT,DIURAB): Convert equatorial coordinates to horizon. + + } + Note, the \texttt{"} H2E\texttt{"} and \texttt{"} E2H\texttt{"} conversions convert between topocentric + horizon coordinates (azimuth,elevation), and apparent local equatorial + coordinates (hour angle,declination). Thus, the effects of diurnal + aberration are taken into account in the conversions but the effects + of atmospheric refraction are not. + } +} +\sstroutine{ + astSlaMap +}{ + Create an SlaMap +}{ + \sstdescription{ + This function creates a new \htmlref{SlaMap}{SlaMap} and optionally initialises + its attributes. + + An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to + represent a sequence of conversions between standard celestial + (longitude, latitude) coordinate systems. + + When an SlaMap is first created, it simply performs a unit + (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd} + function, a series of coordinate conversion steps may then be + added, selected from those provided by the SLALIB Positional + Astronomy Library (Starlink User Note SUN/67). This allows + multi-step conversions between a variety of celestial coordinate + systems to be assembled out of the building blocks provided by + SLALIB. + + For details of the individual coordinate conversions available, + see the description of the astSlaAdd function. + } + \sstsynopsis{ + AstSlaMap $*$astSlaMap( int flags, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + flags + }{ + This parameter is reserved for future use and should currently + always be set to zero. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SlaMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSlaMap() + }{ + A pointer to the new SlaMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes (number of input and output + coordinates) for an SlaMap are both equal to 2. The first + coordinate is the celestial longitude and the second coordinate + is the celestial latitude. All coordinate values are in radians. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSpecAdd +}{ + Add a spectral coordinate conversion to a SpecMap +}{ + \sstdescription{ + This function adds one of the standard spectral coordinate + system conversions listed below to an existing \htmlref{SpecMap}{SpecMap}. + + When a SpecMap is first created (using \htmlref{astSpecMap}{astSpecMap}), it simply + performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSpecAdd (repeatedly + if necessary), one or more coordinate conversion steps may then + be added, which the SpecMap will perform in sequence. This allows + multi-step conversions between a variety of spectral coordinate + systems to be assembled out of the building blocks provided by + this class. + + Normally, if a SpecMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), + then its forward transformation is performed by carrying out + each of the individual coordinate conversions specified by + astSpecAdd in the order given (i.e. with the most recently added + conversion applied last). + + This order is reversed if the SpecMap\texttt{'} s Invert attribute is + non-zero (or if the inverse transformation is requested by any + other means) and each individual coordinate conversion is also + replaced by its own inverse. This process inverts the overall + effect of the SpecMap. In this case, the first conversion to be + applied would be the inverse of the one most recently added. + } + \sstsynopsis{ + void astSpecAdd( AstSpecMap $*$this, const char $*$cvt, const double args[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the SpecMap. + } + \sstsubsection{ + cvt + }{ + Pointer to a null-terminated string which identifies the + spectral coordinate conversion to be added to the + SpecMap. See the \texttt{"} Available Conversions\texttt{"} section for details of + those available. + } + \sstsubsection{ + args + }{ + An array containing argument values for the spectral + coordinate conversion. The number of arguments required, and + hence the number of array elements used, depends on the + conversion specified (see the \texttt{"} Available Conversions\texttt{"} + section). This array is ignored + and a NULL pointer may be supplied + if no arguments are needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When assembling a multi-stage conversion, it can sometimes be + difficult to determine the most economical conversion path. For + example, when converting between reference frames, converting first + to the heliographic reference frame as an intermediate stage is often + sensible in formulating the problem, but may introduce unnecessary + extra conversion steps. A solution to this is to include all the steps + which are (logically) necessary, but then to use + \htmlref{astSimplify}{astSimplify} to simplify the resulting + SpecMap. The simplification process will eliminate any steps + which turn out not to be needed. + + \sstitem + This function does not check to ensure that the sequence of + coordinate conversions added to a SpecMap is physically + meaningful. + } + } + \sstdiytopic{ + Available Conversions + }{ + The following strings (which are case-insensitive) may be supplied + via the \texttt{"} cvt\texttt{"} parameter to indicate which spectral coordinate + conversion is to be added to the SpecMap. Where arguments are needed by + the conversion, they are listed in parentheses. Values for + these arguments should be given, via the \texttt{"} args\texttt{"} array, in the + order indicated. Units and argument names are described at the end of + the list of conversions. + + \sstitemlist{ + + \sstitem + \texttt{"} FRTOVL\texttt{"} (RF): Convert frequency to relativistic velocity. + + \sstitem + \texttt{"} VLTOFR\texttt{"} (RF): Convert relativistic velocity to Frequency. + + \sstitem + \texttt{"} ENTOFR\texttt{"} : Convert energy to frequency. + + \sstitem + \texttt{"} FRTOEN\texttt{"} : Convert frequency to energy. + + \sstitem + \texttt{"} WNTOFR\texttt{"} : Convert wave number to frequency. + + \sstitem + \texttt{"} FRTOWN\texttt{"} : Convert frequency to wave number. + + \sstitem + \texttt{"} WVTOFR\texttt{"} : Convert wavelength (vacuum) to frequency. + + \sstitem + \texttt{"} FRTOWV\texttt{"} : Convert frequency to wavelength (vacuum). + + \sstitem + \texttt{"} AWTOFR\texttt{"} : Convert wavelength (air) to frequency. + + \sstitem + \texttt{"} FRTOAW\texttt{"} : Convert frequency to wavelength (air). + + \sstitem + \texttt{"} VRTOVL\texttt{"} : Convert radio to relativistic velocity. + + \sstitem + \texttt{"} VLTOVR\texttt{"} : Convert relativistic to radio velocity. + + \sstitem + \texttt{"} VOTOVL\texttt{"} : Convert optical to relativistic velocity. + + \sstitem + \texttt{"} VLTOVO\texttt{"} : Convert relativistic to optical velocity. + + \sstitem + \texttt{"} ZOTOVL\texttt{"} : Convert redshift to relativistic velocity. + + \sstitem + \texttt{"} VLTOZO\texttt{"} : Convert relativistic velocity to redshift. + + \sstitem + \texttt{"} BTTOVL\texttt{"} : Convert beta factor to relativistic velocity. + + \sstitem + \texttt{"} VLTOBT\texttt{"} : Convert relativistic velocity to beta factor. + + \sstitem + \texttt{"} USF2HL\texttt{"} (VOFF,RA,DEC): Convert frequency from a user-defined + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2US\texttt{"} (VOFF,RA,DEC): Convert frequency from heliocentric + reference frame to user-defined. + + \sstitem + \texttt{"} TPF2HL\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from + topocentric reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2TP\texttt{"} (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from + heliocentric reference frame to topocentric. + + \sstitem + \texttt{"} GEF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from geocentric + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2GE\texttt{"} (EPOCH,RA,DEC): Convert frequency from + heliocentric reference frame to geocentric. + + \sstitem + \texttt{"} BYF2HL\texttt{"} (EPOCH,RA,DEC): Convert frequency from + barycentric reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2BY\texttt{"} (EPOCH,RA,DEC): Convert frequency from + heliocentric reference frame to barycentric. + + \sstitem + \texttt{"} LKF2HL\texttt{"} (RA,DEC): Convert frequency from kinematic LSR + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2LK\texttt{"} (RA,DEC): Convert frequency from heliocentric + reference frame to kinematic LSR. + + \sstitem + \texttt{"} LDF2HL\texttt{"} (RA,DEC): Convert frequency from dynamical LSR + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2LD\texttt{"} (RA,DEC): Convert frequency from heliocentric + reference frame to dynamical LSR. + + \sstitem + \texttt{"} LGF2HL\texttt{"} (RA,DEC): Convert frequency from local group + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2LG\texttt{"} (RA,DEC): Convert frequency from heliocentric + reference frame to local group. + + \sstitem + \texttt{"} GLF2HL\texttt{"} (RA,DEC): Convert frequency from galactic + reference frame to heliocentric. + + \sstitem + \texttt{"} HLF2GL\texttt{"} (RA,DEC): Convert frequency from heliocentric + reference frame to galactic. + + } + The units for the values processed by the above conversions are as + follows: + + \sstitemlist{ + + \sstitem + all velocities: metres per second (positive if the source receeds from + the observer). + + \sstitem + frequency: Hertz. + + \sstitem + all wavelengths: metres. + + \sstitem + energy: Joules. + + \sstitem + wave number: cycles per metre. + + } + The arguments used in the above conversions are as follows: + + \sstitemlist{ + + \sstitem + RF: Rest frequency (Hz). + + \sstitem + OBSALT: Geodetic altitude of observer (IAU 1975, metres). + + \sstitem + OBSLAT: Geodetic latitude of observer (IAU 1975, radians). + + \sstitem + OBSLON: Longitude of observer (radians - positive eastwards). + + \sstitem + EPOCH: \htmlref{Epoch}{Epoch} of observation (UT1 expressed as a Modified Julian Date). + + \sstitem + RA: Right Ascension of source (radians, FK5 J2000). + + \sstitem + DEC: Declination of source (radians, FK5 J2000). + + \sstitem + VOFF: Velocity of the user-defined reference frame, towards the + position given by RA and DEC, measured in the heliocentric + reference frame. + + } + If the SpecMap is 3-dimensional, source positions are provided by the + values supplied to inputs 2 and 3 of the SpecMap (which are simply + copied to outputs 2 and 3). Note, usable values are still required + for the RA and DEC arguments in order to define the \texttt{"} user-defined\texttt{"} + reference frame used by USF2HL and HLF2US. However, AST\_\_BAD can be + supplied for RA and DEC if the user-defined reference frame is not + required. + } +} +\sstroutine{ + astSpecFluxFrame +}{ + Create a SpecFluxFrame +}{ + \sstdescription{ + This function creates a new \htmlref{SpecFluxFrame}{SpecFluxFrame} and optionally initialises + its attributes. + + A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single + 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used + to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents + spectral position and the second axis represents flux. + } + \sstsynopsis{ + AstSpecFluxFrame $*$astSpecFluxFrame( AstSpecFrame $*$frame1, AstFluxFrame $*$frame2, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + frame1 + }{ + Pointer to the SpecFrame. This will form the first axis in the + new SpecFluxFrame. + } + \sstsubsection{ + frame2 + }{ + Pointer to the FluxFrame. This will form the second axis in the + new SpecFluxFrame. The \texttt{"} \htmlref{SpecVal}{SpecVal}\texttt{"} attribute of this FluxFrame is + not used by the SpecFluxFrame class and so may be set to AST\_\_BAD + when the FluxFrame is created. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SpecFluxFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSpecFluxFrame() + }{ + A pointer to the new SpecFluxFrame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The supplied Frame pointers are stored directly, rather than + being used to create deep copies of the supplied Frames. This means + that any subsequent changes made to the Frames via the supplied + pointers will result in equivalent changes being visible in the + SpecFluxFrame. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astSpecFrame +}{ + Create a SpecFrame +}{ + \sstdescription{ + This function creates a new \htmlref{SpecFrame}{SpecFrame} and optionally initialises + its attributes. + + A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various coordinate systems used to describe positions within + an electro-magnetic spectrum. The particular coordinate system to be + used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the + default is wavelength) qualified, as necessary, by other attributes + such as the rest frequency, the standard of rest, the epoch of + observation, etc (see the description of the System attribute for + details). + + By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made + to represent offsets from a given spectral position, rather than absolute + } + \sstsynopsis{ + AstSpecFrame $*$astSpecFrame( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SpecFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSpecFrame() + }{ + A pointer to the new SpecFrame. + } + } + \sstexamples{ + \sstexamplesubsection{ + frame = astSpecFrame( \texttt{"} \texttt{"} ); + }{ + Creates a SpecFrame to describe the default wavelength spectral + coordinate system. The \htmlref{RestFreq}{RestFreq} attribute (rest frequency) is + unspecified, so it will not be possible to align this SpecFrame + with another SpecFrame on the basis of a velocity-based system. The + standard of rest is also unspecified. This means that alignment + will be possible with other SpecFrames, but no correction will be + made for Doppler shift caused by change of rest frame during the + alignment. + } + \sstexamplesubsection{ + frame = astSpecFrame( \texttt{"} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{"} ); + }{ + Creates a SpecFrame describing a apparent radial velocity (\texttt{"} VELO\texttt{"} ) axis + with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured + in the kinematic Local Standard of Rest (\texttt{"} LSRK\texttt{"} ). Since the + source position has not been specified (using attributes \htmlref{RefRA}{RefRA} and + \htmlref{RefDec}{RefDec}), it will only be possible to align this SpecFrame with + other SpecFrames which are also measured in the LSRK standard of + rest. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When conversion between two SpecFrames is requested (as when + supplying SpecFrames to \htmlref{astConvert}{astConvert}), + account will be taken of the nature of the spectral coordinate systems + they represent, together with any qualifying rest frequency, standard + of rest, epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest} + attributes will also be taken into account. The results will therefore + fully reflect the relationship between positions measured in the two + systems. In addition, any difference in the Unit attributes of the two + systems will also be taken into account. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSpecMap +}{ + Create a SpecMap +}{ + \sstdescription{ + This function creates a new \htmlref{SpecMap}{SpecMap} and optionally initialises + its attributes. + + An SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to + represent a sequence of conversions between standard spectral + coordinate systems. This includes conversions between frequency, + wavelength, and various forms of velocity, as well as conversions + between different standards of rest. + + When a SpecMap is first created, it simply performs a unit + (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} function, + a series of coordinate conversion steps may then be added, selected + from the list of supported conversions. This allows multi-step + conversions between a variety of spectral coordinate systems to + be assembled out of the building blocks provided by this class. + + For details of the individual coordinate conversions available, + see the description of the astSpecAdd function. + + Conversions are available to transform between standards of rest. + Such conversions need to know the source position as an RA and DEC. + This information can be supplied in the form of parameters for + the relevant conversions, in which case the SpecMap is 1-dimensional, + simply transforming the spectral axis values. This means that the + same source position will always be used by the SpecMap. However, this + may not be appropriate for an accurate description of a 3-D spectral + cube, where changes of spatial position can produce significant + changes in the Doppler shift introduced when transforming between + standards of rest. For this situation, a 3-dimensional SpecMap can + be created in which axes 2 and 3 correspond to the source RA and DEC + The SpecMap simply copies values for axes 2 and 3 from input to + output). + } + \sstsynopsis{ + AstSpecMap $*$astSpecMap( int nin, int flags, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + nin + }{ + The number of inputs to the Mapping (this will also equal the + number of outputs). This value must be either 1 or 3. In either + case, the first input and output correspoindis the spectral axis. + For a 3-axis SpecMap, the second and third axes give the RA and + DEC (J2000 FK5) of the source. This positional information is + used by conversions which transform between standards of rest, + and replaces the \texttt{"} RA\texttt{"} and \texttt{"} DEC\texttt{"} arguments for the individual + conversions listed in description of the \texttt{"} SpecAdd\texttt{"} + function. + } + \sstsubsection{ + flags + }{ + This parameter is reserved for future use and should currently + always be set to zero. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SpecMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSpecMap() + }{ + A pointer to the new SpecMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The nature and units of the coordinate values supplied for the + first input (i.e. the spectral input) of a SpecMap must be appropriate + to the first conversion step applied by the SpecMap. For instance, if + the first conversion step is \texttt{"} FRTOVL\texttt{"} (frequency to relativistic + velocity), then the coordinate values for the first input should + be frequency in units of Hz. Similarly, the nature and units of the + coordinate values returned by a SpecMap will be determined by the + last conversion step applied by the SpecMap. For instance, if the + last conversion step is \texttt{"} VLTOVO\texttt{"} (relativistic velocity to optical + velocity), then the coordinate values for the first output will be optical + velocity in units of metres per second. See the description of the + astSpecAdd function for the units expected and returned by each + conversion. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astSphMap +}{ + Create a SphMap +}{ + \sstdescription{ + This function creates a new \htmlref{SphMap}{SphMap} and optionally initialises + its attributes. + + A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a + 3-dimensional Cartesian coordinate system into a 2-dimensional + spherical coordinate system (longitude and latitude on a unit + sphere centred at the origin). It works by regarding the input + coordinates as position vectors and finding their intersection + with the sphere surface. The inverse transformation always + produces points which are a unit distance from the origin + (i.e. unit vectors). + } + \sstsynopsis{ + AstSphMap $*$astSphMap( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SphMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSphMap() + }{ + A pointer to the new SphMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The spherical coordinates are longitude (positive + anti-clockwise looking from the positive latitude pole) and + latitude. The Cartesian coordinates are right-handed, with the x + axis (axis 1) at zero longitude and latitude, and the z axis + (axis 3) at the positive latitude pole. + + \sstitem + At either pole, the longitude is set to the value of the + \htmlref{PolarLong}{PolarLong} attribute. + + \sstitem + If the Cartesian coordinates are all zero, then the longitude + and latitude are set to the value AST\_\_BAD. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astStatus +}{ + Obtain the current AST error status value +}{ + \sstdescription{ + This function returns the current value of the AST error status. + } + \sstsynopsis{ + int astStatus + } + \sstreturnedvalue{ + \sstsubsection{ + astStatus + }{ + The AST error status value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the AST error status is set to an error value (after an + error), most AST functions will not execute and will simply + return without action. To clear the error status and restore + normal behaviour, use \htmlref{astClearStatus}{astClearStatus}. + } + } +} +\sstroutine{ + astStcCatalogEntryLocation +}{ + Create a StcCatalogEntryLocation +}{ + \sstdescription{ + This function creates a new \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} and optionally initialises its + attributes. + + The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of the datasets contained in some VO resource. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstsynopsis{ + AstStcCatalogEntryLocation $*$astStcCatalogEntryLocation( AstRegion $*$region, + int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region + }{ + Pointer to the encapsulated \htmlref{Region}{Region}. + } + \sstsubsection{ + ncoords + }{ + The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. + } + \sstsubsection{ + coords + }{ + Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} + is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} + describes the contents of a single STC $<$AstroCoords$>$ element, and + should have elements with keys given by constants AST\_\_STCNAME, + AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, + AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other + elements should be included. If supplied, the AST\_\_STCNAME element + should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} + item for each axis in the coordinate system represented by + \texttt{"} region\texttt{"} . + Any other supplied elements should be scalar elements, each holding + a pointer to a Region describing the associated item of ancillary + information (error, resolution, size, pixel size or value). These + Regions should describe a volume within the coordinate system + represented by \texttt{"} region\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new StcCatalogEntryLocation. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStcCatalogEntryLocation() + }{ + A pointer to the new StcCatalogEntryLocation. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A deep copy is taken of the supplied Region. This means that + any subsequent changes made to the encapsulated Region using the + supplied pointer will have no effect on the Stc. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astStcObsDataLocation +}{ + Create a StcObsDataLocation +}{ + \sstdescription{ + This function creates a new \htmlref{StcObsDataLocation}{StcObsDataLocation} and optionally initialises its + attributes. + + The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of the datasets contained in some VO resource. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstsynopsis{ + AstStcObsDataLocation $*$astStcObsDataLocation( AstRegion $*$region, + int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region + }{ + Pointer to the encapsulated \htmlref{Region}{Region}. + } + \sstsubsection{ + ncoords + }{ + The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. + } + \sstsubsection{ + coords + }{ + Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} + is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} + describes the contents of a single STC $<$AstroCoords$>$ element, and + should have elements with keys given by constants AST\_\_STCNAME, + AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, + AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other + elements should be included. If supplied, the AST\_\_STCNAME element + should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} + item for each axis in the coordinate system represented by + \texttt{"} region\texttt{"} . + Any other supplied elements should be scalar elements, each holding + a pointer to a Region describing the associated item of ancillary + information (error, resolution, size, pixel size or value). These + Regions should describe a volume within the coordinate system + represented by \texttt{"} region\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new StcObsDataLocation. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStcObsDataLocation() + }{ + A pointer to the new StcObsDataLocation. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A deep copy is taken of the supplied Region. This means that + any subsequent changes made to the encapsulated Region using the + supplied pointer will have no effect on the Stc. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astStcResourceProfile +}{ + Create a StcResourceProfile +}{ + \sstdescription{ + This function creates a new \htmlref{StcResourceProfile}{StcResourceProfile} and optionally initialises its + attributes. + + The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of the datasets contained in some VO resource. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstsynopsis{ + AstStcResourceProfile $*$astStcResourceProfile( AstRegion $*$region, + int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region + }{ + Pointer to the encapsulated \htmlref{Region}{Region}. + } + \sstsubsection{ + ncoords + }{ + The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. + } + \sstsubsection{ + coords + }{ + Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} + is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} + describes the contents of a single STC $<$AstroCoords$>$ element, and + should have elements with keys given by constants AST\_\_STCNAME, + AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, + AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other + elements should be included. If supplied, the AST\_\_STCNAME element + should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} + item for each axis in the coordinate system represented by + \texttt{"} region\texttt{"} . + Any other supplied elements should be scalar elements, each holding + a pointer to a Region describing the associated item of ancillary + information (error, resolution, size, pixel size or value). These + Regions should describe a volume within the coordinate system + represented by \texttt{"} region\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new StcResourceProfile. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStcResourceProfile() + }{ + A pointer to the new StcResourceProfile. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A deep copy is taken of the supplied Region. This means that + any subsequent changes made to the encapsulated Region using the + supplied pointer will have no effect on the Stc. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astStcSearchLocation +}{ + Create a StcSearchLocation +}{ + \sstdescription{ + This function creates a new \htmlref{StcSearchLocation}{StcSearchLocation} and optionally initialises its + attributes. + + The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of a VO query. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstsynopsis{ + AstStcResourceProfile $*$astStcSearchLocation( AstRegion $*$region, + int ncoords, AstKeyMap $*$coords[], const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + region + }{ + Pointer to the encapsulated \htmlref{Region}{Region}. + } + \sstsubsection{ + ncoords + }{ + The length of the \texttt{"} coords\texttt{"} array. Supply zero if \texttt{"} coords\texttt{"} is NULL. + } + \sstsubsection{ + coords + }{ + Pointer to an array holding \texttt{"} ncoords\texttt{"} AstKeyMap pointers (if \texttt{"} ncoords\texttt{"} + is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap} + describes the contents of a single STC $<$AstroCoords$>$ element, and + should have elements with keys given by constants AST\_\_STCNAME, + AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE, + AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other + elements should be included. If supplied, the AST\_\_STCNAME element + should be a vector of character string pointers holding the \texttt{"} Name\texttt{"} + item for each axis in the coordinate system represented by + \texttt{"} region\texttt{"} . + Any other supplied elements should be scalar elements, each holding + a pointer to a Region describing the associated item of ancillary + information (error, resolution, size, pixel size or value). These + Regions should describe a volume within the coordinate system + represented by \texttt{"} region\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new StcSearchLocation. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStcSearchLocation() + }{ + A pointer to the new StcSearchLocation. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A deep copy is taken of the supplied Region. This means that + any subsequent changes made to the encapsulated Region using the + supplied pointer will have no effect on the Stc. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astStcsChan +}{ + Create an StcsChan +}{ + \sstdescription{ + This function creates a new \htmlref{StcsChan}{StcsChan} and optionally initialises + its attributes. + + A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S + I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an + STC-S description of that Object, and reading from an StcsChan will + create a new Object from its STC-S description. + + Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting text. These functions + should perform any conversions needed between external character + encodings and the internal ASCII encoding. If no such functions + are supplied, a Channel will read from standard input and write + to standard output. + + Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + } + \sstsynopsis{ + AstStcsChan $*$astStcsChan( const char $*$($*$ source)( void ), + void ($*$ sink)( const char $*$ ), + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + source + }{ + Pointer to a source function that takes no arguments and + returns a pointer to a null-terminated string. If no value + has been set for the SourceFile attribute, this function + will be used by the StcsChan to obtain lines of input text. On + each invocation, it should return a pointer to the next input + line read from some external data store, and a NULL pointer + when there are no more lines to read. + + If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile + attribute, the StcsChan will read from standard input instead. + } + \sstsubsection{ + sink + }{ + Pointer to a sink function that takes a pointer to a + null-terminated string as an argument and returns void. + If no value has been set for the SinkFile attribute, this + function will be used by the StcsChan to deliver lines of + output text. On each invocation, it should deliver the + contents of the string supplied to some external data store. + + If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile + attribute, the StcsChan will write to standard output instead. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new StcsChan. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStcsChan() + }{ + A pointer to the new StcsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the external data source or sink uses a character encoding + other than ASCII, the supplied source and sink functions should + translate between the external character encoding and the internal + ASCII encoding used by AST. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astStripEscapes +}{ + Remove AST escape sequences from a string +}{ + \sstdescription{ + This function removes AST escape sequences from a supplied string, + returning the resulting text as the function value. The behaviour + of this function can be controlled by invoking the + \htmlref{astEscapes}{astEscapes} function, + which can be used to supress or enable the removal of escape + sequences by this function. + + AST escape sequences are used by the \htmlref{Plot}{Plot} class to modify the + appearance and position of sub-strings within a plotted text string. + See the \texttt{"} \htmlref{Escape}{Escape}\texttt{"} attribute for further information. + } + \sstsynopsis{ + const char $*$astStripEscapes( const char $*$text ) + } + \sstparameters{ + \sstsubsection{ + text + }{ + Pointer to the string to be checked. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStripEscapes() + }{ + Pointer to the modified string. If no escape sequences were found + in the supplied string, then a copy of the supplied pointer is + returned. Otherwise, the pointer will point to a static buffer + holding the modified text. This text will be over-written by + subsequent invocations of this function. If the astEscapes function + has been called indicating that escape sequences should not be + stripped, then the supplied string is returned without change. + } + } +} +\sstroutine{ + astSwitchMap +}{ + Create a SwitchMap +}{ + \sstdescription{ + This function creates a new \htmlref{SwitchMap}{SwitchMap} and optionally initialises + its attributes. + + A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate + Mappings, each of which is used to transform positions within a + particular region of the input or output coordinate system of the + SwitchMap. + + A SwitchMap can encapsulate any number of Mappings, but they must + all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the + same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself + inherits these same values for its Nin and Nout attributes. Each of + these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are + referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms + positions between the input and output coordinate space of the entire + SwitchMap, but only one Mapping will be used to transform any given + position. The selection of the appropriate route Mapping to use with + any given input position is made by another Mapping, called the + \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector + Mappings in addition to its route Mappings; one for use with the + SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector + Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation + (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping + must have the same number of inputs as the route Mappings, but + should have only one output. Likewise, the inverse selector Mapping + must have the same number of outputs as the route Mappings, but + should have only one input. + + When the SwitchMap is used to transform a position in the forward + direction (from input to output), each supplied input position is + first transformed by the forward transformation of the forward selector + Mapping. This produces a single output value for each input position + referred to as the selector value. The nearest integer to the selector + value is found, and is used to index the array of route Mappings (the + first supplied route Mapping has index 1, the second route Mapping has + index 2, etc). If the nearest integer to the selector value is less + than 1 or greater than the number of route Mappings, then the SwitchMap + output position is set to a value of AST\_\_BAD on every axis. Otherwise, + the forward transformation of the selected route Mapping is used to + transform the supplied input position to produce the SwitchMap output + position. + + When the SwitchMap is used to transform a position in the inverse + direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position + is first transformed by the inverse transformation of the inverse + selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} + position. Again, the nearest integer to the selector value is found, + and is used to index the array of route Mappings. If this selector + index value is within the bounds of the array of route Mappings, then + the inverse transformation of the selected route Mapping is used to + transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap + \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds + of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is + set to a value of AST\_\_BAD on every axis. + + In practice, appropriate selector Mappings should be chosen to + associate a different route Mapping with each region of coordinate + space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly + appropriate for this purpose. + + If a compound Mapping contains a SwitchMap in series with its own + inverse, the combination of the two adjacent SwitchMaps will be + replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using + \htmlref{astSimplify}{astSimplify}. + } + \sstsynopsis{ + AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap, + int nroute, AstMapping $*$routemaps[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + fsmap + }{ + Pointer to the forward selector Mapping. This must have a + defined forward transformation, but need not have a defined + inverse transformation. It must have one output, and the number of + inputs must match the number of inputs of each of the supplied + route Mappings. + NULL + may be supplied, in which case the SwitchMap will have an undefined + forward Mapping. + } + \sstsubsection{ + ismap + }{ + Pointer to the inverse selector Mapping. This must have a + defined inverse transformation, but need not have a defined + forward transformation. It must have one input, and the number of + outputs must match the number of outputs of each of the supplied + route Mappings. + NULL + may be supplied, in which case the SwitchMap will have an undefined + inverse Mapping. + } + \sstsubsection{ + nroute + }{ + The number of supplied route Mappings. + } + \sstsubsection{ + routemaps + }{ + An array of pointers to the route Mappings. All the supplied + route Mappings must have common values for the Nin and Nout + attributes, and these values define the number of inputs and + outputs of the SwitchMap. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new SwitchMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSwitchMap() + }{ + A pointer to the new SwitchMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Note that the component Mappings supplied are not copied by + astSwitchMap (the new SwitchMap simply retains a reference to + them). They may continue to be used for other purposes, but + should not be deleted. If a SwitchMap containing a copy of its + component Mappings is required, then a copy of the SwitchMap should + be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astTable +}{ + Create a Table +}{ + \sstdescription{ + This function creates a new empty \htmlref{Table}{Table} and optionally initialises + its attributes. + + The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional + table of values. The + astMapGet... and astMapPut... + methods provided by the KeyMap class should be used for storing and + retrieving values from individual cells within a Table. Each entry + in the KeyMap represents a single cell of the table and has an + associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the name of a + table column and \texttt{"} i\texttt{"} is the row index (the first row is row 1). Keys + of this form should always be used when using KeyMap methods to access + entries within a Table. + + Columns must be declared using the + \htmlref{astAddColumn}{astAddColumn} + method before values can be stored within them. This also fixes the + type and shape of the values that may be stored in any cell of the + column. Cells may contain scalar or vector values of any data type + supported by the KeyMap class. Multi-dimensional arrays may also be + stored, but these must be vectorised when storing and retrieving + them within a table cell. All cells within a single column must + have the same type and shape (specified when the column is declared). + + Tables may have parameters that describe global properties of the + entire table. These are stored as entries in the parent KeyMap and + can be access using the get and set method of the KeyMap class. + However, parameters must be declared using the + \htmlref{astAddParameter}{astAddParameter} + method before being accessed. + + Note - since accessing entries within a KeyMap is a relatively slow + process, it is not recommended to use the Table class to store + very large tables. + } + \sstsynopsis{ + AstTable $*$astTable( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new Table. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTable() + }{ + A pointer to the new Table. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list described above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astTableSource +}{ + Register a source function for accessing tables in FITS files +}{ + \sstdescription{ + This function can be used to register a call-back function + with a \htmlref{FitsChan}{FitsChan}. The registered + function + is called when-ever the FitsChan needs to read information from a + binary table contained within a FITS file. This occurs if the + \htmlref{astRead}{astRead} + function is invoked to read a \htmlref{FrameSet}{FrameSet} from a set of FITS headers + that use the \texttt{"} -TAB\texttt{"} algorithm to describe one or more axes. Such + axes use a FITS binary table to store a look-up table of axis values. + The FitsChan will fail to read such axes unless the \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"} attribute + is set to a non-zero positive integer value. The table containing the + axis values must be made available to the FitsChan either by storing + the table contents in the FitsChan (using + \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) prior to invoking astRead + or by registering a call-back + function using astTableSource. + The first method is possibly simpler, but requires that the name of + the extension containing the table be known in advance. Since the + table name is embedded in the FITS headers, the name is often not + known in advance. If a call-back is registered, the FitsChan will + determine the name of the required table and invoke the call-back + function + to supply the table at the point where it is needed (i.e. within + the astRead method). + } + \sstsynopsis{ + void astTableSource( AstFitsChan $*$this, + void ($*$ tabsource)( AstFitsChan $*$, const char $*$, + int, int, int $*$ ) ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + tabsource + }{ + Pointer to the table source function to use. + It takes five arguments - the first is a pointer to the + FitsChan, the second is a string holding the name of the + FITS extension containing the required binary table (\texttt{"} EXTNAME\texttt{"} ), + the third is the integer FITS \texttt{"} EXTVER\texttt{"} header value for the + required extension, the fourth is the integer FITS \texttt{"} EXTLEVEL\texttt{"} + header value for the required extension, and the fifth is + a pointer to + the inherited integer status value. + + The call-back should read the entire contents (header and data) + of the binary table in the named extension of the external FITS + file, storing the contents in a newly created \htmlref{FitsTable}{FitsTable} object. It + should then store this FitsTable in the FitsChan using the + astPutTables or astPutTable + method, and finally annull its local copy of the FitsTable pointer. + If the table cannot be read for any reason, or if any other + error occurs, it should return a non-zero integer for the final + (third) argument. + + If \texttt{"} tabsource\texttt{"} is NULL, + any registered call-back function will be removed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Application code can pass arbitrary data (such as file + descriptors, etc) to the table source function using the + \htmlref{astPutChannelData}{astPutChannelData} function. The source function should use + the \htmlref{astChannelData}{astChannelData} macro to retrieve this data. + } + } +} +\sstroutine{ + astTest +}{ + Test if an Object attribute value is set +}{ + \sstdescription{ + This function returns a boolean result (0 or 1) to indicate + whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s + attributes. + } + \sstsynopsis{ + int astTest( AstObject $*$this, const char $*$attrib ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object. + } + \sstsubsection{ + attrib + }{ + Pointer to a null-terminated character string containing + the name of the attribute to be tested. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTest() + }{ + One if a value has previously been explicitly set for the attribute + (and hasn\texttt{'} t been cleared), otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Attribute names are not case sensitive and may be surrounded + by white space. + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any reason. + + \sstitem + A value of zero will also be returned if this function is used + to test a read-only attribute, although no error will result. + } + } +} +\sstroutine{ + astTestFits +}{ + See if a named keyword has a defined value in a FitsChan +}{ + \sstdescription{ + This function serches for a named keyword in a \htmlref{FitsChan}{FitsChan}. If found, + and if the keyword has a value associated with it, a + non-zero + value is returned. If the keyword is not found, or if it does not + have an associated value, a + zero + value is returned. + } + \sstsynopsis{ + int astTestFits( AstFitsChan $*$this, const char $*$name, int $*$there ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + \sstsubsection{ + name + }{ + Pointer to a null-terminated character string + containing the FITS keyword name. This may be a complete FITS + header card, in which case the keyword to use is extracted from + it. No more than 80 characters are read from this string. + } + \sstsubsection{ + there + }{ + Pointer to an integer which will be returned holding a non-zero + value if the keyword was found in the header, and zero otherwise. + This parameter allows a distinction to be made between the case + where a keyword is not present, and the case where a keyword is + present but has no associated value. + A NULL pointer may be supplied if this information is not + required. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTestFits() + }{ + A value of zero + is returned if the keyword was not found in the FitsChan or has + no associated value. Otherwise, a value of + one + is returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The current card is left unchanged by this function. + + \sstitem + The card following the current card is checked first. If this is + not the required card, then the rest of the FitsChan is searched, + starting with the first card added to the FitsChan. Therefore cards + should be accessed in the order they are stored in the FitsChan (if + possible) as this will minimise the time spent searching for cards. + + \sstitem + An error will be reported if the keyword name does not conform + to FITS requirements. + + \sstitem + Zero + is returned as the function value if an error has already occurred, + or if this function should fail for any reason. + } + } +} +\sstroutine{ + astText +}{ + Draw a text string for a Plot +}{ + \sstdescription{ + This function draws a string of text at a position specified in + the physical coordinate system of a \htmlref{Plot}{Plot}. The physical position + is transformed into graphical coordinates to determine where the + text should appear within the plotting area. + } + \sstsynopsis{ + void astText( AstPlot $*$this, const char $*$text, const double pos[], + const float up[], const char $*$just ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Plot. + } + \sstsubsection{ + text + }{ + Pointer to a null-terminated character string containing the + text to be drawn. Trailing white space is ignored. + } + \sstsubsection{ + pos + }{ + An array, with one element for each axis of the Plot, giving + the physical coordinates of the point where the reference + position of the text string is to be placed. + } + \sstsubsection{ + up + }{ + An array holding the components of a vector in the \texttt{"} up\texttt{"} + direction of the text (in graphical coordinates). For + example, to get horizontal text, the vector \{0.0f,1.0f\} should + be supplied. For a basic Plot, 2 values should be supplied. For + a \htmlref{Plot3D}{Plot3D}, 3 values should be supplied, and the actual up vector + used is the projection of the supplied up vector onto the text plane + specified by the current value of the Plot3D\texttt{'} s Norm attribute. + } + \sstsubsection{ + just + }{ + Pointer to a null-terminated character string identifying the + reference point for the text being drawn. The first character in + this string identifies the reference position in the \texttt{"} up\texttt{"} direction + and may be \texttt{"} B\texttt{"} (baseline), \texttt{"} C\texttt{"} (centre), \texttt{"} T\texttt{"} (top) or \texttt{"} M\texttt{"} (bottom). + The second character identifies the side-to-side reference position + and may be \texttt{"} L\texttt{"} (left), \texttt{"} C\texttt{"} (centre) or \texttt{"} R\texttt{"} (right ). The string is + case-insensitive, and only the first two characters are significant. + + For example, a value of \texttt{"} BL\texttt{"} means that the left end of the + baseline of the original (un-rotated) text is to be drawn at the + position given by \texttt{"} pos\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Plot3D class currently does not interpret graphical escape + sequences contained within text displayed using this method. + + \sstitem + Text is not drawn at positions which have any coordinate equal + to the value AST\_\_BAD (or where the transformation into + graphical coordinates yields coordinates containing the value + AST\_\_BAD). + + \sstitem + If the plotting position is clipped (see \htmlref{astClip}{astClip}), then no + text is drawn. + + \sstitem + An error results if the base \htmlref{Frame}{Frame} of the Plot is not + 2-dimensional or (for a Plot3D) 3-dimensional. + + \sstitem + An error also results if the transformation between the + current and base Frames of the Plot is not defined (i.e. the + Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero). + } + } +} +\sstroutine{ + astThread +}{ + Determine the thread that owns an Object +}{ + \sstdescription{ + Returns an integer that indicates whether the supplied \htmlref{Object}{Object} (or + Object pointer) is currently unlocked, or is currently locked by + the running thread, or another thread. + } + \sstsynopsis{ + int astThread( AstObject $*$this, int ptr ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be checked. + } + \sstsubsection{ + ptr + }{ + If non-zero, returns information about the supplied Object + pointer, rather than the Object structure itself. See \texttt{"} Object + Pointers and Structures\texttt{"} below. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astThread() + }{ + A value of AST\_\_UNLOCKED is returned if the Object (or pointer) + is currently unlocked (i.e. has been unlocked using \htmlref{astUnlock}{astUnlock} + but has not yet been locked using \htmlref{astLock}{astLock}). A value of + AST\_\_RUNNING is returned if the Object (or pointer) is currently + locked by the running thread. A value of AST\_\_OTHER is returned + if the Object (or pointer) is currently locked by the another + thread. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function attempts to execute even if the global error + status is set, but no further error report will be made if it + subsequently fails under these circumstances. + + \sstitem + This function is only available in the C interface. + + \sstitem + This function always returns AST\_\_RUNNING if the AST library has + been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} + option was not specified when running the \texttt{"} configure\texttt{"} script). + } + } + \sstdiytopic{ + Object Pointers and Structures + }{ + At any one time, an AST Object can have several distinct pointers, + any one of which can be used to access the Object structure. For + instance, the \htmlref{astClone}{astClone} function will produce a new distinct pointer + for a given Object. In fact, an AST \texttt{"} pointer\texttt{"} is not a real pointer + at all - it is an identifier for a \texttt{"} handle\texttt{"} structure, encoded to + make it look like a pointer. Each handle contains (amongst othere + things) a \texttt{"} real\texttt{"} pointer to the Object structure. This allows more + than one handle to refer to the same Object structure. So when you + call astClone (for instance) you get back an identifier for a new + handle that refers to the same Object as the supplied handle. + + In order to use an Object for anything useful, it must be locked + for use by the running thread (either implicitly at creation or + explicitly using astLock). The identity of the thread is stored in + both the Object structure, and in the handle that was passed to + astLock (or returned by the constructor function). Thus it is + possible for a thread to have active pointers for Objects that are + currently locked by another thread. In general, if such a pointer is + passed to an AST function an error will be reported indicating that + the Object is currently locked by another thread. The two exceptions + to this is that \htmlref{astAnnul}{astAnnul} can be used to annull such a pointer, and + this function can be used to return information about the pointer. + + The other practical consequence of this is that when \htmlref{astEnd}{astEnd} is + called, all active pointers currently owned by the running thread + (at the current context level) are annulled. This includes pointers + for Objects that are currently locked by other threads. + + If the \texttt{"} ptr\texttt{"} parameter is zero, then the returned value describes + the Object structure itself. If \texttt{"} ptr\texttt{"} is non-zero, then the returned + value describes the supplied Object pointer (i.e. handle), rather + than the Object structure. + } +} +\sstroutine{ + astTimeAdd +}{ + Add a time coordinate conversion to a TimeMap +}{ + \sstdescription{ + This function adds one of the standard time coordinate + system conversions listed below to an existing \htmlref{TimeMap}{TimeMap}. + + When a TimeMap is first created (using \htmlref{astTimeMap}{astTimeMap}), it simply + performs a unit (null) \htmlref{Mapping}{Mapping}. By using astTimeAdd (repeatedly + if necessary), one or more coordinate conversion steps may then + be added, which the TimeMap will perform in sequence. This allows + multi-step conversions between a variety of time coordinate + systems to be assembled out of the building blocks provided by + this class. + + Normally, if a TimeMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default), + then its forward transformation is performed by carrying out + each of the individual coordinate conversions specified by + astTimeAdd in the order given (i.e. with the most recently added + conversion applied last). + + This order is reversed if the TimeMap\texttt{'} s Invert attribute is + non-zero (or if the inverse transformation is requested by any + other means) and each individual coordinate conversion is also + replaced by its own inverse. This process inverts the overall + effect of the TimeMap. In this case, the first conversion to be + applied would be the inverse of the one most recently added. + } + \sstsynopsis{ + void astTimeAdd( AstTimeMap $*$this, const char $*$cvt, const double args[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the TimeMap. + } + \sstsubsection{ + cvt + }{ + Pointer to a null-terminated string which identifies the + time coordinate conversion to be added to the + TimeMap. See the \texttt{"} Available Conversions\texttt{"} section for details of + those available. + } + \sstsubsection{ + args + }{ + An array containing argument values for the time + coordinate conversion. The number of arguments required, and + hence the number of array elements used, depends on the + conversion specified (see the \texttt{"} Available Conversions\texttt{"} + section). This array is ignored + and a NULL pointer may be supplied + if no arguments are needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When assembling a multi-stage conversion, it can sometimes be + difficult to determine the most economical conversion path. A solution + to this is to include all the steps which are (logically) necessary, + but then to use + \htmlref{astSimplify}{astSimplify} to simplify the resulting + TimeMap. The simplification process will eliminate any steps + which turn out not to be needed. + + \sstitem + This function does not check to ensure that the sequence of + coordinate conversions added to a TimeMap is physically + meaningful. + } + } + \sstdiytopic{ + Available Conversions + }{ + The following strings (which are case-insensitive) may be supplied + via the \texttt{"} cvt\texttt{"} parameter to indicate which time coordinate + conversion is to be added to the TimeMap. Where arguments are needed by + the conversion, they are listed in parentheses. Values for + these arguments should be given, via the \texttt{"} args\texttt{"} array, in the + order indicated. Units and argument names are described at the end of + the list of conversions, and \texttt{"} MJD\texttt{"} means Modified Julian Date. + + \sstitemlist{ + + \sstitem + \texttt{"} MJDTOMJD\texttt{"} (MJDOFF1,MJDOFF2): Convert MJD from one offset to another. + + \sstitem + \texttt{"} MJDTOJD\texttt{"} (MJDOFF,JDOFF): Convert MJD to Julian Date. + + \sstitem + \texttt{"} JDTOMJD\texttt{"} (JDOFF,MJDOFF): Convert Julian Date to MJD. + + \sstitem + \texttt{"} MJDTOBEP\texttt{"} (MJDOFF,BEPOFF): Convert MJD to Besselian epoch. + + \sstitem + \texttt{"} BEPTOMJD\texttt{"} (BEPOFF,MJDOFF): Convert Besselian epoch to MJD. + + \sstitem + \texttt{"} MJDTOJEP\texttt{"} (MJDOFF,JEPOFF): Convert MJD to Julian epoch. + + \sstitem + \texttt{"} JEPTOMJD\texttt{"} (JEPOFF,MJDOFF): Convert Julian epoch to MJD. + + \sstitem + \texttt{"} TAITOUTC\texttt{"} (MJDOFF): Convert a TAI MJD to a UTC MJD. + + \sstitem + \texttt{"} UTCTOTAI\texttt{"} (MJDOFF): Convert a UTC MJD to a TAI MJD. + + \sstitem + \texttt{"} TAITOTT\texttt{"} (MJDOFF): Convert a TAI MJD to a TT MJD. + + \sstitem + \texttt{"} TTTOTAI\texttt{"} (MJDOFF): Convert a TT MJD to a TAI MJD. + + \sstitem + \texttt{"} TTTOTDB\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD. + + \sstitem + \texttt{"} TDBTOTT\texttt{"} (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD. + + \sstitem + \texttt{"} TTTOTCG\texttt{"} (MJDOFF): Convert a TT MJD to a TCG MJD. + + \sstitem + \texttt{"} TCGTOTT\texttt{"} (MJDOFF): Convert a TCG MJD to a TT MJD. + + \sstitem + \texttt{"} TDBTOTCB\texttt{"} (MJDOFF): Convert a TDB MJD to a TCB MJD. + + \sstitem + \texttt{"} TCBTOTDB\texttt{"} (MJDOFF): Convert a TCB MJD to a TDB MJD. + + \sstitem + \texttt{"} UTTOGMST\texttt{"} (MJDOFF): Convert a UT MJD to a GMST MJD. + + \sstitem + \texttt{"} GMSTTOUT\texttt{"} (MJDOFF): Convert a GMST MJD to a UT MJD. + + \sstitem + \texttt{"} GMSTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. + + \sstitem + \texttt{"} LMSTTOGMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. + + \sstitem + \texttt{"} LASTTOLMST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD. + + \sstitem + \texttt{"} LMSTTOLAST\texttt{"} (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD. + + \sstitem + \texttt{"} UTTOUTC\texttt{"} (DUT1): Convert a UT1 MJD to a UTC MJD. + + \sstitem + \texttt{"} UTCTOUT\texttt{"} (DUT1): Convert a UTC MJD to a UT1 MJD. + + \sstitem + \texttt{"} LTTOUTC\texttt{"} (LTOFF): Convert a Local Time MJD to a UTC MJD. + + \sstitem + \texttt{"} UTCTOLT\texttt{"} (LTOFF): Convert a UTC MJD to a Local Time MJD. + + } + The units for the values processed by the above conversions are as + follows: + + \sstitemlist{ + + \sstitem + Julian epochs and offsets: Julian years + + \sstitem + Besselian epochs and offsets: Tropical years + + \sstitem + Modified Julian Dates and offsets: days + + \sstitem + Julian Dates and offsets: days + + } + The arguments used in the above conversions are the zero-points + used by the + astTransform function. + The axis values supplied and returned by + astTransform + are offsets away from these zero-points: + + \sstitemlist{ + + \sstitem + MJDOFF: The zero-point being used with MJD values. + + \sstitem + JDOFF: The zero-point being used with Julian Date values. + + \sstitem + BEPOFF: The zero-point being used with Besselian epoch values. + + \sstitem + JEPOFF: The zero-point being used with Julian epoch values. + + \sstitem + OBSLON: Observer longitude in radians ($+$ve westwards). + + \sstitem + OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards). + + \sstitem + OBSALT: Observer geodetic altitude (IAU 1975) in metres. + + \sstitem + DUT1: The UT1-UTC value to use. + + \sstitem + LTOFF: The offset between Local Time and UTC (in hours, positive + for time zones east of Greenwich). + } + } +} +\sstroutine{ + astTimeFrame +}{ + Create a TimeFrame +}{ + \sstdescription{ + This function creates a new \htmlref{TimeFrame}{TimeFrame} and optionally initialises + its attributes. + + A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various coordinate systems used to describe positions in + time. + + A TimeFrame represents a moment in time as either an Modified Julian + Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, + as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be + specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame + representing time offsets from the specified zero point. + + Even though JD and MJD are defined as being in units of days, the + TimeFrame class allows other units to be used (via the Unit attribute) + on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 + hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs + can be described in units other than the usual years. Besselian epoch + are always represented in units of (tropical) years. + + The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that + is, the physical proces used to define the rate of flow of time). + MJD, JD and Julian epoch can be used to represent a time in any + supported time scale. However, Besselian epoch may only be used with the + \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales + includes universal time and siderial time. Strictly, these represent + angles rather than time scales, but are included in the list since + they are in common use and are often thought of as time scales. + + When a time value is formatted it can be formated either as a simple + floating point value, or as a Gregorian date (see the Format + attribute). + } + \sstsynopsis{ + AstTimeFrame $*$astTimeFrame( const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new TimeFrame. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTimeFrame() + }{ + A pointer to the new TimeFrame. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When conversion between two TimeFrames is requested (as when + supplying TimeFrames to \htmlref{astConvert}{astConvert}), + account will be taken of the nature of the time coordinate systems + they represent, together with any qualifying time scale, offset, + unit, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignTimeScale}{AlignTimeScale} attributes will also be + taken into account. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astTimeMap +}{ + Create a TimeMap +}{ + \sstdescription{ + This function creates a new \htmlref{TimeMap}{TimeMap} and optionally initialises + its attributes. + + A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be + used to represent a sequence of conversions between standard time + coordinate systems. + + When a TimeMap is first created, it simply performs a unit + (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd} + function, a series of coordinate conversion steps may then be + added. This allows multi-step conversions between a variety of + time coordinate systems to be assembled out of a set of building + blocks. + + For details of the individual coordinate conversions available, + see the description of the astTimeAdd function. + } + \sstsynopsis{ + AstTimeMap $*$astTimeMap( int flags, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + flags + }{ + This parameter is reserved for future use and should currently + always be set to zero. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new TimeMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + If no initialisation is required, a zero-length string may be + supplied. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTimeMap() + }{ + A pointer to the new TimeMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The nature and units of the coordinate values supplied for the + first input (i.e. the time input) of a TimeMap must be appropriate + to the first conversion step applied by the TimeMap. For instance, if + the first conversion step is \texttt{"} MJDTOBEP\texttt{"} (Modified Julian Date to + Besselian epoch) then the coordinate values for the first input should + be date in units of days. Similarly, the nature and units of the + coordinate values returned by a TimeMap will be determined by the + last conversion step applied by the TimeMap. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astToString +}{ + Create an in-memory serialisation of an Object +}{ + \sstdescription{ + This function returns a string holding a minimal textual + serialisation of the supplied AST \htmlref{Object}{Object}. The Object can re + re-created from the serialisation using \htmlref{astFromString}{astFromString}. + } + \sstsynopsis{ + char $*$astToString( AstObject $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be serialised. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astToString() + }{ + Pointer to dynamically allocated memory holding the + serialisation, or NULL if an error occurs. The pointer + should be freed when no longer needed using \htmlref{astFree}{astFree}. + } + } +} +\sstroutine{ + astTran1 +}{ + Transform 1-dimensional coordinates +}{ + \sstdescription{ + This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of + a set of points in one dimension. + } + \sstsynopsis{ + void astTran1( AstMapping $*$this, int npoint, const double xin[], + int forward, double xout[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + npoint + }{ + The number of points to be transformed. + } + \sstsubsection{ + xin + }{ + An array of \texttt{"} npoint\texttt{"} coordinate values for the input + (untransformed) points. + } + \sstsubsection{ + forward + }{ + A non-zero value indicates that the Mapping\texttt{'} s forward + coordinate transformation is to be applied, while a zero + value indicates that the inverse transformation should be + used. + } + \sstsubsection{ + xout + }{ + An array (with \texttt{"} npoint\texttt{"} elements) into which the + coordinates of the output (transformed) points will be written. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin} + and \htmlref{Nout}{Nout} attributes. + } + } +} +\sstroutine{ + astTran2 +}{ + Transform 2-dimensional coordinates +}{ + \sstdescription{ + This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of + a set of points in two dimensions. + } + \sstsynopsis{ + void astTran2( AstMapping $*$this, + int npoint, const double xin[], const double yin[], + int forward, double xout[], double yout[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + npoint + }{ + The number of points to be transformed. + } + \sstsubsection{ + xin + }{ + An array of \texttt{"} npoint\texttt{"} X-coordinate values for the input + (untransformed) points. + } + \sstsubsection{ + yin + }{ + An array of \texttt{"} npoint\texttt{"} Y-coordinate values for the input + (untransformed) points. + } + \sstsubsection{ + forward + }{ + A non-zero value indicates that the Mapping\texttt{'} s forward + coordinate transformation is to be applied, while a zero + value indicates that the inverse transformation should be + used. + } + \sstsubsection{ + xout + }{ + An array (with \texttt{"} npoint\texttt{"} elements) into which the + X-coordinates of the output (transformed) points will be written. + } + \sstsubsection{ + yout + }{ + An array (with \texttt{"} npoint\texttt{"} elements) into which the + Y-coordinates of the output (transformed) points will be written. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin} + and \htmlref{Nout}{Nout} attributes. + } + } +} +\sstroutine{ + astTranGrid +}{ + Transform a grid of positions +}{ + \sstdescription{ + This function uses the supplied \htmlref{Mapping}{Mapping} to transforms a regular square + grid of points covering a specified box. It attempts to do this + quickly by first approximating the Mapping with a linear transformation + applied over the whole region of the input grid which is being used. + If this proves to be insufficiently accurate, the input region is + sub-divided into two along its largest dimension and the process is + repeated within each of the resulting sub-regions. This process of + sub-division continues until a sufficiently good linear approximation + is found, or the region to which it is being applied becomes too small + (in which case the original Mapping is used directly). + } + \sstsynopsis{ + void astTranGrid( AstMapping $*$this, int ncoord\_in, + const int lbnd[], const int ubnd[], + double tol, int maxpix, int forward, + int ncoord\_out, int outdim, double $*$out ); + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + ncoord\_in + }{ + The number of coordinates being supplied for each box corner + (i.e. the number of dimensions of the space in which the + input points reside). + } + \sstsubsection{ + lbnd + }{ + Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd + }{ + Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\texttt{"} and \texttt{"} ubnd\texttt{"} together define the shape + and size of the input grid, its extent along a particular + (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the + index \texttt{"} j\texttt{"} to be zero-based). They also define + the input grid\texttt{'} s coordinate system, each pixel having unit + extent along each dimension with integral coordinate values + at its centre. + } + \sstsubsection{ + tol + }{ + The maximum tolerable geometrical distortion which may be + introduced as a result of approximating non-linear Mappings + by a set of piece-wise linear transformations. This should be + expressed as a displacement within the output coordinate system + of the Mapping. + + If piece-wise linear approximation is not required, a value + of zero may be given. This will ensure that the Mapping is + used without any approximation, but may increase execution + time. + + If the value is too high, discontinuities between the linear + approximations used in adjacent panel will be higher. If this + is a problem, reduce the tolerance value used. + } + \sstsubsection{ + maxpix + }{ + A value which specifies an initial scale size (in input grid points) + for the adaptive algorithm which approximates non-linear Mappings + with piece-wise linear transformations. Normally, this should + be a large value (larger than any dimension of the region of + the input grid being used). In this case, a first attempt to + approximate the Mapping by a linear transformation will be + made over the entire input region. + + If a smaller value is used, the input region will first be + divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"} + grid points in any dimension. Only at this point will attempts + at approximation commence. + + This value may occasionally be useful in preventing false + convergence of the adaptive algorithm in cases where the + Mapping appears approximately linear on large scales, but has + irregularities (e.g. holes) on smaller scales. A value of, + say, 50 to 100 grid points can also be employed as a safeguard + in general-purpose software, since the effect on performance is + minimal. + + If too small a value is given, it will have the effect of + inhibiting linear approximation altogether (equivalent to + setting \texttt{"} tol\texttt{"} to zero). Although this may degrade + performance, accurate results will still be obtained. + } + \sstsubsection{ + forward + }{ + A non-zero value indicates that the Mapping\texttt{'} s forward + coordinate transformation is to be applied, while a zero + value indicates that the inverse transformation should be + used. + } + \sstsubsection{ + ncoord\_out + }{ + The number of coordinates being generated by the Mapping for + each output point (i.e. the number of dimensions of the + space in which the output points reside). This need not be + the same as \texttt{"} ncoord\_in\texttt{"} . + } + \sstsubsection{ + outdim + }{ + The number of elements along the second dimension of the \texttt{"} out\texttt{"} + array (which will contain the output coordinates). The value + given should not be less than the number of points in the grid. + } + \sstsubsection{ + out + }{ + The address of the first element in a 2-dimensional array of + shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into + which the coordinates of the output (transformed) points will + be written. These will be stored such that the value of + coordinate number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} + will be found in element \texttt{"} out[coord][point]\texttt{"} . + The points are ordered such that the first axis of the input + grid changes most rapidly. For example, if the input grid is + 2-dimensional and extends from (2,-1) to (3,1), the output + points will be stored in the order (2,-1), (3, -1), (2,0), (3,0), + (2,1), (3,1). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the forward coordinate transformation is being applied, the + Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} + attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} attribute. If + the inverse transformation is being applied, these values should + be reversed. + } + } +} +\sstroutine{ + astTranMap +}{ + Create a TranMap +}{ + \sstdescription{ + This function creates a new \htmlref{TranMap}{TranMap} and optionally initialises + its attributes. + + A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of + a supplied Mapping with the inverse transformation of another + supplied Mapping, ignoring the un-used transformation in each + Mapping (indeed the un-used transformation need not exist). + + When the forward transformation of the TranMap is referred to, the + transformation actually used is the forward transformation of the + first Mapping supplied when the TranMap was constructed. Likewise, + when the inverse transformation of the TranMap is referred to, the + transformation actually used is the inverse transformation of the + second Mapping supplied when the TranMap was constructed. + } + \sstsynopsis{ + AstTranMap $*$astTranMap( AstMapping $*$map1, AstMapping $*$map2, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + map1 + }{ + Pointer to the first component Mapping, which defines the + forward transformation. + } + \sstsubsection{ + map2 + }{ + Pointer to the second component Mapping, which defines the + inverse transformation. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new TranMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTranMap() + }{ + A pointer to the new TranMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The number of output coordinates generated by the two Mappings + (their \htmlref{Nout}{Nout} attribute) must be equal, as must the number of input + coordinates accepted by each Mapping (their \htmlref{Nin}{Nin} attribute). + + \sstitem + The forward transformation of the first Mapping must exist. + + \sstitem + The inverse transformation of the second Mapping must exist. + + \sstitem + Note that the component Mappings supplied are not copied by + astTranMap (the new TranMap simply retains a reference to + them). They may continue to be used for other purposes, but + should not be deleted. If a TranMap containing a copy of its + component Mappings is required, then a copy of the TranMap should + be made using \htmlref{astCopy}{astCopy}. + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astTranN +}{ + Transform N-dimensional coordinates +}{ + \sstdescription{ + This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of + a set of points in an arbitrary number of dimensions. It is the + appropriate routine to use if the coordinates are not purely 1- + or 2-dimensional and are stored in a single array (which they + need not fill completely). + + If the coordinates are not stored in a single array, then the + \htmlref{astTranP}{astTranP} function might be more suitable. + } + \sstsynopsis{ + void astTranN( AstMapping $*$this, int npoint, + int ncoord\_in, int indim, const double $*$in, + int forward, + int ncoord\_out, int outdim, double $*$out ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + npoint + }{ + The number of points to be transformed. + } + \sstsubsection{ + ncoord\_in + }{ + The number of coordinates being supplied for each input point + (i.e. the number of dimensions of the space in which the + input points reside). + } + \sstsubsection{ + indim + }{ + The number of elements along the second dimension of the \texttt{"} in\texttt{"} + array (which contains the input coordinates). This value is + required so that the coordinate values can be correctly + located if they do not entirely fill this array. The value + given should not be less than \texttt{"} npoint\texttt{"} . + } + \sstsubsection{ + in + }{ + The address of the first element in a 2-dimensional array of + shape \texttt{"} [ncoord\_in][indim]\texttt{"} , + containing the coordinates of the input (untransformed) + points. These should be stored such that the value of + coordinate number \texttt{"} coord\texttt{"} for input point number \texttt{"} point\texttt{"} is + found in element \texttt{"} in[coord][point]\texttt{"} . + } + \sstsubsection{ + forward + }{ + A non-zero value indicates that the Mapping\texttt{'} s forward + coordinate transformation is to be applied, while a zero + value indicates that the inverse transformation should be + used. + } + \sstsubsection{ + ncoord\_out + }{ + The number of coordinates being generated by the Mapping for + each output point (i.e. the number of dimensions of the + space in which the output points reside). This need not be + the same as \texttt{"} ncoord\_in\texttt{"} . + } + \sstsubsection{ + outdim + }{ + The number of elements along the second dimension of the \texttt{"} out\texttt{"} + array (which will contain the output coordinates). This value + is required so that the coordinate values can be correctly + located if they will not entirely fill this array. The value + given should not be less than \texttt{"} npoint\texttt{"} . + } + \sstsubsection{ + out + }{ + The address of the first element in a 2-dimensional array of + shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into + which the coordinates of the output (transformed) points will + be written. These will be stored such that the value of + coordinate number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} + will be found in element \texttt{"} out[coord][point]\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the forward coordinate transformation is being applied, the + Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} + attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} attribute. If + the inverse transformation is being applied, these values should + be reversed. + } + } +} +\sstroutine{ + astTranP +}{ + Transform N-dimensional coordinates held in separate arrays +}{ + \sstdescription{ + This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of + a set of points in an arbitrary number of dimensions. It is the + appropriate routine to use if the coordinates are not purely 1- + or 2-dimensional and are stored in separate arrays, since each + coordinate array is located by supplying a separate pointer to + it. + + If the coordinates are stored in a single (2-dimensional) array, + then the \htmlref{astTranN}{astTranN} function might be more suitable. + } + \sstsynopsis{ + void astTranP( AstMapping $*$this, int npoint, + int ncoord\_in, const double $*$ptr\_in[], + int forward, int ncoord\_out, double $*$ptr\_out[] ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Mapping to be applied. + } + \sstsubsection{ + npoint + }{ + The number of points to be transformed. + } + \sstsubsection{ + ncoord\_in + }{ + The number of coordinates being supplied for each input point + (i.e. the number of dimensions of the space in which the + input points reside). + } + \sstsubsection{ + ptr\_in + }{ + An array of pointers to double, with \texttt{"} ncoord\_in\texttt{"} + elements. Element \texttt{"} ptr\_in[coord]\texttt{"} should point at the first + element of an array of double (with \texttt{"} npoint\texttt{"} elements) which + contain the values of coordinate number \texttt{"} coord\texttt{"} for each + input (untransformed) point. The value of coordinate number + \texttt{"} coord\texttt{"} for input point number \texttt{"} point\texttt{"} is therefore given by + \texttt{"} ptr\_in[coord][point]\texttt{"} (assuming both indices are + zero-based). + } + \sstsubsection{ + forward + }{ + A non-zero value indicates that the Mapping\texttt{'} s forward + coordinate transformation is to be applied, while a zero + value indicates that the inverse transformation should be + used. + } + \sstsubsection{ + ncoord\_out + }{ + The number of coordinates being generated by the Mapping for + each output point (i.e. the number of dimensions of the space + in which the output points reside). This need not be the same + as \texttt{"} ncoord\_in\texttt{"} . + } + \sstsubsection{ + ptr\_out + }{ + An array of pointers to double, with \texttt{"} ncoord\_out\texttt{"} + elements. Element \texttt{"} ptr\_out[coord]\texttt{"} should point at the first + element of an array of double (with \texttt{"} npoint\texttt{"} elements) into + which the values of coordinate number \texttt{"} coord\texttt{"} for each output + (transformed) point will be written. The value of coordinate + number \texttt{"} coord\texttt{"} for output point number \texttt{"} point\texttt{"} will therefore + be found in \texttt{"} ptr\_out[coord][point]\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the forward coordinate transformation is being applied, the + Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"} for its \htmlref{Nin}{Nin} + attribute and the value of \texttt{"} ncoord\_out\texttt{"} for its \htmlref{Nout}{Nout} + attribute. If the inverse transformation is being applied, these + values should be reversed. + + \sstitem + This routine is not available in the Fortran 77 interface to + the AST library. + } + } +} +\sstroutine{ + astTune +}{ + Set or get an integer-valued AST global tuning parameter +}{ + \sstdescription{ + This function returns the current value of an integer-valued AST + global tuning parameter, optionally storing a new value for the + parameter. For character-valued tuning parameters, see + \htmlref{astTuneC}{astTuneC}. + } + \sstsynopsis{ + int astTune( const char $*$name, int value ) + } + \sstparameters{ + \sstsubsection{ + name + }{ + The name of the tuning parameter (case-insensitive). + } + \sstsubsection{ + value + }{ + The new value for the tuning parameter. If this is AST\_\_TUNULL, + the existing current value will be retained. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astTune() + }{ + The original value of the tuning parameter. A default value will + be returned if no value has been set for the parameter. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function attempts to execute even if the AST error + status is set + on entry, although no further error report will be + made if it subsequently fails under these circumstances. + + \sstitem + All threads in a process share the same AST tuning parameters + values. + } + } + \sstdiylist{ + Tuning Parameters + }{ + \sstsubsection{ + ObjectCaching + }{ + A boolean flag which indicates what should happen + to the memory occupied by an AST \htmlref{Object}{Object} when the Object is deleted + (i.e. when its reference count falls to zero or it is deleted using + \htmlref{astDelete}{astDelete}). + If this is zero, the memory is simply freed using the systems \texttt{"} free\texttt{"} + function. If it is non-zero, the memory is not freed. Instead a + pointer to it is stored in a pool of such pointers, all of which + refer to allocated but currently unused blocks of memory. This allows + AST to speed up subsequent Object creation by re-using previously + allocated memory blocks rather than allocating new memory using the + systems malloc function. The default value for this parameter is + zero. Setting it to a non-zero value will result in Object memory + being cached in future. Setting it back to zero causes any memory + blocks currently in the pool to be freed. Note, this tuning parameter + only controls the caching of memory used to store AST Objects. To + cache other memory blocks allocated by AST, use MemoryCaching. + } + \sstsubsection{ + MemoryCaching + }{ + A boolean flag similar to ObjectCaching except + that it controls caching of all memory blocks of less than 300 bytes + allocated by AST (whether for internal or external use), not just + memory used to store AST Objects. + } + } +} +\sstroutine{ + astTuneC +}{ + Set or get a character-valued AST global tuning parameter +}{ + \sstdescription{ + This function returns the current value of a character-valued + AST global tuning parameter, optionally storing a new value + for the parameter. For integer-valued tuning parameters, see + \htmlref{astTune}{astTune}. + } + \sstsynopsis{ + void astTuneC( const char $*$name, const char $*$value, char $*$buff, + int bufflen ) + } + \sstparameters{ + \sstsubsection{ + name + }{ + The name of the tuning parameter (case-insensitive). + } + \sstsubsection{ + value + }{ + The new value for the tuning parameter. If this is + NULL, + the existing current value will be retained. + } + \sstsubsection{ + buff + }{ + A character string in which to return the original value of + the tuning parameter. An error will be reported if the buffer + is too small to hold the value. + NULL may be supplied if the old value is not required. + } + \sstsubsection{ + bufflen + }{ + The size of the supplied \texttt{"} buff\texttt{"} array. Ignored if \texttt{"} buff\texttt{"} is NULL. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function attempts to execute even if the AST error + status is set + on entry, although no further error report will be + made if it subsequently fails under these circumstances. + + \sstitem + All threads in a process share the same AST tuning parameters + values. + } + } + \sstdiylist{ + Tuning Parameters + }{ + \sstsubsection{ + HRDel + }{ + A string to be drawn following the hours field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use (see the Format + attribute). This string may include escape sequences to produce + super-scripts, etc. (see the Escapes attribute for details + of the escape sequences allowed). The default value is + \texttt{"} \%-\%$\wedge$50$+$\%s70$+$h\%$+$\texttt{"} which produces a super-script \texttt{"} h\texttt{"} . + } + \sstsubsection{ + MNDel + }{ + A string to be drawn following the minutes field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is + \texttt{"} \%-\%$\wedge$50$+$\%s70$+$m\%$+$\texttt{"} which produces a super-script \texttt{"} m\texttt{"} . + } + \sstsubsection{ + SCDel + }{ + A string to be drawn following the seconds field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is + \texttt{"} \%-\%$\wedge$50$+$\%s70$+$s\%$+$\texttt{"} which produces a super-script \texttt{"} s\texttt{"} . + } + \sstsubsection{ + DGDel + }{ + A string to be drawn following the degrees field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is + \texttt{"} \%-\%$\wedge$53$+$\%s60$+$o\%$+$\texttt{"} which produces a super-script \texttt{"} o\texttt{"} . + } + \sstsubsection{ + AMDel + }{ + A string to be drawn following the arc-minutes field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is + \texttt{"} \%-\%$\wedge$20$+$\%s85$+$\texttt{'} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{'} \texttt{"} (single quote). + } + \sstsubsection{ + ASDel + }{ + A string to be drawn following the arc-seconds field in a formatted + sky axis value when \texttt{"} g\texttt{"} format is in use. The default value is + \texttt{"} \%-\%$\wedge$20$+$\%s85$+$$\backslash$\texttt{"} \%$+$\texttt{"} which produces a super-script \texttt{"} \texttt{"} \texttt{"} (double quote). + } + \sstsubsection{ + EXDel + }{ + A string to be drawn to introduce the exponent in a value when \texttt{"} g\texttt{"} + format is in use. The default value is \texttt{"} 10\%-\%$\wedge$50$+$\%s70$+$\texttt{"} which + produces \texttt{"} 10\texttt{"} followed by the exponent as a super-script. + } + } +} +\sstroutine{ + astUinterp +}{ + Perform sub-pixel interpolation on a grid of data +}{ + \sstdescription{ + This is a fictitious function which does not actually + exist. Instead, this description constitutes a template so that + you may implement a function with this interface for yourself + (and give it any name you wish). A pointer to such a function + may be passed via the \texttt{"} finterp\texttt{"} parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$} + functions (q.v.) in order to perform sub-pixel interpolation + during resampling of gridded data (you must also set the + \texttt{"} interp\texttt{"} parameter of astResample$<$X$>$ to the value + AST\_\_UINTERP). This allows you to use your own interpolation + algorithm in addition to those which are pre-defined. + + The function interpolates an input grid of data (and, + optionally, processes associated statistical variance estimates) + at a specified set of points. + } + \sstsynopsis{ + void astUinterp( int ndim\_in, const int lbnd\_in[], const int ubnd\_in[], + const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[], + int npoint, const int offset[], + const double $*$const coords[], const double params[], + int flags, $<$Xtype$>$ badval, + $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], int $*$nbad ) + } + \sstparameters{ + \sstsubsection{ + ndim\_in + }{ + The number of dimensions in the input grid. This will be at + least one. + } + \sstsubsection{ + lbnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the first pixel + in the input grid along each dimension. + } + \sstsubsection{ + ubnd\_in + }{ + Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"} elements, + containing the coordinates of the centre of the last pixel in + the input grid along each dimension. + + Note that \texttt{"} lbnd\_in\texttt{"} and \texttt{"} ubnd\_in\texttt{"} together define the shape, + size and coordinate system of the input grid in the same + way as they do in astResample$<$X$>$. + } + \sstsubsection{ + in + }{ + Pointer to an array, with one element for each pixel in the + input grid, containing the input data. This will be the same + array as was passed to astResample$<$X$>$ via the \texttt{"} in\texttt{"} parameter. + The numerical type of this array should match that of the + data being processed. + } + \sstsubsection{ + in\_var + }{ + Pointer to an optional second array with the same size and + type as the \texttt{"} in\texttt{"} array. If given, this will contain the set + of variance values associated with the input data and will be + the same array as was passed to astResample$<$X$>$ via the + \texttt{"} in\_var\texttt{"} parameter. + + If no variance values are being processed, this will be a + NULL pointer. + } + \sstsubsection{ + npoint + }{ + The number of points at which the input grid is to be + interpolated. This will be at least one. + } + \sstsubsection{ + offset + }{ + Pointer to an array of integers with \texttt{"} npoint\texttt{"} elements. For + each interpolation point, this will contain the zero-based + index in the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s) at which the + interpolated value (and its variance, if required) should be + stored. For example, the interpolated value for point number + \texttt{"} point\texttt{"} should be stored in \texttt{"} out[offset[point]]\texttt{"} (assuming + the index \texttt{"} point\texttt{"} is zero-based). + } + \sstsubsection{ + coords + }{ + An array of pointers to double, with \texttt{"} ndim\_in\texttt{"} + elements. Element \texttt{"} coords[coord]\texttt{"} will point at the first + element of an array of double (with \texttt{"} npoint\texttt{"} elements) which + contains the values of coordinate number \texttt{"} coord\texttt{"} for each + interpolation point. The value of coordinate number \texttt{"} coord\texttt{"} + for interpolation point number \texttt{"} point\texttt{"} is therefore given by + \texttt{"} coords[coord][point]\texttt{"} (assuming both indices are + zero-based). + + If any interpolation point has any of its coordinates equal + to the value AST\_\_BAD (as defined in the \texttt{"} ast.h\texttt{"} header + file), then the corresponding output data (and variance) + should either be set to the value given by \texttt{"} badval\texttt{"} , + or left unchanged, depending on whether the AST\_\_NOBAD flag is + specified by \texttt{"} flags\texttt{"} . + } + \sstsubsection{ + params + }{ + This will be a pointer to the same array as was given via the + \texttt{"} params\texttt{"} parameter of astResample$<$X$>$. You may use this to + pass any additional parameter values required by your + interpolation algorithm. + } + \sstsubsection{ + flags + }{ + This will be the same value as was given via the \texttt{"} flags\texttt{"} + parameter of astResample$<$X$>$. You may test this value to + provide additional control over the operation of your + resampling algorithm. Note that the special flag values + AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your + own purposes and will not clash with other pre-defined flag + values (see astResample$<$X$>$). + } + \sstsubsection{ + badval + }{ + This will be the same value as was given via the \texttt{"} badval\texttt{"} + parameter of astResample$<$X$>$, and will have the same numerical + type as the data being processed (i.e. as elements of the + \texttt{"} in\texttt{"} array). It should be used to test for bad pixels in the + input grid (but only if the AST\_\_USEBAD flag is set via the + \texttt{"} flags\texttt{"} parameter) and (unless the AST\_\_NOBAD flag is set in + \texttt{"} flags\texttt{"} ) for identifying bad output values in + the \texttt{"} out\texttt{"} (and \texttt{"} out\_var\texttt{"} ) array(s). + } + \sstsubsection{ + out + }{ + Pointer to an array with the same numerical type as the \texttt{"} in\texttt{"} + array, into which the interpolated data values should be + returned. Note that details of the storage order and number + of dimensions of this array are not required, since the + \texttt{"} offset\texttt{"} array contains all necessary information about where + each returned value should be stored. + + In general, not all elements of this array (or the \texttt{"} out\_var\texttt{"} + array below) may be used in any particular invocation of the + function. Those which are not used should be returned + unchanged. + } + \sstsubsection{ + out\_var + }{ + Pointer to an optional array with the same type and size as + the \texttt{"} out\texttt{"} array, into which variance estimates for the + resampled values should be returned. This array will only be + given if the \texttt{"} in\_var\texttt{"} array has also been given. + + If given, it is addressed in exactly the same way (via the + \texttt{"} offset\texttt{"} array) as the \texttt{"} out\texttt{"} array. The values returned + should be estimates of the statistical variance of the + corresponding values in the \texttt{"} out\texttt{"} array, on the assumption + that all errors in input data values are statistically + independent and that their variance estimates may simply be + summed (with appropriate weighting factors). + + If no output variance estimates are required, a NULL pointer + will be given. + } + \sstsubsection{ + nbad + }{ + Pointer to an int in which to return the number of interpolation + points at + which no valid interpolated value could be obtained. The maximum + value that should be returned is \texttt{"} npoint\texttt{"} , and the minimum is + zero (indicating that all output values were successfully + obtained). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The data type $<$Xtype$>$ indicates the numerical type of the data + being processed, as for astResample$<$X$>$. + + \sstitem + This function will typically be invoked more than once for each + invocation of astResample$<$X$>$. + + \sstitem + If an error occurs within this function, it should use + \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value. + This will cause an immediate return from astResample$<$X$>$. The error + value AST\_\_UINER is available for this purpose, but other values may + also be used (e.g. if you wish to distinguish different types of + error). + } + } +} +\sstroutine{ + astUkern1 +}{ + 1-dimensional sub-pixel interpolation kernel +}{ + \sstdescription{ + This is a fictitious function which does not actually + exist. Instead, this description constitutes a template so that + you may implement a function with this interface for yourself + (and give it any name you wish). A pointer to such a function + may be passed via the \texttt{"} finterp\texttt{"} parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$} + functions (q.v.) in order to supply a 1-dimensional + interpolation kernel to the algorithm which performs sub-pixel + interpolation during resampling of gridded data (you must also + set the \texttt{"} interp\texttt{"} parameter of astResample$<$X$>$ to the value + AST\_\_UKERN1). This allows you to use your own interpolation + kernel in addition to those which are pre-defined. + + The function calculates the value of a 1-dimensional sub-pixel + interpolation kernel. This determines how the weight given to + neighbouring pixels in calculating an interpolated value depends + on the pixel\texttt{'} s offset from the interpolation point. In more than + one dimension, the weight assigned to a pixel is formed by + evaluating this 1-dimensional kernel using the offset along each + dimension in turn. The product of the returned values is then + used as the pixel weight. + } + \sstsynopsis{ + void astUkern1( double offset, const double params[], int flags, + double $*$value ) + } + \sstparameters{ + \sstsubsection{ + offset + }{ + This will be the offset of the pixel from the interpolation + point, measured in pixels. This value may be positive or + negative, but for most practical interpolation schemes its + sign should be ignored. + } + \sstsubsection{ + params + }{ + This will be a pointer to the same array as was given via the + \texttt{"} params\texttt{"} parameter of astResample$<$X$>$. You may use this to + pass any additional parameter values required by your kernel, + but note that \texttt{"} params[0]\texttt{"} will already have been used to specify + the number of neighbouring pixels which contribute to the + interpolated value. + } + \sstsubsection{ + flags + }{ + This will be the same value as was given via the \texttt{"} flags\texttt{"} + parameter of astResample$<$X$>$. You may test this value to + provide additional control over the operation of your + function. Note that the special flag values AST\_\_URESAMP1, 2, + 3 \& 4 are reserved for you to use for your own purposes and + will not clash with other pre-defined flag + values (see astResample$<$X$>$). + } + \sstsubsection{ + value + }{ + Pointer to a double to receive the calculated kernel value, + which may be positive or negative. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Not all functions make good interpolation kernels. In general, + acceptable kernels tend to be symmetrical about zero, to have a + positive peak (usually unity) at zero, and to evaluate to zero + whenever the pixel offset has any other integral value (this + ensures that the interpolated values pass through the original + data). An interpolation kernel may or may not have regions with + negative values. You should consult a good book on image + processing for more details. + + \sstitem + If an error occurs within this function, it should use + \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value. + This will cause an immediate return from astResample$<$X$>$. The error + value AST\_\_UK1ER is available for this purpose, but other values may + also be used (e.g. if you wish to distinguish different types of + error). + } + } +} +\sstroutine{ + astUnformat +}{ + Read a formatted coordinate value for a Frame axis +}{ + \sstdescription{ + This function reads a formatted coordinate value (given as a + character string) for a \htmlref{Frame}{Frame} axis and returns the equivalent + numerical (double) value. It also returns the number of + characters read from the string. + + The principle use of this function is in decoding user-supplied + input which contains formatted coordinate values. Free-format + input is supported as far as possible. If input is ambiguous, it + is interpreted with reference to the Frame\texttt{'} s attributes (in + particular, the Format string associated with the Frame\texttt{'} s + axis). This function is, in essence, the inverse of \htmlref{astFormat}{astFormat}. + } + \sstsynopsis{ + int astUnformat( AstFrame $*$this, int axis, const char $*$string, + double $*$value ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Frame. + } + \sstsubsection{ + axis + }{ + The number of the Frame axis for which a coordinate value is to + be read (axis numbering starts at 1 for the first axis). + } + \sstsubsection{ + string + }{ + Pointer to a null-terminated character string containing the + formatted coordinate value. + This string may contain additional information following the + value to be read, in which case reading stops at the first + character which cannot be interpreted as part of the value. + Any white space before or after the value is discarded. + } + \sstsubsection{ + value + }{ + Pointer to a double in which the coordinate value read will be + returned. + } + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + This function applies to all Frames. See the \texttt{"} Frame Input + Format\texttt{"} section below for details of the input formats + accepted by a basic Frame. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the input format to be suitable + for representing angles and times, with the resulting + coordinate value returned in radians. See the \texttt{"} SkyFrame + Input Format\texttt{"} section below for details of the formats + accepted. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The input formats accepted by a FrameSet are determined by + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astUnformat() + }{ + The number of characters read from the string in order to + obtain the coordinate value. This will include any white + space which occurs before or after the value. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A function value of zero (and no coordinate value) will be + returned, without error, if the string supplied does not contain + a suitably formatted value. + + \sstitem + Beware that it is possible for a formatting error part-way + through an input string to terminate input before it has been + completely read, but to yield a coordinate value that appears + valid. For example, if a user types \texttt{"} 1.5r6\texttt{"} instead of \texttt{"} 1.5e6\texttt{"} , + the \texttt{"} r\texttt{"} will terminate input, giving an incorrect coordinate + value of 1.5. It is therefore most important to check the return + value of this function to ensure that the correct number of + characters have been read. + + \sstitem + An error will result if a value is read which appears to have + the correct format, but which cannot be converted into a valid + coordinate value (for instance, because the value of one or more + of its fields is invalid). + + \sstitem + The string \texttt{"} $<$bad$>$\texttt{"} is recognised as a special case and will + yield the coordinate value AST\_\_BAD without error. The test for + this string is case-insensitive and also permits embedded white + space. + + \sstitem + A function result of zero will be returned and no coordinate + value will be returned via the \texttt{"} value\texttt{"} pointer if this function + is invoked with the AST error status set, or if it should fail + for any reason. + } + } + \sstdiytopic{ + Frame Input Format + }{ + The input format accepted for a basic Frame axis is as follows: + \sstitemlist{ + + \sstitem + An optional sign, followed by: + + \sstitem + A sequence of one or more digits possibly containing a decimal point, + followed by: + + \sstitem + An optional exponent field. + + \sstitem + The exponent field, if present, consists of \texttt{"} E\texttt{"} or \texttt{"} e\texttt{"} + followed by a possibly signed integer. + + } + Examples of acceptable Frame input formats include: + \sstitemlist{ + + \sstitem + 99 + + \sstitem + 1.25 + + \sstitem + -1.6 + + \sstitem + 1E8 + + \sstitem + -.99e-17 + + \sstitem + $<$bad$>$ + } + } + \sstdiytopic{ + SkyFrame Input Format + }{ + The input format accepted for a SkyFrame axis is as follows: + \sstitemlist{ + + \sstitem + An optional sign, followed by between one and three fields + representing either degrees, arc-minutes, arc-seconds or hours, + minutes, seconds (e.g. \texttt{"} -12 42 03\texttt{"} ). + + \sstitem + Each field should consist of a sequence of one or more digits, + which may include leading zeros. At most one field may contain a + decimal point, in which case it is taken to be the final field + (e.g. decimal degrees might be given as \texttt{"} 124.707\texttt{"} , while degrees + and decimal arc-minutes might be given as \texttt{"} -13 33.8\texttt{"} ). + + \sstitem + The first field given may take any value, allowing angles and + times outside the conventional ranges to be + represented. However, subsequent fields must have values of less + than 60 (e.g. \texttt{"} 720 45 31\texttt{"} is valid, whereas \texttt{"} 11 45 61\texttt{"} is not). + + \sstitem + Fields may be separated by white space or by \texttt{"} :\texttt{"} (colon), but + the choice of separator must be used consistently throughout the + value. Additional white space may be present around fields and + separators (e.g. \texttt{"} - 2: 04 : 7.1\texttt{"} ). + + \sstitem + The following field identification characters may be used as + separators to replace either of those above (or may be appended + to the final field), in order to identify the field to which + they are appended: \texttt{"} d\texttt{"} ---degrees; \texttt{"} h\texttt{"} ---hours; \texttt{"} m\texttt{"} ---minutes of + arc or time; \texttt{"} s\texttt{"} ---seconds of arc or time; \texttt{"} \texttt{'} \texttt{"} (single + quote)---minutes of arc; \texttt{"} \texttt{"} \texttt{"} (double quote)---seconds of arc. + Either lower or upper case may be used. Fields must be given in + order of decreasing significance (e.g. \texttt{"} -11D 3\texttt{'} 14.4\texttt{"} \texttt{"} or + \texttt{"} 22h14m11.2s\texttt{"} ). + + \sstitem + The presence of any of the field identification characters + \texttt{"} d\texttt{"} , \texttt{"} \texttt{'} \texttt{"} (single quote) or \texttt{"} \texttt{"} \texttt{"} (double quote) indicates that the + value is to be interpreted as an angle. Conversely, the presence + of \texttt{"} h\texttt{"} indicates that it is to be interpreted as a time (with 24 + hours corresponding to 360 degrees). Incompatible angle/time + identification characters may not be mixed (e.g. \texttt{"} 10h14\texttt{'} 3\texttt{"} \texttt{"} is + not valid). The remaining field identification characters and + separators do not specify a preference for an angle or a time + and may be used with either. + + \sstitem + If no preference for an angle or a time is expressed anywhere + within the value, it is interpreted as an angle if the Format + attribute string associated with the SkyFrame axis generates an + angle and as a time otherwise. This ensures that values produced + by astFormat are correctly interpreted by astUnformat. + + \sstitem + Fields may be omitted, in which case they default to zero. The + remaining fields may be identified by using appropriate field + identification characters (see above) and/or by adding extra + colon separators (e.g. \texttt{"} -05m13s\texttt{"} is equivalent to \texttt{"} -:05:13\texttt{"} ). If + a field is not identified explicitly, it is assumed that + adjacent fields have been given, after taking account of any + extra separator characters (e.g. \texttt{"} 14:25.4s\texttt{"} specifies minutes + and seconds, while \texttt{"} 14::25.4s\texttt{"} specifies degrees and seconds). + + \sstitem + If fields are omitted in such a way that the remaining ones + cannot be identified uniquely (e.g. \texttt{"} 01:02\texttt{"} ), then the first + field (either given explicitly or implied by an extra leading + colon separator) is taken to be the most significant field that + astFormat would produce when formatting a value (using the + Format attribute associated with the SkyFrame axis). By + default, this means that the first field will normally be + interpreted as degrees or hours. However, if this does not + result in consistent field identification, then the last field + (either given explicitly or implied by an extra trailing colon + separator) is taken to to be the least significant field that + astFormat would produce. + + } + This final convention is intended to ensure that values formatted + by astFormat which contain less than three fields will be + correctly interpreted if read back using astUnformat, even if + they do not contain field identification characters. + + Examples of acceptable SkyFrame input formats (with + interpretation in parentheses) include: + \sstitemlist{ + + \sstitem + -14d 13m 22.2s (-14d 13\texttt{'} 22.2\texttt{"} ) + + \sstitem + $+$ 12:34:56.7 (12d 34\texttt{'} 56.7\texttt{"} or 12h 34m 56.7s) + + \sstitem + 001 : 02 : 03.4 (1d 02\texttt{'} 03.4\texttt{"} or 1h 02m 03.4s) + + \sstitem + 22h 30 (22h 30m 00s) + + \sstitem + 136::10\texttt{"} (136d 00\texttt{'} 10\texttt{"} or 136h 00m 10s) + + \sstitem + -14M 27S (-0d 14\texttt{'} 27\texttt{"} or -0h 14m 27s) + + \sstitem + -:14: (-0d 14\texttt{'} 00\texttt{"} or -0h 14m 00s) + + \sstitem + -::4.1 (-0d 00\texttt{'} 04.1\texttt{"} or -0h 00m 04.1s) + + \sstitem + .9\texttt{"} (0d 00\texttt{'} 00.9\texttt{"} ) + + \sstitem + d12m (0d 12\texttt{'} 00\texttt{"} ) + + \sstitem + H 12:22.3s (0h 12m 22.3s) + + \sstitem + $<$bad$>$ (AST\_\_BAD) + + } + Where alternative interpretations are shown, the choice of angle or + time depends on the associated \htmlref{Format(axis)}{Format(axis)} attribute. + } +} +\sstroutine{ + astUnitMap +}{ + Create a UnitMap +}{ + \sstdescription{ + This function creates a new \htmlref{UnitMap}{UnitMap} and optionally initialises + its attributes. + + A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the + coordinates supplied to it. They are simply copied. This can be + useful if a Mapping is required (e.g. to pass to another + function) but you do not want it to have any effect. + } + \sstsynopsis{ + AstUnitMap $*$astUnitMap( int ncoord, const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of input and output coordinates (these numbers are + necessarily the same). + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new UnitMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astUnitMap() + }{ + A pointer to the new UnitMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astUnitNormMap +}{ + Create a UnitNormMap +}{ + \sstdescription{ + This function creates a new \htmlref{UnitNormMap}{UnitNormMap} and optionally initialises its + attributes. + + The forward transformation of a UnitNormMap subtracts the specified centre + and then transforms the resulting vector to a unit vector and the vector norm. + The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs + are in the same order as the input; the final output is the norm. + + The inverse transformation of a UnitNormMap multiplies each component + of the provided vector by the provided norm and adds the specified centre. + The output contains one fewer coordinate than the input: the initial Nin inputs + are in the same order as the output; the final input is the norm. + + UnitNormMap enables radially symmetric transformations, as follows: + \sstitemlist{ + + \sstitem + apply a UnitNormMap to produce a unit vector and norm (radius) + + \sstitem + apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged + + \sstitem + apply the same UnitNormMap in the inverse direction to produce the result + } + } + \sstsynopsis{ + AstUnitNormMap $*$astUnitNormMap( int ncoord, const double centre[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of coordinate values for each point to be + transformed (i.e. the number of dimensions of the space in + which the points will reside). Output will include one additional coordinate. + } + \sstsubsection{ + centre + }{ + An array containing the values to be subtracted from the input + coordinates before computing unit vector and norm. A separate + value must be supplied for each coordinate. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new UnitNormMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astUnitNormMap() + }{ + A pointer to the new UnitNormMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astUnlock +}{ + Unlock an Object for use by other threads +}{ + \sstdescription{ + Unlocks an \htmlref{Object}{Object} previously locked using \htmlref{astLock}{astLock}, so that other + threads can use the Object. See astLock for further details. + } + \sstsynopsis{ + void astUnlock( AstObject $*$this, int report ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Object to be unlocked. + } + \sstsubsection{ + report + }{ + If non-zero, an error will be reported if the supplied Object, + or any Object contained within the supplied Object, is not + currently locked by the running thread. If zero, such Objects + will be left unchanged, and no error will be reported. + } + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + This function applies to all Objects. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function attempts to execute even if the global error + status is set, but no further error report will be made if it + subsequently fails under these circumstances. + + \sstitem + All unlocked Objects are excluded from AST context handling until + they are re-locked using astLock. + + \sstitem + This function is only available in the C interface. + + \sstitem + This function returns without action if the Object is not currently + locked by any thread. If it is locked by the running thread, it is + unlocked. If it is locked by another thread, an error will be reported + if \texttt{"} error\texttt{"} is non-zero. + + \sstitem + This function returns without action if the AST library has + been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"} + option was not specified when running the \texttt{"} configure\texttt{"} script). + } + } +} +\sstroutine{ + astVersion +}{ + Return the version of the AST library being used +}{ + \sstdescription{ + This macro invokes a function which + returns an integer representing the version of the AST library + being used. The library version is formatted as a string such as + \texttt{"} 2.0-7\texttt{"} which contains integers representing the \texttt{"} major version\texttt{"} (2), + the \texttt{"} minor version\texttt{"} (0) and the \texttt{"} release\texttt{"} (7). The integer returned + by this function combines all three integers together into a single + integer using the expresion: + + (major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release) + } + \sstsynopsis{ + int astVersion + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Object}{Object} + }{ + This macro applies to all Objects. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astVersion + }{ + The major version, minor version and release numbers for the AST + library, encoded as a single integer. + } + } +} +\sstroutine{ + astWarnings +}{ + Returns any warnings issued by the previous read or write operation +}{ + \sstdescription{ + This function returns an AST \htmlref{KeyMap}{KeyMap} object holding the text of any + warnings issued as a result of the previous invocation of the + \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} + function on the \htmlref{Channel}{Channel}. If no warnings were issued, a + a NULL value + will be returned. + + Such warnings are non-fatal and will not prevent the + read or write operation succeeding. However, the converted object + may not be identical to the original object in all respects. + Differences which would usually be deemed as insignificant in most + usual cases will generate a warning, whereas more significant + differences will generate an error. + + The \texttt{"} \htmlref{Strict}{Strict}\texttt{"} attribute allows this warning facility to be switched + off, so that a fatal error is always reported for any conversion + error. + } + \sstsynopsis{ + AstKeyMap $*$astWarnings( AstChannel $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Channel. + } + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + The basic Channel class generates a warning when ever an + un-recognised item is encountered whilst reading an \htmlref{Object}{Object} from + an external data source. If Strict is zero (the default), then + unexpected items in the Object description are simply ignored, + and any remaining items are used to construct the returned + Object. If Strict is non-zero, an error will be reported and a + NULL Object pointer returned if any unexpected items are + encountered. + + As AST continues to be developed, new attributes are added + occasionally to selected classes. If an older version of AST is + used to read external Object descriptions created by a more + recent version of AST, then the Channel class will, by default, + ignore the new attributes, using the remaining attributes to + construct the Object. This is usually a good thing. However, + since external Object descriptions are often stored in plain + text, it is possible to edit them using a text editor. This + gives rise to the possibility of genuine errors in the + description due to finger-slips, typos, or simple + mis-understanding. Such inappropriate attributes will be ignored + if Strict is left at its default zero value. This will cause the + mis-spelled attribute to revert to its default value, + potentially causing subtle changes in the behaviour of + application software. If such an effect is suspected, the Strict + attribute can be set non-zero, resulting in the erroneous + attribute being identified in an error message. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + The returned KeyMap will contain warnings for all conditions + listed in the \htmlref{Warnings}{Warnings} attribute. + } + \sstsubsection{ + \htmlref{XmlChan}{XmlChan} + }{ + Reports conversion errors that result in what are usally + insignificant changes. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astWarnings() + }{ + A pointer to the KeyMap holding the warning messages, or + NULL + if no warnings were issued during the previous read operation. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The returned KeyMap uses keys of the form \texttt{"} Warning\_1\texttt{"} , + \texttt{"} Warning\_2\texttt{"} , etc. + + \sstitem + A value of + NULL will be returned if this function is invoked with the AST + error status set, + or if it should fail for any reason. + } + } +} +\sstroutine{ + astWatch +}{ + Identify a new error status variable for the AST library +}{ + \sstdescription{ + This function allows a new error status variable to be accessed + by the AST library when checking for and reporting error + conditions. + + By default, the library uses an internal integer error status + which is set to an error value if an error occurs. Use of + astWatch allows the internal error status to be replaced by an + integer variable of your choosing, so that the AST library can + share its error status directly with other code which uses the + same error detection convention. + + If an alternative error status variable is supplied, it is used + by all related AST functions and macros (e.g. \htmlref{astOK}{astOK}, \htmlref{astStatus}{astStatus} + and \htmlref{astClearStatus}{astClearStatus}). + } + \sstsynopsis{ + int $*$astWatch( int $*$status\_ptr ) + } + \sstparameters{ + \sstsubsection{ + status\_ptr + }{ + Pointer to an int whose value is to be used subsequently as + the AST inherited status value. If a NULL pointer is supplied, + the AST library will revert to using its own internal error status. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astWatch() + }{ + Address of the previous error status variable. This may later + be passed back to astWatch to restore the previous behaviour + of the library. (Note that on the first invocation of + astWatch the returned value will be the address of the + internal error status variable.) + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This function is not available in the FORTRAN 77 interface to + the AST library. + } + } +} +\sstroutine{ + astWcsMap +}{ + Create a WcsMap +}{ + \sstdescription{ + This function creates a new \htmlref{WcsMap}{WcsMap} and optionally initialises its + attributes. + + A WcsMap is used to represent sky coordinate projections as + described in the (draft) FITS world coordinate system (FITS-WCS) + paper by E.W. Griesen and M. Calabretta (A \& A, in preparation). + This paper defines a set of functions, or sky projections, which + transform longitude-latitude pairs representing spherical + celestial coordinates into corresponding pairs of Cartesian + coordinates (and vice versa). + + A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these + sky projections and applies them to a specified pair of coordinates. + All the projections in the FITS-WCS paper are supported, plus the now + deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which + is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, + the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection + plane\texttt{"} coordinates. These coordinates may, optionally, be embedded in + a space with more than two dimensions, the remaining coordinates being + copied unchanged. Note, however, that for consistency with other AST + facilities, a WcsMap handles coordinates that represent angles + in radians (rather than the degrees used by FITS-WCS). + + The type of FITS-WCS projection to be used and the coordinates + (axes) to which it applies are specified when a WcsMap is first + created. The projection type may subsequently be determined + using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts + may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. + + Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be + associated with each axis. These specify the precise form of the + projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is + the integer axis index (starting at 1), and m is an integer + \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection + parameters required by each projection, and their meanings, are + dependent upon the projection type (most projections either do not + use any projection parameters, or use parameters 1 and 2 associated + with the latitude axis). Before creating a WcsMap you should consult + the FITS-WCS paper for details of which projection parameters are + required, and which have defaults. When creating the WcsMap, you must + explicitly set values for all those required projection parameters + which do not have defaults defined in this paper. + } + \sstsynopsis{ + AstWcsMap $*$astWcsMap( int ncoord, int type, int lonax, int latax, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of coordinate values for each point to be + transformed (i.e. the number of dimensions of the space in + which the points will reside). This must be at least 2. The + same number is applicable to both input and output points. + } + \sstsubsection{ + type + }{ + The type of FITS-WCS projection to apply. This should be + given using a macro value such as AST\_\_TAN (for a tangent + plane projection), where the characters following the double + underscore give the projection type code (in upper case) as + used in the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword. You should consult the + FITS-WCS paper for a list of the available projections. The + additional code of AST\_\_TPN can be supplied which represents a + TAN projection with polynomial correction terms as defined in an + early draft of the FITS-WCS paper. + } + \sstsubsection{ + lonax + }{ + The index of the longitude axis. This should lie in the range + 1 to \texttt{"} ncoord\texttt{"} . + } + \sstsubsection{ + latax + }{ + The index of the latitude axis. This should lie in the range + 1 to \texttt{"} ncoord\texttt{"} and be distinct from \texttt{"} lonax\texttt{"} . + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new WcsMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + + If the sky projection to be implemented requires projection + parameter values to be set, then this should normally be done + here via the PVi\_m attribute (see the \texttt{"} Examples\texttt{"} + section). Setting values for these parameters is mandatory if + they do not have default values (as defined in the FITS-WCS + paper). + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astWcsMap() + }{ + A pointer to the new WcsMap. + } + } + \sstexamples{ + \sstexamplesubsection{ + wcsmap = astWcsMap( 2, AST\_\_MER, 1, 2, \texttt{"} \texttt{"} ); + }{ + Creates a WcsMap that implements a FITS-WCS Mercator + projection on pairs of coordinates, with coordinates 1 and 2 + representing the longitude and latitude respectively. Note + that the FITS-WCS Mercator projection does not require any + projection parameters. + } + \sstexamplesubsection{ + wcsmap = astWcsMap( 3, AST\_\_COE, 2, 3, \texttt{"} PV3\_1=40.0\texttt{"} ); + }{ + Creates a WcsMap that implements a FITS-WCS conical equal + area projection. The WcsMap acts on points in a 3-dimensional + space; coordinates 2 and 3 represent longitude and latitude + respectively, while the values of coordinate 1 are copied + unchanged. \htmlref{Projection}{Projection} parameter 1 associatyed with the latitude + axis (corresponding to FITS keyword \texttt{"} PV3\_1\texttt{"} ) is required and has + no default, so is set explicitly to 40.0 degrees. Projection + parameter 2 (corresponding to FITS keyword \texttt{"} PV3\_2\texttt{"} ) is required + but has a default of zero, so need not be specified. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The forward transformation of a WcsMap converts between + FITS-WCS \texttt{"} native spherical\texttt{"} and \texttt{"} relative physical\texttt{"} coordinates, + while the inverse transformation converts in the opposite + direction. This arrangement may be reversed, if required, by + using \htmlref{astInvert}{astInvert} or by setting the \htmlref{Invert}{Invert} attribute to a non-zero + value. + + \sstitem + If any set of coordinates cannot be transformed (for example, + many projections do not cover the entire celestial sphere), then + a WcsMap will yield coordinate values of AST\_\_BAD. + + \sstitem + The validity of any projection parameters given via the PVi\_m + parameter in the \texttt{"} options\texttt{"} string is not checked by this + function. However, their validity is checked when the resulting + WcsMap is used to transform coordinates, and an error will + result if the projection parameters do not satisfy all the + required constraints (as defined in the FITS-WCS paper). + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astWinMap +}{ + Create a WinMap +}{ + \sstdescription{ + This function creates a new \htmlref{WinMap}{WinMap} and optionally initialises its + attributes. + + A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular + window in one coordinate system into a similar window in another + coordinate system by scaling and shifting each axis (the window + edges being parallel to the coordinate axes). + + A WinMap is specified by giving the coordinates of two opposite + corners (A and B) of the window in both the input and output + coordinate systems. + } + \sstsynopsis{ + AstWinMap $*$astWinMap( int ncoord, + const double ina[], const double inb[], + const double outa[], const double outb[], + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of coordinate values for each point to be + transformed (i.e. the number of dimensions of the space in + which the points will reside). The same number is applicable + to both input and output points. + } + \sstsubsection{ + ina + }{ + An array containing the \texttt{"} ncoord\texttt{"} + coordinates of corner A of the window in the input coordinate + system. + } + \sstsubsection{ + inb + }{ + An array containing the \texttt{"} ncoord\texttt{"} + coordinates of corner B of the window in the input coordinate + system. + } + \sstsubsection{ + outa + }{ + An array containing the \texttt{"} ncoord\texttt{"} + coordinates of corner A of the window in the output coordinate + system. + } + \sstsubsection{ + outb + }{ + An array containing the \texttt{"} ncoord\texttt{"} + coordinates of corner B of the window in the output coordinate + system. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new WinMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astWinMap() + }{ + A pointer to the new WinMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\sstroutine{ + astWrite +}{ + Write an Object to a Channel +}{ + \sstdescription{ + This function writes an \htmlref{Object}{Object} to a \htmlref{Channel}{Channel}, appending it to any + previous Objects written to that Channel. + } + \sstsynopsis{ + int astWrite( AstChannel $*$this, AstObject $*$object ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the Channel. + } + \sstsubsection{ + object + }{ + Pointer to the Object which is to be written. + } + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather + than the native AST encoding, then storing values in the + FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking + astWrite + can help to produce a successful write. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astWrite() + }{ + The number of Objects written to the Channel by this + invocation of astWrite (normally, this will be one). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero will be returned if this function is invoked + with the AST error status set, or if it should fail for any + reason. + + \sstitem + Invoking this function will usually cause the sink function + associated with the channel to be called in order to transfer a + textual description of the supplied object to some external data + store. However, the FitsChan class behaves differently. Invoking + this function on a FitsChan causes new FITS header cards to be + added to an internal buffer (the sink function is not invoked). + This buffer is written out through the sink function only when the + FitsChan is deleted. + } + } +} +\sstroutine{ + astWriteFits +}{ + Write out all cards in a FitsChan to the sink function +}{ + \sstdescription{ + This function + writes out all cards currently in the \htmlref{FitsChan}{FitsChan}. If the \htmlref{SinkFile}{SinkFile} + attribute is set, they will be written out to the specified sink file. + Otherwise, they will be written out using the sink function specified + when the FitsChan was created. All cards are then deleted from the + FitsChan. + } + \sstsynopsis{ + void astWriteFits( AstFitsChan $*$this ) + } + \sstparameters{ + \sstsubsection{ + this + }{ + Pointer to the FitsChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the SinkFile is unset, and no sink function is available, this + method simply empties the FitsChan, and is then equivalent to + \htmlref{astEmptyFits}{astEmptyFits}. + + \sstitem + This method attempt to execute even if an error has occurred + previously. + } + } +} +\sstroutine{ + astXmlChan +}{ + Create an XmlChan +}{ + \sstdescription{ + This function creates a new \htmlref{XmlChan}{XmlChan} and optionally initialises + its attributes. + + A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O + operations. Writing an \htmlref{Object}{Object} to an XmlChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an + XML description of that Object, and reading from an XmlChan will + create a new Object from its XML description. + + Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting XML text. By default, however, + an XmlChan will read from standard input and write to standard + output. + + Alternatively, an XmlChan can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + } + \sstsynopsis{ + AstXmlChan $*$astXmlChan( const char $*$($*$ source)( void ), + void ($*$ sink)( const char $*$ ), + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + source + }{ + Pointer to a source function that takes no arguments and + returns a pointer to a null-terminated string. If no value + has been set for the SourceFile attribute, this function + will be used by the XmlChan to obtain lines of input text. On + each invocation, it should return a pointer to the next input + line read from some external data store, and a NULL pointer + when there are no more lines to read. + + If \texttt{"} source\texttt{"} is NULL and no value has been set for the SourceFile + attribute, the XmlChan will read from standard input instead. + } + \sstsubsection{ + sink + }{ + Pointer to a sink function that takes a pointer to a + null-terminated string as an argument and returns void. + If no value has been set for the SinkFile attribute, this + function will be used by the XmlChan to deliver lines of + output text. On each invocation, it should deliver the + contents of the string supplied to some external data store. + + If \texttt{"} sink\texttt{"} is NULL, and no value has been set for the SinkFile + attribute, the XmlChan will write to standard output instead. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new XmlChan. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astXmlChan() + }{ + A pointer to the new XmlChan. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the external data source or sink uses a character encoding + other than ASCII, the supplied source and sink functions should + translate between the external character encoding and the internal + ASCII encoding used by AST. + + \sstitem + A null Object pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } +} +\sstroutine{ + astZoomMap +}{ + Create a ZoomMap +}{ + \sstdescription{ + This function creates a new \htmlref{ZoomMap}{ZoomMap} and optionally initialises its + attributes. + + A ZoomMap is a \htmlref{Mapping}{Mapping} which \texttt{"} zooms\texttt{"} a set of points about the + origin by multiplying all coordinate values by the same scale + factor (the inverse transformation is performed by dividing by + this scale factor). + } + \sstsynopsis{ + AstZoomMap $*$astZoomMap( int ncoord, double zoom, + const char $*$options, ... ) + } + \sstparameters{ + \sstsubsection{ + ncoord + }{ + The number of coordinate values for each point to be + transformed (i.e. the number of dimensions of the space in + which the points will reside). The same number is applicable + to both input and output points. + } + \sstsubsection{ + zoom + }{ + Initial scale factor by which coordinate values should be + multiplied (by the forward transformation) or divided (by the + inverse transformation). This factor may subsequently be + changed via the ZoomMap\texttt{'} s \htmlref{Zoom}{Zoom} attribute. It may be positive + or negative, but should not be zero. + } + \sstsubsection{ + options + }{ + Pointer to a null-terminated string containing an optional + comma-separated list of attribute assignments to be used for + initialising the new ZoomMap. The syntax used is identical to + that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"} format + specifiers identified by \texttt{"} \%\texttt{"} symbols in the normal way. + } + \sstsubsection{ + ... + }{ + If the \texttt{"} options\texttt{"} string contains \texttt{"} \%\texttt{"} format specifiers, then + an optional list of additional arguments may follow it in + order to supply values to be substituted for these + specifiers. The rules for supplying these are identical to + those for the astSet function (and for the C \texttt{"} printf\texttt{"} + function). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astZoomMap() + }{ + A pointer to the new ZoomMap. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this + function is invoked with the AST error status set, or if it + should fail for any reason. + } + } + \sstdiytopic{ + Status Handling + }{ + The protected interface to this function includes an extra + parameter at the end of the parameter list descirbed above. This + parameter is a pointer to the integer inherited status + variable: \texttt{"} int $*$status\texttt{"} . + } +} +\normalsize + +\cleardoublepage +\section{\label{ss:attributedescriptions}AST Attribute Descriptions} +\small +\sstroutine{ + Abbrev(axis) +}{ + Abbreviate leading fields within numerical axis labels? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether matching leading fields should be removed from adjacent + numerical axis labels. It takes a separate value for each physical + axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} Abbrev(2)=0\texttt{"} + specifies that matching leading fields should not be removed on + the second axis. + + If the Abbrev value of a Plot is non-zero (the default), then + leading fields will be removed from adjacent axis labels if they + are equal. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} Abbrev\texttt{"} instead of + \texttt{"} Abbrev(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the Abbrev(1) value. + } + } +} +\sstroutine{ + Adaptive +}{ + Should the area adapt to changes in the coordinate system? +}{ + \sstdescription{ + The coordinate system represented by a \htmlref{Region}{Region} may be changed by + assigning new values to attributes such as \htmlref{System}{System}, Unit, etc. + For instance, a Region representing an area on the sky in ICRS + coordinates may have its System attribute changed so that it + represents (say) Galactic coordinates instead of ICRS. This + attribute controls what happens when the coordinate system + represented by a Region is changed in this way. + + If Adaptive is non-zero (the default), then area represented by the + Region adapts to the new coordinate system. That is, the numerical + values which define the area represented by the Region are changed + by mapping them from the old coordinate system into the new coordinate + system. Thus the Region continues to represent the same physical + area. + + If Adaptive is zero, then area represented by the Region does not adapt + to the new coordinate system. That is, the numerical values which + define the area represented by the Region are left unchanged. Thus + the physical area represented by the Region will usually change. + + As an example, consider a Region describe a range of wavelength from + 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region + is changed from Angstrom to \texttt{"} nm\texttt{"} (nanometre), what happens depends + on the setting of Adaptive. If Adaptive is non-zero, the \htmlref{Mapping}{Mapping} + from the old to the new coordinate system is found. In this case it + is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). + This Mapping is then used to modify the numerical values within the + Region, changing 2000 to 200 and 4000 to 400. Thus the modified + region represents 200 nm to 400 nm, the same physical space as + the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive + had been zero, then the numerical values would not have been changed, + resulting in the final Region representing 2000 nm to 4000 nm. + + Setting Adaptive to zero can be necessary if you want correct + inaccurate attribute settings in an existing Region. For instance, + when creating a Region you may not know what \htmlref{Epoch}{Epoch} value to use, so + you would leave Epoch unset resulting in some default value being used. + If at some later point in the application, the correct Epoch value + is determined, you could assign the correct value to the Epoch + attribute. However, you would first need to set Adaptive temporarily + to zero, because otherwise the area represented by the Region would + be Mapped from the spurious default Epoch to the new correct Epoch, + which is not what is required. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + } +} +\sstroutine{ + AlignOffset +}{ + Align SkyFrames using the offset coordinate system? +}{ + \sstdescription{ + This attribute is a boolean value which controls how a \htmlref{SkyFrame}{SkyFrame} + behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) + SkyFrame. It determines the coordinate system in which the two + SkyFrames are aligned if a match occurs. + + If the template and target SkyFrames both have defined offset coordinate + systems (i.e. the \htmlref{SkyRefIs}{SkyRefIs} attribute is set to either \texttt{"} Origin\texttt{"} or \texttt{"} + Pole\texttt{"} ), and they both have a non-zero value for AlignOffset, then + alignment occurs within the offset coordinate systems (that is, a + \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). If either + the template or target SkyFrame has zero (the default value) for + AlignOffset, or if either SkyFrame has SkyRefIs set to \texttt{"} Ignored\texttt{"} , then + alignment occurring within the coordinate system specified by the + \htmlref{AlignSystem}{AlignSystem} attribute. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + AlignSideBand +}{ + Should the SideBand attribute be taken into account when aligning + this \htmlref{DSBSpecFrame}{DSBSpecFrame} with another DSBSpecFrame? +}{ + \sstdescription{ + This attribute controls how a DSBSpecFrame behaves when an attempt + is made to align it with another DSBSpecFrame using + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}. + If both DSBSpecFrames have a non-zero value for AlignSideBand, the + value of the \htmlref{SideBand}{SideBand} attribute in each DSBSpecFrame is used so that + alignment occurs between sidebands. That is, if one DSBSpecFrame + represents USB and the other represents LSB then + astFindFrame and astConvert + will recognise that the DSBSpecFrames represent different sidebands + and will take this into account when constructing the \htmlref{Mapping}{Mapping} that + maps positions in one DSBSpecFrame into the other. If AlignSideBand + in either DSBSpecFrame is set to zero, then the values of the SideBand + attributes are ignored. In the above example, this would result in a + frequency in the first DSBSpecFrame being mapped onto the same + frequency in the second DSBSpecFrame, even though those frequencies + refer to different sidebands. In other words, if either AlignSideBand + attribute is zero, then the two DSBSpecFrames aligns like basic + SpecFrames. The default value for AlignSideBand is zero. + + When astFindFrame or astConvert + is used on two DSBSpecFrames (potentially describing different spectral + coordinate systems and/or sidebands), it returns a Mapping which can be + used to transform a position in one DSBSpecFrame into the corresponding + position in the other. The Mapping is made up of the following steps in + the indicated order: + + \sstitemlist{ + + \sstitem + If both DSBSpecFrames have a value of 1 for the AlignSideBand + attribute, map values from the target\texttt{'} s current sideband (given by its + SideBand attribute) to the observed sideband (whether USB or LSB). If + the target already represents the observed sideband, this step will + leave the values unchanged. If either of the two DSBSpecFrames have a + value of zero for its AlignSideBand attribute, then this step is omitted. + + \sstitem + Map the values from the spectral system of the target to the spectral + system of the template. This Mapping takes into account all the + inherited \htmlref{SpecFrame}{SpecFrame} attributes such as \htmlref{System}{System}, \htmlref{StdOfRest}{StdOfRest}, Unit, etc. + + \sstitem + If both DSBSpecFrames have a value of 1 for the AlignSideBand + attribute, map values from the result\texttt{'} s observed sideband to the + result\texttt{'} s current sideband (given by its SideBand attribute). If the + result already represents the observed sideband, this step will leave + the values unchanged. If either of the two DSBSpecFrames have a value + of zero for its AlignSideBand attribute, then this step is omitted. + } + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + DSBSpecFrame + }{ + All DSBSpecFrames have this attribute. + } + } +} +\sstroutine{ + AlignSpecOffset +}{ + Align SpecFrames using the offset coordinate system? +}{ + \sstdescription{ + This attribute is a boolean value which controls how a \htmlref{SpecFrame}{SpecFrame} + behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) + SpecFrame. It determines whether alignment occurs between the offset + values defined by the current value of the SpecOffset attribute, or + between the corresponding absolute spectral values. + + The default value of zero results in the two SpecFrames being aligned + so that a given absolute spectral value in one is mapped to the same + absolute value in the other. A non-zero value results in the SpecFrames + being aligned so that a given offset value in one is mapped to the same + offset value in the other. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + SpecFrame + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + AlignStdOfRest +}{ + Standard of rest to use when aligning SpecFrames +}{ + \sstdescription{ + This attribute controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) + SpecFrame. It identifies the standard of rest in which alignment is + to occur. See the \htmlref{StdOfRest}{StdOfRest} attribute for a desription of the values + which may be assigned to this attribute. The default AlignStdOfRest + value is \texttt{"} Helio\texttt{"} (heliographic). + + When astFindFrame or astConvert is used on two SpecFrames (potentially + describing different spectral coordinate systems), it returns a \htmlref{Mapping}{Mapping} + which can be used to transform a position in one SpecFrame into the + corresponding position in the other. The Mapping is made up of the + following steps in the indicated order: + + \sstitemlist{ + + \sstitem + Map values from the system used by the target (wavelength, + apparent radial velocity, etc) to the system specified by the + \htmlref{AlignSystem}{AlignSystem} attribute, using the target\texttt{'} s rest frequency if necessary. + + \sstitem + Map these values from the target\texttt{'} s standard of rest to the standard of + rest specified by the AlignStdOfRest attribute, using the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat}, + \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{RefDec}{RefDec} and \htmlref{RefRA}{RefRA} attributes of the target to define the + two standards of rest. + + \sstitem + Map these values from the standard of rest specified by the + AlignStdOfRest attribute, to the template\texttt{'} s standard of rest, using the + Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the + template to define the two standards of rest. + + \sstitem + Map these values from the system specified by the AlignSystem + attribute, to the system used by the template, using the template\texttt{'} s + rest frequency if necessary. + } + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + SpecFrame + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + AlignSystem +}{ + Coordinate system in which to align the Frame +}{ + \sstdescription{ + This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) + Frame. It identifies the coordinate system in which the two Frames + will be aligned by the match. + + The values which may be assigned to this attribute, and its default + value, depend on the class of Frame and are described in the + \texttt{"} Applicability\texttt{"} section below. In general, the AlignSystem attribute + will accept any of the values which may be assigned to the \htmlref{System}{System} + attribute. + + The \htmlref{Mapping}{Mapping} returned by AST\_FINDFRAME or AST\_CONVERT will use the + coordinate system specified by the AlignSystem attribute as an + intermediate coordinate system. The total returned Mapping will first + map positions from the first Frame into this intermediate coordinate + system, using the attributes of the first Frame. It will then map + these positions from the intermediate coordinate system into the + second Frame, using the attributes of the second Frame. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The AlignSystem attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , + and may not be altered. + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The AlignSystem attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , + and may not be altered. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The AlignSystem attribute of a FrameSet is the same as that of its + current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The default AlignSystem attribute for a SkyFrame is \texttt{"} ICRS\texttt{"} . + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + The default AlignSystem attribute for a SpecFrame is \texttt{"} Wave\texttt{"} + (wavelength). + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The default AlignSystem attribute for a TimeFrame is \texttt{"} MJD\texttt{"} . + } + } +} +\sstroutine{ + AlignTimeScale +}{ + Time scale to use when aligning TimeFrames +}{ + \sstdescription{ + This attribute controls how a \htmlref{TimeFrame}{TimeFrame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target) + TimeFrame. It identifies the time scale in which alignment is + to occur. See the \htmlref{TimeScale}{TimeScale} attribute for a desription of the values + which may be assigned to this attribute. The default AlignTimeScale + value depends on the current value of TimeScale: if TimeScale is + UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all + other TimeScales the default is TAI. + + When astFindFrame or astConvert is used on two TimeFrames (potentially + describing different time coordinate systems), it returns a \htmlref{Mapping}{Mapping} + which can be used to transform a position in one TimeFrame into the + corresponding position in the other. The Mapping is made up of the + following steps in the indicated order: + + \sstitemlist{ + + \sstitem + Map values from the system used by the target (MJD, JD, etc) to the + system specified by the \htmlref{AlignSystem}{AlignSystem} attribute. + + \sstitem + Map these values from the target\texttt{'} s time scale to the time scale + specified by the AlignTimeScale attribute. + + \sstitem + Map these values from the time scale specified by the AlignTimeScale + attribute, to the template\texttt{'} s time scale. + + \sstitem + Map these values from the system specified by the AlignSystem + attribute, to the system used by the template. + } + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + TimeFrame + }{ + All TimeFrames have this attribute. + } + } +} +\sstroutine{ + AllVariants +}{ + A list of the variant Mappings associated with the current Frame +}{ + \sstdescription{ + This attrbute gives a space separated list of the names of all the + variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute + \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the + list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the + current Frame. + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + All FrameSets have this attribute. + } + } +} +\sstroutine{ + AllWarnings +}{ + A list of all currently available condition names +}{ + \sstdescription{ + This read-only attribute is a space separated list of all the conditions + names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed + below. + } + \sstattributetype{ + String, read-only + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + All FitsChans have this attribute. + } + } + \sstdiytopic{ + Conditions + }{ + The following conditions are currently recognised (all are + case-insensitive): + + \sstitemlist{ + + \sstitem + \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a + non-Native encoded FitsChan if an unknown celestial co-ordinate + system is specified by the CTYPE keywords. + + \sstitem + \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a + non-Native encoded FitsChan if an illegal algorithm code is specified + by a CTYPE keyword, and the illegal code can be converted to an + equivalent legal code. + + \sstitem + \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is + encountered that contains an illegal character (i.e. one not allowed + by the FITS standard). + + \sstitem + \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword + cannot be determined from the content of the header card. + + \sstitem + \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a + non-Native encoded FitsChan if the latitude of the reference point + has an absolute value greater than 90 degrees. The actual absolute + value used is set to exactly 90 degrees in these cases. + + \sstitem + \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the + transformation from pixel offsets to intermediate world coordinates + cannot be inverted. This matrix describes the scaling, rotation, shear, + etc., applied to the pixel axes, and is specified by keywords such as + PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable + if any rows or columns consist entirely of zeros. The FITS-WCS Paper I + \texttt{"} Representation of World Coordinates in FITS\texttt{"} by Greisen \& Calabretta + requires that this matrix be invertable. Many operations (such as + grid plotting) will not be possible if the matrix cannot be inverted. + + \sstitem + \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a + non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found + that refers to a projection parameter that is not used by the + projection type specified by CTYPE, or the PV values are otherwise + inappropriate for the projection type. + + \sstitem + \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a + non-Native encoded FitsChan if it is not possible to convert the + value of a FITS keywords to the expected type. For instance, this + can occur if the FITS header contains a string value for a keyword + which should have a floating point value, or if the keyword has no + value at all (i.e. is a comment card). + + \sstitem + \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a + non-Native encoded FitsChan if any of the CTYPE keywords specify an + unsupported distortion code using the \texttt{"} 4-3-3\texttt{"} format specified in + FITS-WCS paper IV. Such distortion codes are ignored. + + \sstitem + \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used + within \htmlref{astRead}{astRead}, due to no value being present in the supplied FitsChan. + This condition is only tested for when using non-Native encodings. + + \sstitem + \texttt{"} NoEquinox\texttt{"} : This condition arises if a default equinox value is used + within astRead, due to no value being present in the supplied FitsChan. + This condition is only tested for when using non-Native encodings. + + \sstitem + \texttt{"} NoRadesys\texttt{"} : This condition arises if a default reference frame is + used for an equatorial co-ordinate system within astRead, due to no + value being present in the supplied FitsChan. This condition is only + tested for when using non-Native encodings. + + \sstitem + \texttt{"} NoLonpole\texttt{"} : This condition arises if a default value is used for + the LONPOLE keyword within astRead, due to no value being present + in the supplied FitsChan. This condition is only tested for when + using non-Native encodings. + + \sstitem + \texttt{"} NoLatpole\texttt{"} : This condition arises if a default value is used for + the LATPOLE keyword within astRead, due to no value being present + in the supplied FitsChan. This condition is only tested for when + using non-Native encodings. + + \sstitem + \texttt{"} NoMjd-obs\texttt{"} : This condition arises if a default value is used for + the date of observation within astRead, due to no value being present + in the supplied FitsChan. This condition is only tested for when using + non-Native encodings. + + \sstitem + \texttt{"} Tnx\texttt{"} : This condition arises if a FrameSet is read from a FITS + header containing an IRAF \texttt{"} TNX\texttt{"} projection which includes terms + not supproted by AST. Such terms are ignored and so the resulting + FrameSet may be inaccurate. + + \sstitem + \texttt{"} Zpx\texttt{"} : This condition arises if a FrameSet is read from a FITS + header containing an IRAF \texttt{"} ZPX\texttt{"} projection which includes \texttt{"} lngcor\texttt{"} + or \texttt{"} latcor\texttt{"} correction terms. These terms are not supported by AST + and are ignored. The resulting FrameSet may therefore be inaccurate. + } + } +} +\sstroutine{ + AsTime(axis) +}{ + Format celestal coordinates as times? +}{ + \sstdescription{ + This attribute specifies the default style of formatting to be + used (e.g. by \htmlref{astFormat}{astFormat}) for the celestial coordinate values + described by a \htmlref{SkyFrame}{SkyFrame}. It takes a separate boolean value for + each SkyFrame axis so that, for instance, the setting + \texttt{"} AsTime(2)=0\texttt{"} specifies the default formatting style for + celestial latitude values. + + If the AsTime attribute for a SkyFrame axis is zero, then + coordinates on that axis will be formatted as angles by default + (using degrees, minutes and seconds), otherwise they will be + formatted as times (using hours, minutes and seconds). + + The default value of AsTime is chosen according to the sky + coordinate system being represented, as determined by the + SkyFrame\texttt{'} s \htmlref{System}{System} attribute. This ensures, for example, that + right ascension values will be formatted as times by default, + following normal conventions. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The AsTime attribute operates by changing the default value of + the corresponding \htmlref{Format(axis)}{Format(axis)} attribute. This, in turn, may + also affect the value of the \htmlref{Unit(axis)}{Unit(axis)} attribute. + + \sstitem + Only the default style of formatting is affected by the AsTime + value. If an explicit Format(axis) value is set, it will + over-ride any effect from the AsTime attribute. + } + } +} +\sstroutine{ + Base +}{ + FrameSet base Frame index +}{ + \sstdescription{ + This attribute gives the index of the \htmlref{Frame}{Frame} which is to be + regarded as the \texttt{"} base\texttt{"} Frame within a \htmlref{FrameSet}{FrameSet}. The default is + the first Frame added to the FrameSet when it is created (this + Frame always has an index of 1). + + When setting a new value for this attribute, a string may be + supplied instead of an integer index. In this case a search + is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain} + attribute value equal to the supplied string (the comparison is + case-insensitive). If found, the Frame is made the base Frame. + Otherwise an error is reported. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FrameSet + }{ + All FrameSets have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Inverting a FrameSet (inverting the boolean sense of its + \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will + interchange the values of its Base and \htmlref{Current}{Current} attributes. + } + } +} +\sstroutine{ + Border +}{ + Draw a border around valid regions of a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether a border is drawn around regions corresponding to the + valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{astBorder}{astBorder}). + + If the Border value of a Plot is non-zero, then this border will + be drawn as part of the grid. Otherwise, the border is not drawn + (although axis labels and tick marks will still appear, unless + other relevant Plot attributes indicate that they should + not). The default behaviour is to draw the border if tick marks + and numerical labels will be drawn around the edges of the + plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit it + otherwise. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } +} +\sstroutine{ + Bottom(axis) +}{ + Lowest axis value to display +}{ + \sstdescription{ + This attribute gives the lowest axis value to be displayed (for + instance, by the \htmlref{astGrid}{astGrid} method). + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + The default supplied by the Frame class is to display all axis + values, without any limit. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Bottom value to -90 degrees + for latitude axes, and 0 degrees for co-latitude axes. The + default for longitude axes is to display all axis values. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + Bounded +}{ + Is the Region bounded? +}{ + \sstdescription{ + This is a read-only attribute indicating if the \htmlref{Region}{Region} is bounded. + A Region is bounded if it is contained entirely within some + finite-size bounding box. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + } +} +\sstroutine{ + CDMatrix +}{ + Use CDi\_j keywords to represent pixel scaling, rotation, etc? +}{ + \sstdescription{ + This attribute is a boolean value which specifies how the linear + transformation from pixel coordinates to intermediate world + coordinates should be represented within a \htmlref{FitsChan}{FitsChan} when using + FITS-WCS encoding. This transformation describes the scaling, + rotation, shear, etc., of the pixel axes. + + If the attribute has a non-zero value then the transformation is + represented by a set of CDi\_j keywords representing a square matrix + (where \texttt{"} i\texttt{"} is the index of an intermediate world coordinate axis + and \texttt{"} j\texttt{"} is the index of a pixel axis). If the attribute has a zero + value the transformation is represented by a set of PCi\_j keywords + (which also represent a square matrix) together with a corresponding + set of CDELTi keywords representing the axis scalings. See FITS-WCS + paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by + M. Calabretta \& E.W. Greisen, for a complete description of these two + schemes. + + The default value of the CDMatrix attribute is determined by the + contents of the FitsChan at the time the attribute is accessed. If + the FitsChan contains any CDi\_j keywords then the default value is + non-zero. Otherwise it is zero. Note, reading a \htmlref{FrameSet}{FrameSet} from a + FitsChan will in general consume any CDi\_j keywords present in the + FitsChan. Thus the default value for CDMatrix following a read will + usually be zero, even if the FitsChan originally contained some + CDi\_j keywords. This behaviour is similar to that of the \htmlref{Encoding}{Encoding} + attribute, the default value for which is determined by the contents + of the FitsChan at the time the attribute is accessed. If you wish + to retain the original value of the CDMatrix attribute (that is, + the value before reading the FrameSet) then you should enquire the + default value before doing the read, and then set that value + explicitly. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + CarLin +}{ + Ignore spherical rotations on CAR projections? +}{ + \sstdescription{ + This attribute is a boolean value which specifies how FITS \texttt{"} CAR\texttt{"} + (plate carree, or \texttt{"} Cartesian\texttt{"} ) projections should be treated when + reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero (the + default), it is assumed that the CAR projection conforms to the + conventions described in the FITS world coordinate system (FITS-WCS) + paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"} by + M. Calabretta \& E.W. Greisen. If CarLin is non-zero, then these + conventions are ignored, and it is assumed that the mapping from pixel + coordinates to celestial coordinates is a simple linear transformation + (hence the attribute name \texttt{"} CarLin\texttt{"} ). This is appropriate for some older + FITS data which claims to have a \texttt{"} CAR\texttt{"} projection, but which in fact do + not conform to the conventions of the FITS-WCS paper. + + The FITS-WCS paper specifies that headers which include a CAR projection + represent a linear mapping from pixel coordinates to \texttt{"} native spherical + coordinates\texttt{"} , NOT celestial coordinates. An extra mapping is then + required from native spherical to celestial. This mapping is a 3D + rotation and so the overall \htmlref{Mapping}{Mapping} from pixel to celestial coordinates + is NOT linear. See the FITS-WCS papers for further details. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Card +}{ + Index of current FITS card in a FitsChan +}{ + \sstdescription{ + This attribute gives the index of the \texttt{"} current\texttt{"} FITS header card + within a \htmlref{FitsChan}{FitsChan}, the first card having an index of 1. The + choice of current card affects the behaviour of functions that + access the contents of the FitsChan, such as \htmlref{astDelFits}{astDelFits}, + \htmlref{astFindFits}{astFindFits} and \htmlref{astPutFits}{astPutFits}. + + A value assigned to Card will position the FitsChan at any + desired point, so that a particular card within it can be + accessed. Alternatively, the value of Card may be enquired in + order to determine the current position of a FitsChan. + + The default value of Card is 1. This means that clearing + this attribute (using \htmlref{astClear}{astClear}) effectively \texttt{"} rewinds\texttt{"} the + FitsChan, so that the first card is accessed next. If Card is + set to a value which exceeds the total number of cards in the + FitsChan (as given by its \htmlref{Ncard}{Ncard} attribute), it is regarded as + pointing at the \texttt{"} end-of-file\texttt{"} . In this case, the value returned + in response to an enquiry is always one more than the number of + cards in the FitsChan. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + CardComm +}{ + The comment for the current card in a FitsChan +}{ + \sstdescription{ + This attribute gives the comment for the current card of the + \htmlref{FitsChan}{FitsChan}. A zero-length string is returned if the card has no comment. + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + CardName +}{ + The keyword name of the current card in a FitsChan +}{ + \sstdescription{ + This attribute gives the name of the keyword for the + current card of the \htmlref{FitsChan}{FitsChan}. + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + CardType +}{ + The data type of the current card in a FitsChan +}{ + \sstdescription{ + This attribute gives the data type of the keyword value for the + current card of the \htmlref{FitsChan}{FitsChan}. It will be one of the following + integer constants: AST\_\_NOTYPE, AST\_\_COMMENT, AST\_\_INT, AST\_\_FLOAT, + AST\_\_STRING, AST\_\_COMPLEXF, AST\_\_COMPLEXI, AST\_\_LOGICAL, + AST\_\_CONTINUE, AST\_\_UNDEF. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Class +}{ + Object class name +}{ + \sstdescription{ + This attribute gives the name of the class to which an \htmlref{Object}{Object} + belongs. + } + \sstattributetype{ + Character string, read-only. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + Clean +}{ + Remove cards used whilst reading even if an error occurs? +}{ + \sstdescription{ + This attribute indicates whether or not cards should be removed from + the \htmlref{FitsChan}{FitsChan} if an error occurs within + \htmlref{astRead}{astRead}. + A succesful read on a FitsChan always results in the removal of + the cards which were involved in the description of the returned + \htmlref{Object}{Object}. However, in the event of an error during the read (for instance + if the cards in the FitsChan have illegal values, or if some required + cards are missing) no cards will be removed from the FitsChan if + the Clean attribute is zero (the default). If Clean is non-zero then + any cards which were used in the aborted attempt to read an object + will be removed. + + This provides a means of \texttt{"} cleaning\texttt{"} a FitsChan of WCS related cards + which works even in the event of the cards not forming a legal WCS + description. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Clip +}{ + Clip lines and/or markers at the Plot boundary? +}{ + \sstdescription{ + This attribute controls whether curves and markers are clipped at the + boundary of the graphics box specified when the \htmlref{Plot}{Plot} was created. A + value of 3 implies both markers and curves are clipped at the Plot + boundary. A value of 2 implies markers are clipped, but not curves. A + value of 1 implies curves are clipped, but not markers. A value of + zero implies neither curves nor markers are clipped. The default + value is 1. Note, this attributes controls only the clipping + performed internally within AST. The underlying graphics system may + also apply clipping. In such cases, removing clipping using this + attribute does not guarantee that no clipping will be visible in the + final plot. + + The \htmlref{astClip}{astClip} function + can be used to establish generalised clipping within arbitrary + regions of the Plot. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } +} +\sstroutine{ + ClipOp +}{ + Combine Plot clipping limits using a boolean OR? +}{ + \sstdescription{ + This attribute controls how the clipping limits specified for + each axis of a \htmlref{Plot}{Plot} (using the \htmlref{astClip}{astClip} function) are + combined. This, in turn, determines which parts of the graphical + output will be visible. + + If the ClipOp attribute of a Plot is zero (the default), + graphical output is visible only if it satisfies the clipping + limits on all the axes of the clipping \htmlref{Frame}{Frame} (a boolean + AND). Otherwise, if ClipOp is non-zero, output is visible if it + satisfies the clipping limits on one or more axes (a boolean + OR). + + An important use of this attribute is to allow areas of a Plot + to be left clear (e.g. as a background for some text). To + achieve this, the lower and upper clipping bounds supplied to + astClip should be reversed, and the ClipOp attribute of the + Plot should be set to a non-zero value. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } +} +\sstroutine{ + Closed +}{ + Should the boundary be considered to be inside the region? +}{ + \sstdescription{ + This attribute controls whether points on the boundary of a \htmlref{Region}{Region} + are considered to be inside or outside the region. If the attribute + value is non-zero (the default), points on the boundary are considered + to be inside the region (that is, the Region is \texttt{"} closed\texttt{"} ). However, + if the attribute value is zero, points on the bounary are considered + to be outside the region. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + \sstsubsection{ + \htmlref{PointList}{PointList} + }{ + The value of the Closed attribute is ignored by PointList regions. + If the PointList region has not been negated, then it is always + assumed to be closed. If the PointList region has been negated, then + it is always assumed to be open. This is required since points + have zero volume and therefore consist entirely of boundary. + } + \sstsubsection{ + \htmlref{CmpRegion}{CmpRegion} + }{ + The default Closed value for a CmpRegion is the Closed value of its + first component Region. + } + \sstsubsection{ + \htmlref{Stc}{Stc} + }{ + The default Closed value for an Stc is the Closed value of its + encapsulated Region. + } + } +} +\sstroutine{ + Colour(element) +}{ + Colour index for a Plot element +}{ + \sstdescription{ + This attribute determines the colour index used when drawing + each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a + separate value for each graphical element so that, for instance, + the setting \texttt{"} Colour(title)=2\texttt{"} causes the Plot title to be drawn + using colour index 2. The synonym \texttt{"} Color\texttt{"} may also be used. + + The range of integer colour indices available and their + appearance is determined by the underlying graphics system. The + default behaviour is for all graphical elements to be drawn + using the default colour index supplied by this graphics system + (normally, this is likely to result in white plotting on a black + background, or vice versa). + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of the graphical elements available, see the + description of the Plot class. + + \sstitem + If no graphical element is specified, (e.g. \texttt{"} Colour\texttt{"} instead + of \texttt{"} Colour(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will + affect the attribute value of all graphical elements, while a + \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Colour(TextLab) + value. + } + } +} +\sstroutine{ + ColumnLenC(column) +}{ + The largest string length of any value in a column +}{ + \sstdescription{ + This attribute holds the minimum length which a character variable + must have in order to be able to store the longest value currently + present (at any row) in a specified column of the supplied \htmlref{Table}{Table}. + This does not include room for a trailing null character. + The required column name should be placed inside the parentheses in + the attribute name. If the named column holds vector values, then + the attribute value is the length of the longest element of the + vector value. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Table + }{ + All Tables have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the named column holds numerical values, the length returned + is the length of the largest string that would be generated if the + column values were accessed as strings. + } + } +} +\sstroutine{ + ColumnLength(column) +}{ + The number of elements in each value in a column +}{ + \sstdescription{ + This attribute holds the number of elements in each value stored + in a named column. Each value can be a scalar (in which case the + ColumnLength attribute has a value of 1), or a multi-dimensional + array ( in which case the ColumnLength value is equal to the + product of the array dimensions). + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Table}{Table} + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + ColumnNdim(column) +}{ + The number of axes spanned by each value in a column +}{ + \sstdescription{ + This attribute holds the number of axes spanned by each value in a + column. If each cell in the column is a scalar, ColumnNdim will be + zero. If each cell in the column is a 1D spectrum, ColumnNdim will + be one. If each cell in the column is a 2D image, ColumnNdim will be + two, etc. The required column name should be placed inside the + parentheses in the attribute name. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Table}{Table} + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + ColumnType(column) +}{ + The data type of each value in a column +}{ + \sstdescription{ + This attribute holds a integer value indicating the data type of + a named column in a \htmlref{Table}{Table}. This is the data type which was used + when the column was added to the Table using \htmlref{astAddColumn}{astAddColumn}. The + required column name should be placed inside the parentheses in + the attribute name. + + The attribute value will be one of AST\_\_INTTYPE (for integer), + AST\_\_SINTTYPE (for + short int), + AST\_\_BYTETYPE (for + unsigned bytes - i.e. unsigned chars), + AST\_\_DOUBLETYPE (for double + precision floating point), AST\_\_FLOATTYPE (for single + precision floating point), AST\_\_STRINGTYPE (for character string), + AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for + arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values + created by + \htmlref{astMapPutU}{astMapPutU}). + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Table + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + Comment +}{ + Include textual comments in output? +}{ + \sstdescription{ + This is a boolean attribute which controls whether textual + comments are to be included in the output generated by a + \htmlref{Channel}{Channel}. If included, they will describe what each item of + output represents. + + If Comment is non-zero, then comments will be included. If + it is zero, comments will be omitted. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + The default value is non-zero for a normal Channel. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + The default value is non-zero for a FitsChan. + } + \sstsubsection{ + \htmlref{XmlChan}{XmlChan} + }{ + The default value is zero for an XmlChan. + } + } +} +\sstroutine{ + Current +}{ + FrameSet current Frame index +}{ + \sstdescription{ + This attribute gives the index of the \htmlref{Frame}{Frame} which is to be + regarded as the \texttt{"} current\texttt{"} Frame within a \htmlref{FrameSet}{FrameSet}. The default + is the most recent Frame added to the FrameSet (this Frame + always has an index equal to the FrameSet\texttt{'} s \htmlref{Nframe}{Nframe} attribute). + + When setting a new value for this attribute, a string may be + supplied instead of an integer index. In this case a search + is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain} + attribute value equal to the supplied string (the comparison is + case-insensitive). If found, the Frame is made the current Frame. + Otherwise an error is reported. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FrameSet + }{ + All FrameSets have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Inverting a FrameSet (inverting the boolean sense of its + \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will + interchange the values of its \htmlref{Base}{Base} and Current attributes. + } + } +} +\sstroutine{ + DSBCentre +}{ + The central position of interest in a dual sideband spectrum +}{ + \sstdescription{ + This attribute specifies the central position of interest in a dual + sideband spectrum. Its sole use is to determine the local oscillator + frequency (the frequency which marks the boundary between the lower + and upper sidebands). See the description of the \htmlref{IF}{IF} (intermediate + frequency) attribute for details of how the local oscillator frequency + is calculated. The sideband containing this central position is + referred to as the \texttt{"} observed\texttt{"} sideband, and the other sideband as + the \texttt{"} image\texttt{"} sideband. + + The value is accessed as a position in the spectral system + represented by the \htmlref{SpecFrame}{SpecFrame} attributes inherited by this class, but + is stored internally as topocentric frequency. Thus, if the \htmlref{System}{System} + attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} is set to \texttt{"} VRAD\texttt{"} , the Unit attribute + set to \texttt{"} m/s\texttt{"} and the \htmlref{StdOfRest}{StdOfRest} attribute set to \texttt{"} LSRK\texttt{"} , then values + for the DSBCentre attribute should be supplied as radio velocity in + units of \texttt{"} m/s\texttt{"} relative to the kinematic LSR (alternative units may + be used by appending a suitable units string to the end of the value). + This value is then converted to topocentric frequency and stored. If + (say) the Unit attribute is subsequently changed to \texttt{"} km/s\texttt{"} before + retrieving the current value of the DSBCentre attribute, the stored + topocentric frequency will be converted back to LSRK radio velocity, + this time in units of \texttt{"} km/s\texttt{"} , before being returned. + + The default value for this attribute is 30 GHz. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + DSBSpecFrame + }{ + All DSBSpecFrames have this attribute. + } + } + \sstdiytopic{ + Note + }{ + \sstitemlist{ + + \sstitem + The attributes which define the transformation to or from topocentric + frequency should be assigned their correct values before accessing + this attribute. These potentially include System, Unit, StdOfRest, + \htmlref{ObsLon}{ObsLon}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec} and \htmlref{RestFreq}{RestFreq}. + } + } +} +\sstroutine{ + DefB1950 +}{ + Use FK4 B1950 as defaults? +}{ + \sstdescription{ + This attribute is a boolean value which specifies a default equinox + and reference frame to use when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} + with a foreign (i.e. non-native) encoding. It is only used if the FITS + header contains RA and DEC axes but contains no information about the + reference frame or equinox. If this is the case, then values of FK4 and + B1950 are assumed if the DefB1950 attribute has a non-zero value and + ICRS is assumed if DefB1950 is zero. The default value for DefB1950 + depends on the value of the \htmlref{Encoding}{Encoding} attribute: for FITS-WCS encoding + the default is zero, and for all other encodings it is one. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Digits/Digits(axis) +}{ + Number of digits of precision +}{ + \sstdescription{ + This attribute specifies how many digits of precision are + required by default when a coordinate value is formatted for a + \htmlref{Frame}{Frame} axis (e.g. using \htmlref{astFormat}{astFormat}). Its value may be set either + for a Frame as a whole, or (by subscripting the attribute name + with the number of an axis) for each axis individually. Any + value set for an individual axis will over-ride the value for + the Frame as a whole. + + Note that the Digits value acts only as a means of determining a + default Format string. Its effects are over-ridden if a Format + string is set explicitly for an axis. However, if the Format + attribute specifies the precision using the string \texttt{"} .$*$\texttt{"} , then + the Digits attribute is used to determine the number of decimal + places to produce. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default Digits value supplied by the Frame class is 7. If + a value less than 1 is supplied, then 1 is used instead. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Digits attribute of a FrameSet (or one of its axes) is + the same as that of its current Frame (as specified by the + \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + \htmlref{Plot}{Plot} + }{ + The default Digits value used by the Plot class when drawing + annotated axis labels is the smallest value which results in all + adjacent labels being distinct. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The Digits attribute is ignored when a TimeFrame formats a value + as a date and time string (see the Format attribute). + } + } +} +\sstroutine{ + Direction(axis) +}{ + Display axis in conventional direction? +}{ + \sstdescription{ + This attribute is a boolean value which suggests how the axes of + a \htmlref{Frame}{Frame} should be displayed (e.g.) in graphical output. By + default, it has the value one, indicating that they should be + shown in the conventional sense (increasing left to right for an + abscissa, and bottom to top for an ordinate). If set to zero, + this attribute indicates that the direction should be reversed, + as would often be done for an astronomical magnitude or a right + ascension axis. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default Direction value supplied by the Frame class is 1, + indicating that all axes should be displayed in the + conventional direction. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Direction value to + suggest that certain axes (e.g. right ascension) should be + plotted in reverse when appropriate. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Direction attribute of a FrameSet axis is the same as + that of its current Frame (as specified by the \htmlref{Current}{Current} + attribute). + } + \sstsubsection{ + \htmlref{Plot}{Plot} + }{ + The Direction attribute of the base Frame in a Plot is set to + indicate the sense of the two graphics axes, as implied by the + graphics bounding box supplied when the Plot was created. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + + \sstitem + The Direction attribute does not directly affect the behaviour + of the AST library. Instead, it serves as a hint to applications + programs about the orientation in which they may wish to display + any data associated with the Frame. Applications are free to + ignore this hint if they wish. + } + } +} +\sstroutine{ + Disco +}{ + PcdMap pincushion/barrel distortion coefficient +}{ + \sstdescription{ + This attribute specifies the pincushion/barrel distortion coefficient + used by a \htmlref{PcdMap}{PcdMap}. This coefficient is set when the PcdMap is created, + but may later be modified. If the attribute is cleared, its default + value is zero, which gives no distortion. For pincushion distortion, + the value should be positive. For barrel distortion, it should be + negative. + + Note that the forward transformation of a PcdMap applies the + distortion specified by this attribute and the inverse + transformation removes this distortion. If the PcdMap is inverted + (e.g. using \htmlref{astInvert}{astInvert}), then the forward transformation will + remove the distortion and the inverse transformation will apply + it. The distortion itself will still be given by the same value of + Disco. + + Note, the value of this attribute may changed only if the PcdMap + has no more than one reference. That is, an error is reported if the + PcdMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + PcdMap + }{ + All PcdMaps have this attribute. + } + } +} +\sstroutine{ + Domain +}{ + Coordinate system domain +}{ + \sstdescription{ + This attribute contains a string which identifies the physical + domain of the coordinate system that a \htmlref{Frame}{Frame} describes. + + The Domain attribute also controls how a Frame behaves when it is + used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) + Frame. It does this by specifying the Domain that the target + Frame should have in order to match the template. If the Domain + value in the template Frame is set, then only targets with the + same Domain value will be matched. If the template\texttt{'} s Domain + value is not set, however, then the target\texttt{'} s Domain will be + ignored. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default Domain value supplied by the Frame class is an + empty string. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Domain value to be + \texttt{"} SKY\texttt{"} . + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The CmpFrame class re-defines the default Domain value to be + of the form \texttt{"} $<$dom1$>$-$<$dom2$>$\texttt{"} , where $<$dom1$>$ and $<$dom2$>$ are the + Domains of the two component Frames. If both these Domains are + blank, then the string \texttt{"} CMP\texttt{"} is used as the default Domain name. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Domain attribute of a FrameSet is the same as that of its + current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + The SpecFrame class re-defines the default Domain value to be + \texttt{"} SPECTRUM\texttt{"} . + } + \sstsubsection{ + \htmlref{DSBSpecFrame}{DSBSpecFrame} + }{ + The DSBSpecFrame class re-defines the default Domain value to be + \texttt{"} DSBSPECTRUM\texttt{"} . + } + \sstsubsection{ + \htmlref{FluxFrame}{FluxFrame} + }{ + The FluxFrame class re-defines the default Domain value to be + \texttt{"} FLUX\texttt{"} . + } + \sstsubsection{ + \htmlref{SpecFluxFrame}{SpecFluxFrame} + }{ + The FluxFrame class re-defines the default Domain value to be + \texttt{"} SPECTRUM-FLUX\texttt{"} . + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class re-defines the default Domain value to be + \texttt{"} TIME\texttt{"} . + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + All Domain values are converted to upper case and white space + is removed before use. + } + } +} +\sstroutine{ + DrawAxes(axis) +}{ + Draw axes for a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether curves representing coordinate axes should be drawn. + It takes a separate value for each physical axis of a + \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} DrawAxes(2)=0\texttt{"} + specifies that no axis should be drawn for the second axis. + + If drawn, these axis lines will pass through any tick marks + associated with numerical labels drawn to mark values on the + axes. The location of these tick marks and labels (and hence the + axis lines) is determined by the Plot\texttt{'} s \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute. + + If the DrawAxes value of a Plot is non-zero (the default), then + axis lines will be drawn, otherwise they will be omitted. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + \htmlref{Axis}{Axis} lines are drawn independently of any coordinate grid + lines (see the \htmlref{Grid}{Grid} attribute) so grid lines may be used to + substitute for axis lines if required. + + \sstitem + In some circumstances, numerical labels and tick marks are + drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} + attribute). In this case, the value of the DrawAxes attribute + is ignored. + + \sstitem + If no axis is specified, (e.g. \texttt{"} DrawAxes\texttt{"} instead of + \texttt{"} DrawAxes(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the DrawAxes(1) value. + } + } +} +\sstroutine{ + DrawTitle +}{ + Draw a title for a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether a title is drawn. + + If the DrawTitle value of a \htmlref{Plot}{Plot} is non-zero (the default), then + the title will be drawn, otherwise it will be omitted. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + \sstsubsection{ + \htmlref{Plot3D}{Plot3D} + }{ + The Plot3D class ignores this attributes, assuming a value of + zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The text used for the title is obtained from the Plot\texttt{'} s \htmlref{Title}{Title} + attribute. + + \sstitem + The vertical placement of the title can be controlled using + the \htmlref{TitleGap}{TitleGap} attribute. + } + } +} +\sstroutine{ + Dut1 +}{ + The UT1-UTC correction +}{ + \sstdescription{ + This attribute is used when calculating the Local Apparent Sidereal + Time corresponding to \htmlref{SkyFrame}{SkyFrame}\texttt{'} s \htmlref{Epoch}{Epoch} value (used when converting + positions to or from the \texttt{"} AzEl\texttt{"} system). It should be set to the + difference, in seconds, between the UT1 and UTC timescales at the + moment in time represented by the SkyFrame\texttt{'} s Epoch attribute. The + value to use is unpredictable and depends on changes in the earth\texttt{'} s + rotation speed. Values for UT1-UTC can be obtained from the + International Earth Rotation and Reference Systems Service + (IERS) at http://www.iers.org/. + + Currently, the correction is always less than 1 second. This is + ensured by the occasional introduction of leap seconds into the UTC + timescale. Therefore no great error will usually result if no value + is assigned to this attribute (in which case a default value of + zero is used). However, it is possible that a decision may be taken + at some time in the future to abandon the introduction of leap + seconds, in which case the DUT correction could grow to significant + sizes. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + All Frames have this attribute. + } + } +} +\sstroutine{ + Edge(axis) +}{ + Which edges to label in a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + which edges of a \htmlref{Plot}{Plot} are used for displaying numerical and + descriptive axis labels. It takes a separate value for each + physical axis of the Plot so that, for instance, the setting + \texttt{"} Edge(2)=left\texttt{"} specifies which edge to use to display labels for + the second axis. + + The values \texttt{"} left\texttt{"} , \texttt{"} top\texttt{"} , \texttt{"} right\texttt{"} and \texttt{"} bottom\texttt{"} (or any + abbreviation) can be supplied for this attribute. The default is + usually \texttt{"} bottom\texttt{"} for the first axis and \texttt{"} left\texttt{"} for the second + axis. However, if exterior labelling was requested (see the + \htmlref{Labelling}{Labelling} attribute) but cannot be produced using these default + Edge values, then the default values will be swapped if this + enables exterior labelling to be produced. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + \sstsubsection{ + \htmlref{Plot3D}{Plot3D} + }{ + The Plot3D class ignores this attributes. Instead it uses its + own \htmlref{RootCorner}{RootCorner} attribute to determine which edges of the 3D plot + to label. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + In some circumstances, numerical labels will be drawn along + internal grid lines instead of at the edges of the plotting area + (see the Labelling attribute). In this case, the Edge attribute + only affects the placement of the descriptive labels (these are + drawn at the edges of the plotting area, rather than along the + axis lines). + } + } +} +\sstroutine{ + Encoding +}{ + System for encoding Objects as FITS headers +}{ + \sstdescription{ + This attribute specifies the encoding system to use when AST + Objects are stored as FITS header cards in a \htmlref{FitsChan}{FitsChan}. It + affects the behaviour of the \htmlref{astWrite}{astWrite} and \htmlref{astRead}{astRead} functions when + they are used to transfer any AST \htmlref{Object}{Object} to or from an external + representation consisting of FITS header cards (i.e. whenever a + write or read operation is performed using a FitsChan as the I/O + \htmlref{Channel}{Channel}). + + There are several ways (conventions) by which coordinate system + information may be represented in the form of FITS headers and + the Encoding attribute is used to specify which of these should + be used. The encoding options available are outlined in the + \texttt{"} Encodings Available\texttt{"} section below, and in more detail in the + sections which follow. + + Encoding systems differ in the range of possible Objects + (e.g. classes) they can represent, in the restrictions they + place on these Objects (e.g. compatibility with some + externally-defined coordinate system model) and in the number of + Objects that can be stored together in any particular set of + FITS header cards (e.g. multiple Objects, or only a single + Object). The choice of encoding also affects the range of + external applications which can potentially read and interpret + the FITS header cards produced. + + The encoding options available are not necessarily mutually + exclusive, and it may sometimes be possible to store multiple + Objects (or the same Object several times) using different + encodings within the same set of FITS header cards. This + possibility increases the likelihood of other applications being + able to read and interpret the information. + + By default, a FitsChan will attempt to determine which encoding + system is already in use, and will set the default Encoding + value accordingly (so that subsequent I/O operations adopt the + same conventions). It does this by looking for certain critical + FITS keywords which only occur in particular encodings. For + details of how this works, see the \texttt{"} Choice of Default Encoding\texttt{"} + section below. If you wish to ensure that a particular encoding + system is used, independently of any FITS cards already present, + you should set an explicit Encoding value yourself. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } + \sstdiytopic{ + Encodings Available + }{ + The Encoding attribute can take any of the following (case + insensitive) string values to select the corresponding encoding + + system: + + \sstitemlist{ + + \sstitem + \texttt{"} DSS\texttt{"} : Encodes coordinate system information in FITS header + cards using the convention developed at the Space Telescope + Science Institute (STScI) for the Digitised Sky Survey (DSS) + astrometric plate calibrations. The main advantages of this + encoding are that FITS images which use it are widely available + and it is understood by a number of important and + well-established astronomy applications. For further details, + see the section \texttt{"} The DSS Encoding\texttt{"} below. + + \sstitem + \texttt{"} FITS-WCS\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions described in the FITS + world coordinate system (FITS-WCS) papers by E.W. Greisen, + M. Calabretta, et al. The main advantages of this encoding are that + it should be understood by any FITS-WCS compliant application and + is likely to be adopted widely for FITS data in future. For further + details, see the section \texttt{"} The FITS-WCS Encoding\texttt{"} below. + + \sstitem + \texttt{"} FITS-PC\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions described in an earlier draft + of the FITS world coordinate system papers by E.W. Greisen and + M. Calabretta. This encoding uses a combination of CDELTi and + PCiiijjj keywords to describe the scale and rotation of the pixel + axes. This encoding is included to support existing data and + software which uses these now superceded conventions. In general, + the \texttt{"} FITS-WCS\texttt{"} encoding (which uses CDi\_j or PCi\_j keywords to + describe the scale and rotation) should be used in preference to + \texttt{"} FITS-PC\texttt{"} . + + \sstitem + \texttt{"} FITS-IRAF\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions described in the document + \texttt{"} World Coordinate Systems Representations Within the FITS + Format\texttt{"} by R.J. Hanisch and D.G. Wells, 1988. This encoding is + currently employed by the IRAF data analysis facility, so its + use will facilitate data exchange with IRAF. Its main advantages + are that it is a stable convention which approximates to a + subset of the propsed FITS-WCS encoding (above). This makes it + suitable as an interim method for storing coordinate system + information in FITS headers until the FITS-WCS encoding becomes + stable. Since many datasets currently use the FITS-IRAF + encoding, conversion of data from FITS-IRAF to the final form of + FITS-WCS is likely to be well supported. + + \sstitem + \texttt{"} FITS-AIPS\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions originally introduced by the + AIPS data analysis facility. This is base on the use of CDELTi and + CROTAi keuwords to desribe the scale and rotation of each axis. + These conventions have been superceded but are still widely used. + + \sstitem + \texttt{"} FITS-AIPS$+$$+$\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions used by the AIPS$+$$+$ project. + This is an extension of FITS-AIPS which includes some of the + features of FITS-IRAF and FITS-PC. + + \sstitem + \texttt{"} FITS-CLASS\texttt{"} : Encodes coordinate system information in FITS + header cards using the conventions used by the CLASS project. + CLASS is a software package for reducing single-dish radio and + sub-mm spectroscopic data. See the section \texttt{"} CLASS FITS format\texttt{"} at + http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/. + + \sstitem + \texttt{"} NATIVE\texttt{"} : Encodes AST Objects in FITS header cards using a + convention which is private to the AST library (but adheres to + the general FITS standard) and which uses FITS keywords that + will not clash with other encoding systems. The main advantages + of this are that any class of AST Object may be encoded, and any + (reasonable) number of Objects may be stored sequentially in the + same FITS header. This makes FITS headers an almost loss-less + communication path for passing AST Objects between applications + (although all such applications must, of course, make use of the + AST library to interpret the information). For further details, + see the section \texttt{"} The NATIVE Encoding\texttt{"} below. + } + } + \sstdiytopic{ + Choice of Default Encoding + }{ + If the Encoding attribute of a FitsChan is not set, the default + value it takes is determined by the presence of certain critical + FITS keywords within the FitsChan. The sequence of decisions + + used to arrive at the default value is as follows: + + \sstitemlist{ + + \sstitem + If the FitsChan contains any keywords beginning with the + string \texttt{"} BEGAST\texttt{"} , then NATIVE encoding is used, + + \sstitem + Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV + keyword and a keyword of the form VELO-xxx, where xxx indicates one + of the rest frames used by class (e.g. \texttt{"} VELO-LSR\texttt{"} ), or \texttt{"} VLSR\texttt{"} . + + \sstitem + Otherwise, if the FitsChan contains a CTYPE keyword which + represents a spectral axis using the conventions of the AIPS and + AIPS$+$$+$ projects (e.g. \texttt{"} FELO-LSR\texttt{"} , etc), then one of FITS-AIPS or + FITS-AIPS$+$$+$ encoding is used. FITS-AIPS$+$$+$ is used if any of the + keywords CDi\_j, PROJP, LONPOLE or LATPOLE are + found in the FitsChan. Otherwise FITS-AIPS is used. + + \sstitem + Otherwise, if the FitsChan contains a keyword of the form + \texttt{"} PCiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then + FITS-PC encoding is used, + + \sstitem + Otherwise, if the FitsChan contains a keyword of the form + \texttt{"} CDiiijjj\texttt{"} , where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then + FITS-IRAF encoding is used, + + \sstitem + Otherwise, if the FitsChan contains a keyword of the form + \texttt{"} CDi\_j\texttt{"} , and at least one of RADECSYS, PROJPi, or CjVALi + where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, then FITS-IRAF encoding is + used. + + \sstitem + Otherwise, if the FitsChan contains any keywords of the form + PROJPi, CjVALi or RADECSYS, where \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits, + then FITS-PC encoding is used. + + \sstitem + Otherwise, if the FitsChan contains a keyword of the form + CROTAi, where \texttt{"} i\texttt{"} is a single digit, then FITS-AIPS encoding is + used. + + \sstitem + Otherwise, if the FitsChan contains a keyword of the form + CRVALi, where \texttt{"} i\texttt{"} is a single digit, then FITS-WCS encoding is + used. + + \sstitem + Otherwise, if the FitsChan contains the \texttt{"} PLTRAH\texttt{"} keyword, then + DSS encoding is used, + + \sstitem + Otherwise, if none of these conditions is met (as would be the + case when using an empty FitsChan), then NATIVE encoding is + used. + + } + Except for the NATIVE and DSS encodings, all the above checks + also require that the header contains at least one CTYPE, CRPIX and + CRVAL keyword (otherwise the checking process continues to the next + case). + + Setting an explicit value for the Encoding attribute always + over-rides this default behaviour. + + Note that when writing information to a FitsChan, the choice of + encoding will depend greatly on the type of application you + expect to be reading the information in future. If you do not + know this, there may sometimes be an advantage in writing the + information several times, using a different encoding on each + occasion. + } + \sstdiytopic{ + The DSS Encoding + }{ + The DSS encoding uses FITS header cards to store a multi-term + polynomial which relates pixel positions on a digitised + photographic plate to celestial coordinates (right ascension and + declination). This encoding may only be used to store a single + AST Object in any set of FITS header cards, and that Object must + be a \htmlref{FrameSet}{FrameSet} which conforms to the STScI/DSS coordinate system + model (this means the \htmlref{Mapping}{Mapping} which relates its base and current + Frames must include either a \htmlref{DssMap}{DssMap} or a \htmlref{WcsMap}{WcsMap} with type + AST\_\_TAN or AST\_\_TPN). + + When reading a DSS encoded Object (using astRead), the FitsChan + concerned must initially be positioned at the first card (its + \htmlref{Card}{Card} attribute must equal 1) and the result of the read, if + successful, will always be a pointer to a FrameSet. The base + \htmlref{Frame}{Frame} of this FrameSet represents DSS pixel coordinates, and the + current Frame represents DSS celestial coordinates. Such a read + is always destructive and causes the FITS header cards required + for the construction of the FrameSet to be removed from the + FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A + subsequent read using the same encoding will therefore not + return another FrameSet, even if the FitsChan is rewound. + + When astWrite is used to store a FrameSet using DSS encoding, + an attempt is first made to simplify the FrameSet to see if it + conforms to the DSS model. Specifically, the current Frame must + be a FK5 \htmlref{SkyFrame}{SkyFrame}; the projection must be a tangent plane + (gnomonic) projection with polynomial corrections conforming to + DSS requirements, and north must be parallel to the second base + Frame axis. + + If the simplification process succeeds, a description of the + FrameSet is written to the FitsChan using appropriate DSS FITS + header cards. The base Frame of the FrameSet is used to form the + DSS pixel coordinate system and the current Frame gives the DSS + celestial coordinate system. A successful write operation will + over-write any existing DSS encoded data in the FitsChan, but + will not affect other (non-DSS) header cards. If a destructive + read of a DSS encoded Object has previously occurred, then an + attempt will be made to store the FITS header cards back in + their original locations. + + If an attempt to simplify a FrameSet to conform to the DSS model + fails (or if the Object supplied is not a FrameSet), then no + data will be written to the FitsChan and astWrite will return + zero. No error will result. + } + \sstdiytopic{ + The FITS-WCS Encoding + }{ + The FITS-WCS convention uses FITS header cards to describe the + relationship between pixels in an image (not necessarily + 2-dimensional) and one or more related \texttt{"} world coordinate systems\texttt{"} . + The FITS-WCS encoding may only be used to store a single AST Object + in any set of FITS header cards, and that Object must be a FrameSet + which conforms to the FITS-WCS model (the FrameSet may, however, + contain multiple Frames which will be result in multiple FITS + \texttt{"} alternate axis descriptions\texttt{"} ). Details of the use made by this + Encoding of the conventions described in the FITS-WCS papers are + given in the appendix \texttt{"} FITS-WCS Coverage\texttt{"} of this document. A few + main points are described below. + + The rotation and scaling of the intermediate world coordinate system + can be specified using either \texttt{"} CDi\_j\texttt{"} keywords, or \texttt{"} PCi\_j\texttt{"} together + with \texttt{"} CDELTi\texttt{"} keywords. When writing a FrameSet to a FitsChan, the + the value of the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan determines + which system is used. + + In addition, this encoding supports the \texttt{"} TAN with polynomial correction + terms\texttt{"} projection which was included in a draft of the FITS-WCS paper, + but was not present in the final version. A \texttt{"} TAN with polynomial + correction terms\texttt{"} projection is represented using a WcsMap with type + AST\_\_TPN (rather than AST\_\_TAN which is used to represent simple + TAN projections). When reading a FITS header, a CTYPE keyword value + including a \texttt{"} -TAN\texttt{"} code results in an AST\_\_TPN projection if there are + any projection parameters (given by the \htmlref{PVi\_m}{PVi\_m} keywords) associated with + the latitude axis, or if there are projection parameters associated + with the longitude axis for m greater than 4. When writing a + FrameSet to a FITS header, an AST\_\_TPN projection gives rise to a + CTYPE value including the normal \texttt{"} -TAN\texttt{"} code, but the projection + parameters are stored in keywords with names \texttt{"} QVi\_m\texttt{"} , instead of the + usual \texttt{"} PVi\_m\texttt{"} . Since these QV parameters are not part of the + FITS-WCS standard they will be ignored by other non-AST software, + resulting in the WCS being interpreted as a simple TAN projection + without any corrections. This should be seen as an interim solution + until such time as an agreed method for describing projection + distortions within FITS-WCS has been published. + + AST extends the range of celestial coordinate systems which may be + described using this encoding by allowing the inclusion of + \texttt{"} AZ--\texttt{"} and \texttt{"} EL--\texttt{"} as the coordinate specification within CTYPE + values. These form a longitude/latitude pair of axes which describe + azimuth and elevation. The geographic position of the observer + should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS + paper III. Currently, a simple model is used which includes diurnal + aberration, but ignores atmospheric refraction, polar motion, etc. + These may be added in a later release. + + If an AST SkyFrame that represents offset rather than absolute + coordinates (see attribute \htmlref{SkyRefIs}{SkyRefIs}) is written to a FitsChan using + FITS-WCS encoding, two alternate axis descriptions will be created. + One will describe the offset coordinates, and will use \texttt{"} OFLN\texttt{"} and + \texttt{"} OFLT\texttt{"} as the axis codes in the CTYPE keywords. The other will + describe absolute coordinates as specified by the \htmlref{System}{System} attribute + of the SkyFrame, using the usual CTYPE codes (\texttt{"} RA--\texttt{"} /\texttt{"} DEC-\texttt{"} , etc). + In addition, the absolute coordinates description will contain + AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the + header to be read back into AST in order to reconstruct the original + SkyFrame. + + When reading a FITS-WCS encoded Object (using astRead), the FitsChan + concerned must initially be positioned at the first card (its + Card attribute must equal 1) and the result of the read, if + successful, will always be a pointer to a FrameSet. The base + Frame of this FrameSet represents FITS-WCS pixel coordinates, + and the current Frame represents the physical coordinate system + described by the FITS-WCS primary axis descriptions. If + secondary axis descriptions are also present, then the FrameSet + may contain additional (non-current) Frames which represent + these. Such a read is always destructive and causes the FITS + header cards required for the construction of the FrameSet to be + removed from the FitsChan, which is then left positioned at the + \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will + therefore not return another FrameSet, even if the FitsChan is + rewound. + + When astWrite is used to store a FrameSet using FITS-WCS + encoding, an attempt is first made to simplify the FrameSet to + see if it conforms to the FITS-WCS model. If this simplification + process succeeds (as it often should, as the model is reasonably + flexible), a description of the FrameSet is written to the + FitsChan using appropriate FITS header cards. The base Frame of + the FrameSet is used to form the FITS-WCS pixel coordinate + system and the current Frame gives the physical coordinate + system to be described by the FITS-WCS primary axis + descriptions. Any additional Frames in the FrameSet may be used + to construct secondary axis descriptions, where appropriate. + + A successful write operation will over-write any existing + FITS-WCS encoded data in the FitsChan, but will not affect other + (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS + encoded Object has previously occurred, then an attempt will be + made to store the FITS header cards back in their original + locations. Otherwise, the new cards will be inserted following + any other FITS-WCS related header cards present or, failing + that, in front of the current card (as given by the Card + attribute). + + If an attempt to simplify a FrameSet to conform to the FITS-WCS + model fails (or if the Object supplied is not a FrameSet), then + no data will be written to the FitsChan and astWrite will + return zero. No error will result. + } + \sstdiytopic{ + The FITS-IRAF Encoding + }{ + The FITS-IRAF encoding can, for most purposes, be considered as + a subset of the FITS-WCS encoding (above), although it differs + in the details of the FITS keywords used. It is used in exactly + the same way and has the same restrictions, but with the + + addition of the following: + + \sstitemlist{ + + \sstitem + The only celestial coordinate systems that may be represented + are equatorial, galactic and ecliptic, + + \sstitem + Sky projections can be represented only if any associated + projection parameters are set to their default values. + + \sstitem + Secondary axis descriptions are not supported, so when writing + a FrameSet to a FitsChan, only information from the base and + current Frames will be stored. + + } + Note that this encoding is provided mainly as an interim measure to + provide a more stable alternative to the FITS-WCS encoding until the + FITS standard for encoding WCS information is finalised. The name + \texttt{"} FITS-IRAF\texttt{"} indicates the general keyword conventions used and does + not imply that this encoding will necessarily support all features of + the WCS scheme used by IRAF software. Nevertheless, an attempt has + been made to support a few such features where they are known to be + used by important sources of data. + + When writing a FrameSet using the FITS-IRAF encoding, axis rotations + are specified by a matrix of FITS keywords of the form \texttt{"} CDi\_j\texttt{"} , where + \texttt{"} i\texttt{"} and \texttt{"} j\texttt{"} are single digits. The alternative form \texttt{"} CDiiijjj\texttt{"} , which + is also in use, is recognised when reading an Object, but is never + written. + + In addition, the experimental IRAF \texttt{"} ZPX\texttt{"} and \texttt{"} TNX\texttt{"} sky projections will + be accepted when reading, but will never be written (the corresponding + FITS \texttt{"} ZPN\texttt{"} or \texttt{"} distorted TAN\texttt{"} projection being used instead). However, + there are restrictions on the use of these experimental projections. + For \texttt{"} ZPX\texttt{"} , longitude and latitude correction surfaces (appearing as + \texttt{"} lngcor\texttt{"} or \texttt{"} latcor\texttt{"} terms in the IRAF-specific \texttt{"} WAT\texttt{"} keywords) are + not supported. For \texttt{"} TNX\texttt{"} projections, only cubic surfaces encoded as + simple polynomials with \texttt{"} half cross-terms\texttt{"} are supported. If an + un-usable \texttt{"} TNX\texttt{"} or \texttt{"} ZPX\texttt{"} projection is encountered while reading + from a FitsChan, a simpler form of TAN or ZPN projection is used + which ignores the unsupported features and may therefore be + inaccurate. If this happens, a warning message is added to the + contents of the FitsChan as a set of cards using the keyword \texttt{"} ASTWARN\texttt{"} . + + You should not normally attempt to mix the foreign FITS encodings within + the same FitsChan, since there is a risk that keyword clashes may occur. + } + \sstdiytopic{ + The FITS-PC Encoding + }{ + The FITS-PC encoding can, for most purposes, be considered as + equivalent to the FITS-WCS encoding (above), although it differs + in the details of the FITS keywords used. It is used in exactly + the same way and has the same restrictions. + } + \sstdiytopic{ + The FITS-AIPS Encoding + }{ + The FITS-AIPS encoding can, for most purposes, be considered as + equivalent to the FITS-WCS encoding (above), although it differs + in the details of the FITS keywords used. It is used in exactly + the same way and has the same restrictions, but with the + + addition of the following: + + \sstitemlist{ + + \sstitem + The only celestial coordinate systems that may be represented + are equatorial, galactic and ecliptic, + + \sstitem + Spectral axes can only be represented if they represent + frequency, radio velocity or optical velocity, and are linearly + sampled in frequency. In addition, the standard of rest + must be LSRK, LSRD, barycentric or geocentric. + + \sstitem + Sky projections can be represented only if any associated + projection parameters are set to their default values. + + \sstitem + The AIT, SFL and MER projections can only be written if the CRVAL + keywords are zero for both longitude and latitude axes. + + \sstitem + Secondary axis descriptions are not supported, so when writing + a FrameSet to a FitsChan, only information from the base and + current Frames will be stored. + + \sstitem + If there are more than 2 axes in the base and current Frames, any + rotation must be restricted to the celestial plane, and must involve + no shear. + } + } + \sstdiytopic{ + The FITS-AIPS$+$$+$ Encoding + }{ + The FITS-AIPS$+$$+$ encoding is based on the FITS-AIPS encoding, but + includes some features of the FITS-IRAF and FITS-PC encodings. + Specifically, any celestial projections supported by FITS-PC may be + used, including those which require parameterisation, and the axis + rotation and scaling may be specified using CDi\_j keywords. When + writing a FITS header, rotation will be specified using CROTA/CDELT + keywords if possible, otherwise CDi\_j keywords will be used instead. + } + \sstdiytopic{ + The FITS-CLASS Encoding + }{ + The FITS-CLASS encoding uses the conventions of the CLASS project. + These are described in the section \texttt{"} Developer Manual\texttt{"} /\texttt{"} CLASS FITS + + Format\texttt{"} contained in the CLASS documentation at: + + http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html. + + This encoding is similar to FITS-AIPS with the following restrictions: + + \sstitemlist{ + + \sstitem + When a \htmlref{SpecFrame}{SpecFrame} is created by reading a FITS-CLASS header, the + attributes describing the observer\texttt{'} s position (\htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon} and + \htmlref{ObsAlt}{ObsAlt}) are left unset because the CLASS encoding does not specify + these values. Conversions to or from the topocentric standard of rest + will therefore be inaccurate (typically by up to about 0.5 km/s) + unless suitable values are assigned to these attributes after the + FrameSet has been created. + + \sstitem + When writing a FrameSet to a FITS-CLASS header, the current Frame + in the FrameSet must have at least 3 WCS axes, of which one must be + a linear spectral axis. The spectral axis in the created header will + always describe frequency. If the spectral axis in the supplied + FrameSet refers to some other system (e.g. radio velocity, etc), + then it will be converted to frequency. + + \sstitem + There must be a pair of celestial axes - either (RA,Dec) or + (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000. + + \sstitem + A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN) + can be used. For AIT and SFL, the reference point must be at the + origin of longitude and latitude. For SIN, the associated projection + parameters must both be zero. + + \sstitem + No rotation of the celestial axes is allowed, unless the spatial + axes are degenerate (i.e. cover only a single pixel). + + \sstitem + The frequency axis in the created header will always describe + frequency in the source rest frame. If the supplied FrameSet uses + some other standard of rest then suitable conversion will be applied. + + \sstitem + The source velocity must be defined. In other words, the SpecFrame + attributes \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} must have been assigned values. + + \sstitem + The frequency axis in a FITS-CLASS header does not represent + absolute frequency, but instead represents offsets from the rest + frequency in the standard of rest of the source. + + } + When writing a FrameSet out using FITS-CLASS encoding, the current + Frame may be temporarily modified if this will allow the header + to be produced. If this is done, the associated pixel-$>$WCS Mapping + will also be modified to take account of the changes to the Frame. + The modifications performed include re-ordering axes (WCS axes, not + pixel axes), changing spectral coordinate system and standard of + rest, changing the celestial coordinate system and reference equinox, + and changing axis units. + } + \sstdiytopic{ + The NATIVE Encoding + }{ + The NATIVE encoding may be used to store a description of any + class of AST Object in the form of FITS header cards, and (for + most practical purposes) any number of these Object descriptions + may be stored within a single set of FITS cards. If multiple + Object descriptions are stored, they are written and read + sequentially. The NATIVE encoding makes use of unique FITS + keywords which are designed not to clash with keywords that have + already been used for other purposes (if a potential clash is + detected, an alternative keyword is constructed to avoid the + clash). + + When reading a NATIVE encoded object from a FitsChan (using + astRead), FITS header cards are read, starting at the current + card (as determined by the Card attribute), until the start of + the next Object description is found. This description is then + read and converted into an AST Object, for which a pointer is + returned. Such a read is always destructive and causes all the + FITS header cards involved in the Object description to be + removed from the FitsChan, which is left positioned at the + following card. + + The Object returned may be of any class, depending on the + description that was read, and other AST routines may be used to + validate it (for example, by examining its \htmlref{Class}{Class} or \htmlref{ID}{ID} attribute + using astGetC). If further NATIVE encoded Object descriptions + exist in the FitsChan, subsequent calls to astRead will return + the Objects they describe in sequence (and destroy their + descriptions) until no more remain between the current card and + the \texttt{"} end-of-file\texttt{"} . + + When astWrite is used to write an Object using NATIVE encoding, + a description of the Object is inserted immediately before the + current card (as determined by the Card attribute). Multiple + Object descriptions may be written in this way and are stored + separately (and sequentially if the Card attribute is not + modified between the writes). A write operation using the NATIVE + encoding does not over-write previously written Object + descriptions. Note, however, that subsequent behaviour is + undefined if an Object description is written inside a + previously-written description, so this should be avoided. + + When an Object is written to a FitsChan using NATIVE encoding, + astWrite should (barring errors) always transfer data and + return a value of 1. + } +} +\sstroutine{ + Epoch +}{ + Epoch of observation +}{ + \sstdescription{ + This attribute is used to qualify the coordinate systems described by + a \htmlref{Frame}{Frame}, by giving the moment in time when the coordinates are known + to be correct. Often, this will be the date of observation, and is + important in cases where coordinates systems move with respect to each + other over the course of time. + + The Epoch attribute is stored as a Modified Julian Date, but + when setting its value it may be given in a variety of + formats. See the \texttt{"} Input Formats\texttt{"} section (below) for details. + Strictly, the Epoch value should be supplied in the TDB timescale, + but for some purposes (for instance, for converting sky positions + between different types of equatorial system) the timescale is not + significant, and UTC may be used. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. The basic Frame class provides + a default of J2000.0 (Julian) but makes no use of the Epoch value. + This is because the Frame class does not distinguish between + different Cartesian coordinate systems (see the \htmlref{System}{System} attribute). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The default Epoch value for a CmpFrame is selected as follows; + if the Epoch attribute has been set in the first component Frame + then the Epoch value from the first component Frame is used as + the default for the CmpFrame. Otherwise, if the Epoch attribute has + been set in the second component Frame then the Epoch value from the + second component Frame is used as the default for the CmpFrame. + Otherwise, the default Epoch value from the first component + Frame is used as the default for the CmpFrame. When the Epoch + attribute of a CmpFrame is set or cleared, it is also set or + cleared in the two component Frames. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Epoch attribute of a FrameSet is the same as that of its current + Frame (as specified by the \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The coordinates of sources within a SkyFrame can changed with time + for various reasons, including: (i) changing aberration of light + caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion + around the Sun), (ii) changing gravitational deflection by the Sun + due to changes in the observer\texttt{'} s position with time, (iii) fictitious + motion due to rotation of non-inertial coordinate systems (e.g. the + old FK4 system), and (iv) proper motion of the source itself (although + this last effect is not handled by the SkyFrame class because it + affects individual sources rather than the coordinate system as + a whole). + + The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the + old FK4-based coordinate systems (see the System attribute) and + J2000.0 (Julian) for all others. + + Care must be taken to distinguish the Epoch value, which relates to + motion (or apparent motion) of the source, from the superficially + similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate + system which is itself in motion in a (notionally) predictable way + as a result of being referred to a slowly moving reference plane + (e.g. the equator). + + See the description of the System attribute for details of which + qualifying attributes apply to each celestial coordinate system. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + A TimeFrame describes a general time axis and so cannot be completely + characterised by a single Epoch value. For this reason the TimeFrame + class makes no use of the Epoch attribute. However, user code can + still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"} + time spanned by the TimeFrame. The default Epoch value for a TimeFrame + will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s + \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin, + then the default Epoch value is J2000.0. + } + } + \sstdiytopic{ + Input Formats + }{ + The formats accepted when setting an Epoch value are listed + below. They are all case-insensitive and are generally tolerant + of extra white space and alternative field delimiters: + + \sstitemlist{ + + \sstitem + Besselian Epoch: Expressed in decimal years, with or without + decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). + + \sstitem + Julian Epoch: Expressed in decimal years, with or without + decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). + + \sstitem + Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"} + for example). Such values are interpreted as a Besselian epoch + (see above) if less than 1984.0 and as a Julian epoch otherwise. + + \sstitem + Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for + example). + + \sstitem + Modified Julian Date: With or without decimal places + (\texttt{"} MJD 54321.4\texttt{"} for example). + + \sstitem + Gregorian Calendar Date: With the month expressed either as an + integer or a 3-character abbreviation, and with optional decimal + places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or + \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is + given, the time refers to the start of the day (zero hours). + + \sstitem + Gregorian Date and Time: Any calendar date (as above) but with + a fraction of a day expressed as hours, minutes and seconds + (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be + separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). + } + } + \sstdiytopic{ + Output Format + }{ + When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"} + format described under \texttt{"} Input Formats\texttt{"} . This is a value in + decimal years which will be a Besselian epoch if less than + 1984.0 and a Julian epoch otherwise. By omitting any character + prefix, this format allows the Epoch value to be obtained as + either a character string or a floating point value. + } +} +\sstroutine{ + Equinox +}{ + Epoch of the mean equinox +}{ + \sstdescription{ + This attribute is used to qualify those celestial coordinate + systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on + the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun) + and/or the Earth\texttt{'} s equator. + + Both of these planes are in motion and their positions are + difficult to specify precisely. In practice, therefore, a model + ecliptic and/or equator are used instead. These, together with + the point on the sky that defines the coordinate origin (the + intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move + with time according to some model which removes the more rapid + fluctuations. The SkyFrame class supports both the FK4 and + FK5 models. + + The position of a fixed source expressed in any of these + coordinate systems will appear to change with time due to + movement of the coordinate system itself (rather than motion of + the source). Such coordinate systems must therefore be + qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"} + or \texttt{"} equinox\texttt{"} for short) which allows the position of the model + coordinate system on the sky to be determined. This is the role + of the Equinox attribute. + + The Equinox attribute is stored as a Modified Julian Date, but + when setting or getting its value you may use the same formats + as for the \htmlref{Epoch}{Epoch} attribute (q.v.). + + The default Equinox value is B1950.0 (Besselian) for the old + FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and + J2000.0 (Julian) for all others. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Care must be taken to distinguish the Equinox value, which + relates to the definition of a time-dependent coordinate system + (based on solar system reference planes which are in motion), + from the superficially similar Epoch value. The latter is used + to qualify coordinate systems where the positions of sources + change with time (or appear to do so) for a variety of other + reasons, such as aberration of light caused by the observer\texttt{'} s + motion, etc. + + \sstitem + See the description of the System attribute for details of + which qualifying attributes apply to each celestial coordinate + system. + } + } +} +\sstroutine{ + Escape +}{ + Allow changes of character attributes within strings? +}{ + \sstdescription{ + This attribute controls the appearance of text strings and numerical + labels drawn by the \htmlref{astGrid}{astGrid} and (for the \htmlref{Plot}{Plot} class) \htmlref{astText}{astText} functions, + by determining if any escape sequences contained within the strings + should be used to control the appearance of the text, or should + be printed literally. Note, the \htmlref{Plot3D}{Plot3D} class only interprets escape + sequences within the + astGrid function. + + If the Escape value of a Plot is one (the default), then any + escape sequences in text strings produce the effects described + below when printed. Otherwise, they are printed literally. + + See also the \htmlref{astEscapes}{astEscapes} function. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstdiytopic{ + Escape Sequences + }{ + Escape sequences are introduced into the text string by a percent + \texttt{"} \%\texttt{"} character. Any unrecognised, illegal or incomplete escape sequences + are printed literally. The following escape sequences are + currently recognised (\texttt{"} ...\texttt{"} represents a string of one or more + decimal digits): + + \%\% - Print a literal \texttt{"} \%\texttt{"} character. + + \%$\wedge$...$+$ - Draw subsequent characters as super-scripts. The digits + \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} + text to the base-line of the super-script text, scaled + so that a value of \texttt{"} 100\texttt{"} corresponds to the height of + \texttt{"} normal\texttt{"} text. + \%$\wedge$$+$ - Draw subsequent characters with the normal base-line. + + \%v...$+$ - Draw subsequent characters as sub-scripts. The digits + \texttt{"} ...\texttt{"} give the distance from the base-line of \texttt{"} normal\texttt{"} + text to the base-line of the sub-script text, scaled + so that a value of \texttt{"} 100\texttt{"} corresponds to the height of + \texttt{"} normal\texttt{"} text. + + \%v$+$ - Draw subsequent characters with the normal base-line + (equivalent to \%$\wedge$$+$). + + \%$>$...$+$ - Leave a gap before drawing subsequent characters. + The digits \texttt{"} ...\texttt{"} give the size of the gap, scaled + so that a value of \texttt{"} 100\texttt{"} corresponds to the height of + \texttt{"} normal\texttt{"} text. + + \%$<$...$+$ - Move backwards before drawing subsequent characters. + The digits \texttt{"} ...\texttt{"} give the size of the movement, scaled + so that a value of \texttt{"} 100\texttt{"} corresponds to the height of + \texttt{"} normal\texttt{"} text. + + \%s...$+$ - Change the Size attribute for subsequent characters. The + digits \texttt{"} ...\texttt{"} give the new Size as a fraction of the + \texttt{"} normal\texttt{"} Size, scaled so that a value of \texttt{"} 100\texttt{"} corresponds + to 1.0; + + \%s$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. + + \%w...$+$ - Change the Width attribute for subsequent characters. The + digits \texttt{"} ...\texttt{"} give the new width as a fraction of the + \texttt{"} normal\texttt{"} Width, scaled so that a value of \texttt{"} 100\texttt{"} corresponds + to 1.0; + + \%w$+$ - Reset the Size attribute to its \texttt{"} normal\texttt{"} value. + + \%f...$+$ - Change the Font attribute for subsequent characters. The + digits \texttt{"} ...\texttt{"} give the new Font value. + + \%f$+$ - Reset the Font attribute to its \texttt{"} normal\texttt{"} value. + + \%c...$+$ - Change the Colour attribute for subsequent characters. The + digits \texttt{"} ...\texttt{"} give the new Colour value. + + \%c$+$ - Reset the Colour attribute to its \texttt{"} normal\texttt{"} value. + + \%t...$+$ - Change the Style attribute for subsequent characters. The + digits \texttt{"} ...\texttt{"} give the new Style value. + + \%t$+$ - Reset the Style attribute to its \texttt{"} normal\texttt{"} value. + + \%h$+$ - Remember the current horizontal position (see \texttt{"} \%g$+$\texttt{"} ) + + \%g$+$ - Go to the horizontal position of the previous \texttt{"} \%h$+$\texttt{"} (if any). + + \%- - Push the current graphics attribute values onto the top of + the stack (see \texttt{"} \%$+$\texttt{"} ). + + \%$+$ - Pop attributes values of the top the stack (see \texttt{"} \%-\texttt{"} ). If + the stack is empty, \texttt{"} normal\texttt{"} attribute values are restored. + } +} +\sstroutine{ + FillFactor +}{ + Fraction of the Region which is of interest +}{ + \sstdescription{ + This attribute indicates the fraction of the \htmlref{Region}{Region} which is of + interest. AST does not use this attribute internally for any purpose. + Typically, it could be used to indicate the fraction of the Region for + which data is available. + + The supplied value must be in the range 0.0 to 1.0, and the default + value is 1.0 (except as noted below). + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + \sstsubsection{ + \htmlref{CmpRegion}{CmpRegion} + }{ + The default FillFactor for a CmpRegion is the FillFactor of its + first component Region. + } + \sstsubsection{ + \htmlref{Prism}{Prism} + }{ + The default FillFactor for a Prism is the product of the + FillFactors of its two component Regions. + } + \sstsubsection{ + \htmlref{Stc}{Stc} + }{ + The default FillFactor for an Stc is the FillFactor of its + encapsulated Region. + } + } +} +\sstroutine{ + FitsAxisOrder +}{ + Frame title +}{ + \sstdescription{ + This attribute specifies the order for the WCS axes in any new + FITS-WCS headers created using the + \htmlref{astWrite}{astWrite} + method. + + The value of the FitsAxisOrder attribute can be either \texttt{"} $<$auto$>$\texttt{"} + (the default value), \texttt{"} $<$copy$>$\texttt{"} or a space-separated list of axis + symbols: + + \texttt{"} $<$auto$>$\texttt{"} : causes the WCS axis order to be chosen automatically so that + the i\texttt{'} th WCS axis in the new FITS header is the WCS axis which is + more nearly parallel to the i\texttt{'} th pixel axis. + + \texttt{"} $<$copy$>$\texttt{"} : causes the WCS axis order to be set so that the i\texttt{'} th WCS + axis in the new FITS header is the i\texttt{'} th WCS axis in the current + \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} being written out to the header. + + \texttt{"} Sym1 Sym2...\texttt{"} : the space-separated list is seached in turn for + the Symbol attribute of each axis in the current Frame of the + FrameSet. The order in which these Symbols occur within the + space-separated list defines the order of the WCS axes in the + new FITS header. An error is reported if Symbol for a current + Frame axis is not present in the supplied list. However, no error + is reported if the list contains extra words that do not correspond + to the Symbol of any current Frame axis. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + FitsDigits +}{ + Digits of precision for floating point FITS values +}{ + \sstdescription{ + This attribute gives the number of significant decimal digits to + use when formatting floating point values for inclusion in the + FITS header cards within a \htmlref{FitsChan}{FitsChan}. + + By default, a positive value is used which results in no loss of + information, assuming that the value\texttt{'} s precision is double. + Usually, this causes no problems. + + However, to adhere strictly to the recommendations of the FITS + standard, the width of the formatted value (including sign, + decimal point and exponent) ought not to be more than 20 + characters. If you are concerned about this, you should set + FitsDigits to a negative value, such as -15. In this case, the + absolute value ($+$15) indicates the maximum number of significant + digits to use, but the actual number used may be fewer than this + to ensure that the FITS recommendations are satisfied. When + using this approach, the resulting number of significant digits + may depend on the value being formatted and on the presence of + any sign, decimal point or exponent. + + The value of this attribute is effective when FITS header cards + are output, either using + \htmlref{astFindFits}{astFindFits} or by the action of the FitsChan\texttt{'} s sink function + when it is finally deleted. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Font(element) +}{ + Character font for a Plot element +}{ + \sstdescription{ + This attribute determines the character font index used when + drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It + takes a separate value for each graphical element so that, for + instance, the setting \texttt{"} Font(title)=2\texttt{"} causes the Plot title to + be drawn using font number 2. + + The range of integer font indices available and the appearance + of the resulting text is determined by the underlying graphics + system. The default behaviour is for all graphical elements to + be drawn using the default font supplied by this graphics + system. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of the graphical elements available, see the + description of the Plot class. + + \sstitem + If no graphical element is specified, (e.g. \texttt{"} Font\texttt{"} instead + of \texttt{"} Font(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will + affect the attribute value of all graphical elements, while a + \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Font(TextLab) + value. + } + } +} +\sstroutine{ + Format(axis) +}{ + Format specification for axis values +}{ + \sstdescription{ + This attribute specifies the format to be used when displaying + coordinate values associated with a particular \htmlref{Frame}{Frame} axis + (i.e. to convert values from binary to character form). It is + interpreted by the \htmlref{astFormat}{astFormat} function and determines the + formatting which it applies. + + If no Format value is set for a Frame axis, a default value is + supplied instead. This is based on the value of the Digits, or + Digits(axis), attribute and is chosen so that it displays the + requested number of digits of precision. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The Frame class interprets this attribute as a format + specification string to be passed to the C \texttt{"} printf\texttt{"} function + (e.g. \texttt{"} \%1.7G\texttt{"} ) in order to format a single coordinate value + (supplied as a double precision number). + + When supplying a value for this attribute, beware that the + \texttt{"} \%\texttt{"} character may be interpreted directly as a format + specification by some printf-like functions (such as + \htmlref{astSet}{astSet}). You may need to double it (i.e. use \texttt{"} \%\%\texttt{"} ) to avoid + this. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the syntax and default value of + the Format string to allow the formatting of sexagesimal + values as appropriate for the particular celestial coordinate + system being represented. The syntax of SkyFrame Format + strings is described (below) in the \texttt{"} SkyFrame Formats\texttt{"} + section. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Format attribute of a FrameSet axis is the same as that + of its current Frame (as specified by the \htmlref{Current}{Current} + attribute). Note that the syntax of the Format string is also + determined by the current Frame. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class extends the syntax of the Format string to + allow the formatting of TimeFrame axis values as Gregorian calendar + dates and times. The syntax of TimeFrame Format strings is described + (below) in the \texttt{"} TimeFrame Formats\texttt{"} section. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } + \sstdiytopic{ + SkyFrame Formats + }{ + The Format string supplied for a SkyFrame should contain zero or + more of the following characters. These may occur in any order, + but the following is recommended for clarity: + + \sstitemlist{ + + \sstitem + \texttt{"} $+$\texttt{"} : Indicates that a plus sign should be prefixed to positive + values. By default, no plus sign is used. + + \sstitem + \texttt{"} z\texttt{"} : Indicates that leading zeros should be prefixed to the + value so that the first field is of constant width, as would be + required in a fixed-width table (leading zeros are always + prefixed to any fields that follow). By default, no leading + zeros are added. + + \sstitem + \texttt{"} i\texttt{"} : Use the standard ISO field separator (a colon) between + fields. This is the default behaviour. + + \sstitem + \texttt{"} b\texttt{"} : Use a blank to separate fields. + + \sstitem + \texttt{"} l\texttt{"} : Use a letter (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} as appropriate) to + separate fields. + + \sstitem + \texttt{"} g\texttt{"} : Use a letter and symbols to separate fields (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} , + etc, as appropriate), but include escape sequences in the formatted + value so that the \htmlref{Plot}{Plot} class will draw the separators as small + super-scripts. + The default escape sequences are optimised for the pgplot graphics + package, but new escape sequences may be specified using function + astSetSkyDelim. + + \sstitem + \texttt{"} d\texttt{"} : Include a degrees field. Expressing the angle purely in + degrees is also the default if none of \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} , \texttt{"} s\texttt{"} or \texttt{"} t\texttt{"} are + given. + + \sstitem + \texttt{"} h\texttt{"} : Express the angle as a time and include an hours field + (where 24 hours correspond to 360 degrees). Expressing the angle + purely in hours is also the default if \texttt{"} t\texttt{"} is given without + either \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} . + + \sstitem + \texttt{"} m\texttt{"} : Include a minutes field. By default this is not included. + + \sstitem + \texttt{"} s\texttt{"} : Include a seconds field. By default this is not included. + This request is ignored if \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is given, unless a minutes + field is also included. + + \sstitem + \texttt{"} t\texttt{"} : Express the angle as a time (where 24 hours correspond to + 360 degrees). This option is ignored if either \texttt{"} d\texttt{"} or \texttt{"} h\texttt{"} is + given and is intended for use where the value is to be expressed + purely in minutes and/or seconds of time (with no hours + field). If \texttt{"} t\texttt{"} is given without \texttt{"} d\texttt{"} , \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} or \texttt{"} s\texttt{"} being + present, then it is equivalent to \texttt{"} h\texttt{"} . + + \sstitem + \texttt{"} .\texttt{"} : Indicates that decimal places are to be given for the + final field in the formatted string (whichever field this + is). The \texttt{"} .\texttt{"} should be followed immediately by an unsigned + integer which gives the number of decimal places required, or by an + asterisk. If an asterisk is supplied, a default number of decimal + places is used which is based on the value of the Digits + attribute. + + } + All of the above format specifiers are case-insensitive. If + several characters make conflicting requests (e.g. if both \texttt{"} i\texttt{"} + and \texttt{"} b\texttt{"} appear), then the character occurring last takes + precedence, except that \texttt{"} d\texttt{"} and \texttt{"} h\texttt{"} always override \texttt{"} t\texttt{"} . + + If the format string starts with a percentage sign (\%), then the + whole format string is assumed to conform to the syntax defined by + the Frame class, and the axis values is formated as a decimal + radians value. + } + \sstdiytopic{ + TimeFrame Formats + }{ + The Format string supplied for a TimeFrame should either use the + syntax defined by the base Frame class (i.e. a C \texttt{"} printf\texttt{"} format + string), or the extended \texttt{"} iso\texttt{"} syntax described below (the default + value is inherited from the Frame class): + + \sstitemlist{ + + \sstitem + C \texttt{"} printf\texttt{"} syntax: If the Format string is a C \texttt{"} printf\texttt{"} format + description such as \texttt{"} \%1.7G\texttt{"} , the TimeFrame axis value will be + formatted without change as a floating point value using this format. + The formatted string will thus represent an offset from the zero point + specified by the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute, measured in + units given by the TimeFrame\texttt{'} s Unit attribute. + + \sstitem + \texttt{"} iso\texttt{"} syntax: This is used to format a TimeFrame axis value as a + Gregorian date followed by an optional time of day. If the Format + value commences with the string \texttt{"} iso\texttt{"} then the TimeFrame axis value + will be converted to an absolute MJD, including the addition of the + current TimeOrigin value, and then formatted as a Gregorian date + using the format \texttt{"} yyyy-mm-dd\texttt{"} . Optionally, the Format value may + include an integer precision following the \texttt{"} iso\texttt{"} specification (e.g. + \texttt{"} iso.2\texttt{"} ), in which case the time of day will be appended to the + formatted date (if no time of day is included, the date field is + rounded to the nearest day). The integer value in the Format string + indicates the number of decimal places to use in the seconds field. For + instance, a Format value of \texttt{"} iso.0\texttt{"} produces a time of day of the form + \texttt{"} hh:mm:ss\texttt{"} , and a Format value of \texttt{"} iso.2\texttt{"} produces a time of day of the + form \texttt{"} hh:mm:ss.ss\texttt{"} . The date and time fields will be separated by a + space unless \texttt{'} T\texttt{'} is appended to the end of string, in which case + the letter T (upper case) will be used as the separator. The value of + the Digits attribute is ignored when using this \texttt{"} iso\texttt{"} format. + } + } +} +\sstroutine{ + Full +}{ + Set level of output detail +}{ + \sstdescription{ + This attribute is a three-state flag and takes values of -1, 0 + or $+$1. It controls the amount of information included in the + output generated by a \htmlref{Channel}{Channel}. + + If Full is zero, then a modest amount of + non-essential but useful information will be included in the + output. If Full is negative, all non-essential information will + be suppressed to minimise the amount of output, while if it is + positive, the output will include the maximum amount of detailed + information about the \htmlref{Object}{Object} being written. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + The default value is zero for a normal Channel. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + The default value is zero for a FitsChan. + } + \sstsubsection{ + \htmlref{XmlChan}{XmlChan} + }{ + The default value is -1 for an XmlChan. + } + \sstsubsection{ + \htmlref{StcsChan}{StcsChan} + }{ + The default value is zero for an StcsChan. Set a positive value + to cause default values to be included in STC-S descriptions. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + All positive values supplied for this attribute are converted + to $+$1 and all negative values are converted to -1. + } + } +} +\sstroutine{ + Gap(axis) +}{ + Interval between linearly spaced major axis values of a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the linear interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at + which (for example) major tick marks are drawn. It takes a separate + value for each physical axis of the Plot so that, for instance, + the setting \texttt{"} Gap(2)=3.0\texttt{"} specifies the difference between adjacent major + values along the second axis. The Gap attribute is only used when + the LogTicks attribute indicates that the spacing between major axis + values is to be linear. If major axis values are logarithmically spaced + then the gap is specified using attribute LogGap. + + The Gap value supplied will usually be rounded to the nearest + \texttt{"} nice\texttt{"} value, suitable (e.g.) for generating axis labels, before + use. To avoid this \texttt{"} nicing\texttt{"} you should set an explicit format + for the axis using the \htmlref{Format(axis)}{Format(axis)} or \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} + attribute. The default behaviour is for the Plot to generate its + own Gap value when required, based on the range of axis values + to be represented. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Gap value should use the same units as are used internally + for storing coordinate values on the corresponding axis. For + example, with a celestial coordinate system, the Gap value + should be in radians, not hours or degrees. + + \sstitem + If no axis is specified, (e.g. \texttt{"} Gap\texttt{"} instead of \texttt{"} Gap(2)\texttt{"} ), + then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute + value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation + will use just the Gap(1) value. + } + } +} +\sstroutine{ + Grf +}{ + Use Grf functions registered through astGrfSet? +}{ + \sstdescription{ + This attribute selects the functions which are used to draw graphics by + the \htmlref{Plot}{Plot} class. If it is zero, then the functions in the graphics + interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script). + Otherwise, functions registered using \htmlref{astGrfSet}{astGrfSet} are used. In this + case, if a function is needed which has not been registered, + then the function in the graphics interface selected at link-time is + used. + + The default is to use the graphics interface + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + \sstsubsection{ + \htmlref{Plot3D}{Plot3D} + }{ + The Plot3D class ignores this attributes, assuming a value of + zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The value of this attribute is not saved when the Plot is written + out through a \htmlref{Channel}{Channel} to an external data store. On re-loading such + a Plot using \htmlref{astRead}{astRead}, the attribute will be cleared, resulting in the + graphics interface selected at link-time being used. + } + } +} +\sstroutine{ + Grid +}{ + Draw grid lines for a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether grid lines (a grid of curves marking the \texttt{"} major\texttt{"} values + on each axis) are drawn across the plotting area. + + If the Grid value of a \htmlref{Plot}{Plot} is non-zero, then grid lines will be + drawn. Otherwise, short tick marks on the axes are used to mark + the major axis values. The default behaviour is to use tick + marks if the entire plotting area is filled by valid physical + coordinates, but to draw grid lines otherwise. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The spacing between major axis values, which determines the + spacing of grid lines, may be set using the \htmlref{Gap(axis)}{Gap(axis)} attribute. + } + } +} +\sstroutine{ + GrismAlpha +}{ + The angle of incidence of the incoming light on the grating surface +}{ + \sstdescription{ + This attribute holds the angle between the incoming light and the + normal to the grating surface, in radians. The default value is 0. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismEps +}{ + The angle between the normal and the dispersion plane +}{ + \sstdescription{ + This attribute holds the angle (in radians) between the normal to + the grating or exit prism face, and the dispersion plane. The + dispersion plane is the plane spanned by the incoming and outgoing + ray. The default value is 0.0. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismG +}{ + The grating ruling density +}{ + \sstdescription{ + This attribute holds the number of grating rulings per unit length. + The unit of length used should be consistent with the units used + for attributes \htmlref{GrismWaveR}{GrismWaveR} and \htmlref{GrismNRP}{GrismNRP}. The default value is 0.0. + (the appropriate value for a pure prism disperser with no grating). + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismM +}{ + The interference order +}{ + \sstdescription{ + This attribute holds the interference order being considered. + The default value is 0. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismNR +}{ + The refractive index at the reference wavelength +}{ + \sstdescription{ + This attribute holds refractive index of the grism material at the + reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default + value is 1.0. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismNRP +}{ + The rate of change of refractive index with wavelength +}{ + \sstdescription{ + This attribute holds the rate of change of the refractive index of the + grism material with respect to wavelength at the reference wavelength + (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 0.0 (the + appropriate value for a pure grating disperser with no prism). The + units of this attribute should be consistent with those of attributes + GrismWaveR and \htmlref{GrismG}{GrismG}. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismTheta +}{ + Angle between normal to detector plane and reference ray +}{ + \sstdescription{ + This attribute gives the angle of incidence of light of the + reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}) onto the + detector. Specifically, it holds the angle (in radians) between + the normal to the detector plane and an incident ray at the reference + wavelength. The default value is 0.0. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + GrismWaveR +}{ + The reference wavelength +}{ + \sstdescription{ + This attribute holds reference wavelength. The default value is + 5000 (Angstrom). The units of this attribute should be consistent with + those of attributes \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG}. + + Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap} + has no more than one reference. That is, an error is reported if the + GrismMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + GrismMap + }{ + All GrismMaps have this attribute. + } + } +} +\sstroutine{ + ID +}{ + Object identification string +}{ + \sstdescription{ + This attribute contains a string which may be used to identify + the \htmlref{Object}{Object} to which it is attached. There is no restriction on + the contents of this string, which is not used internally by the + AST library, and is simply returned without change when + required. The default value is an empty string. + + An identification string can be valuable when, for example, + several Objects have been stored in a file (using \htmlref{astWrite}{astWrite}) and + are later retrieved (using \htmlref{astRead}{astRead}). Consistent use of the ID + attribute allows the retrieved Objects to be identified without + depending simply on the order in which they were stored. + + This attribute may also be useful during debugging, to + distinguish similar Objects when using \htmlref{astShow}{astShow} to display them. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Unlike most other attributes, the value of the ID attribute is + not transferred when an Object is copied. Instead, its value is + undefined (and therefore defaults to an empty string) in any + copy. However, it is retained in any external representation of + an Object produced by the astWrite function. + } + } +} +\sstroutine{ + IF +}{ + The intermediate frequency in a dual sideband spectrum +}{ + \sstdescription{ + This attribute specifies the (topocentric) intermediate frequency in + a dual sideband spectrum. Its sole use is to determine the local + oscillator (LO) frequency (the frequency which marks the boundary + between the lower and upper sidebands). The LO frequency is + equal to the sum of the centre frequency and the intermediate + frequency. Here, the \texttt{"} centre frequency\texttt{"} is the topocentric + frequency in Hz corresponding to the current value of the \htmlref{DSBCentre}{DSBCentre} + attribute. The value of the IF attribute may be positive or + negative: a positive value results in the LO frequency being above + the central frequency, whilst a negative IF value results in the LO + frequency being below the central frequency. The sign of the IF + attribute value determines the default value for the \htmlref{SideBand}{SideBand} + attribute. + + When setting a new value for this attribute, the units in which the + frequency value is supplied may be indicated by appending a suitable + string to the end of the formatted value. If the units are not + specified, then the supplied value is assumed to be in units of GHz. + For instance, the following strings all result in an IF of 4 GHz being + used: \texttt{"} 4.0\texttt{"} , \texttt{"} 4.0 GHz\texttt{"} , \texttt{"} 4.0E9 Hz\texttt{"} , etc. + + When getting the value of this attribute, the returned value is + always in units of GHz. The default value for this attribute is 4 GHz. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{DSBSpecFrame}{DSBSpecFrame} + }{ + All DSBSpecFrames have this attribute. + } + } +} +\sstroutine{ + Ident +}{ + Permanent Object identification string +}{ + \sstdescription{ + This attribute is like the \htmlref{ID}{ID} attribute, in that it contains a + string which may be used to identify the \htmlref{Object}{Object} to which it is + attached. The only difference between ID and Ident is that Ident + is transferred when an Object is copied, but ID is not. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + ImagFreq +}{ + The image sideband equivalent of the rest frequency +}{ + \sstdescription{ + This is a read-only attribute giving the frequency which + corresponds to the rest frequency but is in the opposite sideband. + + The value is calculated by first transforming the rest frequency + (given by the \htmlref{RestFreq}{RestFreq} attribute) from the standard of rest of the + source (given by the \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} attributes) to the + standard of rest of the observer (i.e. the topocentric standard of + rest). The resulting topocentric frequency is assumed to be in the + same sideband as the value given for the \htmlref{DSBCentre}{DSBCentre} attribute (the + \texttt{"} observed\texttt{"} sideband), and is transformed to the other sideband (the + \texttt{"} image\texttt{"} sideband). The new frequency is converted back to the standard + of rest of the source, and the resulting value is returned as the + attribute value, in units of GHz. + } + \sstattributetype{ + Floating point, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{DSBSpecFrame}{DSBSpecFrame} + }{ + All DSBSpecFrames have this attribute. + } + } +} +\sstroutine{ + Indent +}{ + Specifies the indentation to use in text produced by a Channel +}{ + \sstdescription{ + This attribute controls the indentation within the output text produced by + the \htmlref{astWrite}{astWrite} function. + It gives the increase in the indentation for each level in the object + heirarchy. If it is set to zero, no indentation will be used. [3] + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Channel}{Channel} + }{ + The default value is zero for a basic Channel. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + The FitsChan class ignores this attribute. + } + \sstsubsection{ + \htmlref{StcsChan}{StcsChan} + }{ + The default value for an StcsChan is zero, which causes the entire + STC-S description is written out by a single invocation of the sink + function. The text supplied to the sink function will not contain + any linefeed characters, and each pair of adjacent words will be + separated by a single space. The text may thus be arbitrarily large + and the \htmlref{StcsLength}{StcsLength} attribute is ignored. + + If Indent is non-zero, then the text is written out via multiple + calls to the sink function, each call corresponding to a single + \texttt{"} line\texttt{"} of text (although no line feed characters will be inserted + by AST). The complete STC-S description is broken into lines so that: + + \sstitemlist{ + + \sstitem + the line length specified by attribute StcsLength is not exceeded + + \sstitem + each sub-phrase (time, space, etc.) starts on a new line + + \sstitem + each argument in a compound spatial region starts on a new line + + } + If this causes a sub-phrase to extend to two or more lines, then the + second and subsequent lines will be indented by three spaces compared + to the first line. In addition, lines within a compound spatial region + will have extra indentation to highlight the nesting produced by the + parentheses. Each new level of nesting will be indented by a further + three spaces. + } + \sstsubsection{ + \htmlref{XmlChan}{XmlChan} + }{ + The default value for an XmlChan is zero, which results in no + linefeeds or indentation strings being added to output text. + If any non-zero value is assigned to Indent, then extra linefeed and + space characters will be inserted as necessary to ensure that each + XML tag starts on a new line, and each tag will be indented by + a further 3 spaces to show its depth in the containment hierarchy. + } + } +} +\sstroutine{ + InternalUnit(axis) +}{ + Physical units for unformated axis values +}{ + \sstdescription{ + This read-only attribute contains a textual representation of the + physical units used to represent unformatted (i.e. floating point) + values on a particular axis of a \htmlref{Frame}{Frame}, typically handled internally + within application code. In most cases, the value of the InternalUnit + attribute will be the same as Unit attribute (i.e. formatted and + unformatted axis values will normally use the same system of units). + The main exception to this is the \htmlref{SkyFrame}{SkyFrame} class, which represents + unformatted axis values in radians, regardless of the current + setting of the Unit attribute. + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + IntraFlag +}{ + IntraMap identification string +}{ + \sstdescription{ + This attribute allows an \htmlref{IntraMap}{IntraMap} to be flagged so that it is + distinguishable from other IntraMaps. The transformation function + associated with the IntraMap may then enquire the value of this + attribute and adapt the transformation it provides according to the + particular IntraMap involved. + + Although this is a string attribute, it may often be useful to store + numerical values here, encoded as a character string, and to use these + as data within the transformation function. Note, however, that this + mechanism is not suitable for transferring large amounts of data (more + than about 1000 characters) to an IntraMap. For that purpose, global + variables are recommended, although the IntraFlag value can be used to + supplement this approach. The default IntraFlag value is an empty + string. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + IntraMap + }{ + All IntraMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A pair of IntraMaps whose transformations may potentially cancel + cannot be simplified to produce a \htmlref{UnitMap}{UnitMap} (e.g. using \htmlref{astSimplify}{astSimplify}) + unless they have the same IntraFlag values. The test for equality is + case-sensitive. + } + } +} +\sstroutine{ + Invert +}{ + Mapping inversion flag +}{ + \sstdescription{ + This attribute controls which one of a \htmlref{Mapping}{Mapping}\texttt{'} s two possible + coordinate transformations is considered the \texttt{"} forward\texttt{"} + transformation (the other being the \texttt{"} inverse\texttt{"} + transformation). If the attribute value is zero (the default), + the Mapping\texttt{'} s behaviour will be the same as when it was first + created. However, if it is non-zero, its two transformations + will be inter-changed, so that the Mapping displays the inverse + of its original behaviour. + + Inverting the boolean sense of the Invert attribute will cause + the values of a Mapping\texttt{'} s \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes to be + interchanged. The values of its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} + attributes will also be interchanged. This operation may be + performed with the \htmlref{astInvert}{astInvert} function. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{UnitMap}{UnitMap} + }{ + The value of the Invert attribute has no effect on the + behaviour of a UnitMap. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + Inverting the boolean sense of the Invert attribute for a + FrameSet will cause its base and current Frames (and its \htmlref{Base}{Base} + and \htmlref{Current}{Current} attributes) to be interchanged. This, in turn, + may affect other properties and attributes of the FrameSet + (such as Nin, Nout, \htmlref{Naxes}{Naxes}, TranForward, TranInverse, + etc.). The Invert attribute of a FrameSet is not itself + affected by selecting a new base or current \htmlref{Frame}{Frame}. + } + } +} +\sstroutine{ + Invisible +}{ + Draw graphics using invisible ink? +}{ + \sstdescription{ + This attribute controls the appearance of all graphics produced by + \htmlref{Plot}{Plot} methods by determining whether graphics should be visible or + invisible. + + If the Invisible value of a Plot is non-zero, then all the Plot + methods which normally generate graphical output do not do so (you + can think of them drawing with \texttt{"} invisible ink\texttt{"} ). Such methods do, + however, continue to do all the calculations which would be needed to + produce the graphics. In particular, the bounding box enclosing the + graphics is still calculated and can be retrieved as normal using + \htmlref{astBoundingBox}{astBoundingBox}. The default value is zero, resulting in all methods + drawing graphics as normal, using visible ink. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } +} +\sstroutine{ + IsLatAxis(axis) +}{ + Is the specified celestial axis a latitude axis? +}{ + \sstdescription{ + This is a read-only boolean attribute that indicates the nature of + the specified axis. The attribute has a non-zero value if the + specified axis is a celestial latitude axis (Declination, Galactic + latitude, etc), and is zero otherwise. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the SkyFrame axis to be tested. + } + } +} +\sstroutine{ + IsLinear +}{ + Is the Mapping linear? +}{ + \sstdescription{ + This attribute indicates whether a \htmlref{Mapping}{Mapping} is an instance of a + class that always represents a linear transformation. Note, some + Mapping classes can represent linear or non-linear transformations + (the \htmlref{MathMap}{MathMap} class for instance). Such classes have a zero value for + the IsLinear attribute. Specific instances of such classes can be + tested for linearity using the + \htmlref{astLinearApprox}{astLinearApprox} function. + AST\_LINEARAPPROX routine. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + The IsLinear value for a CmpMap is determined by the classes + of the encapsulated Mappings. For instance, a CmpMap that combines + a \htmlref{ZoomMap}{ZoomMap} and a \htmlref{ShiftMap}{ShiftMap} will have a non-zero value for its IsLinear + attribute, but a CmpMap that contains a MathMap will have a + value of zero for its IsLinear attribute. + } + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + The IsLinear value for a Frame is 1 (since a Frame is equivalent + to a \htmlref{UnitMap}{UnitMap}). + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The IsLinear value for a FrameSet is obtained from the Mapping + from the base Frame to the current Frame. + } + } +} +\sstroutine{ + IsLonAxis(axis) +}{ + Is the specified celestial axis a longitude axis? +}{ + \sstdescription{ + This is a read-only boolean attribute that indicates the nature of + the specified axis. The attribute has a non-zero value if the + specified axis is a celestial longitude axis (Right Ascension, Galactic + longitude, etc), and is zero otherwise. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the SkyFrame axis to be tested. + } + } +} +\sstroutine{ + IsSimple +}{ + Has the Mapping been simplified? +}{ + \sstdescription{ + This attribute indicates whether a \htmlref{Mapping}{Mapping} has been simplified + by the + \htmlref{astSimplify}{astSimplify} + method. If the IsSimple value is non-zero, then the Mapping has + been simplified and so there is nothing to be gained by simplifying + it again. Indeed, the + astSimplify + method will immediately return the Mapping unchanged if the IsSimple + attribute indicates that the Mapping has already been simplified. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + All classes of Frame return zero for the IsSimple attribute. + This is because changes can be made to a Frame which affect the + Mapping represented by the Frame, and so there can be no + guarantee that the Mapping may not need re-simplifying. Most + non-Frame Mappings, on the other hand, are immutable and so when + they are simplified it is certain that they weill remain in a + simple state. + } + } +} +\sstroutine{ + IterInverse +}{ + Provide an iterative inverse transformation? +}{ + \sstdescription{ + This attribute indicates whether the inverse transformation of + the \htmlref{PolyMap}{PolyMap} should be implemented via an iterative Newton-Raphson + approximation that uses the forward transformation to transform + candidate input positions until an output position is found which + is close to the required output position. By default, an iterative + inverse is provided if, and only if, no inverse polynomial was supplied + when the PolyMap was constructed. + + The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that + control the behaviour of the inverse approcimation method. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + PolyMap + }{ + All PolyMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An iterative inverse can only be used if the PolyMap has equal + numbers of inputs and outputs, as given by the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} + attributes. An error will be reported if IterInverse is set non-zero + for a PolyMap that does not meet this requirement. + } + } +} +\sstroutine{ + Iwc +}{ + Include a Frame representing FITS-WCS intermediate world coordinates? +}{ + \sstdescription{ + This attribute is a boolean value which is used when a \htmlref{FrameSet}{FrameSet} is + read from a \htmlref{FitsChan}{FitsChan} with a foreign FITS encoding (e.g. FITS-WCS) using + \htmlref{astRead}{astRead}. + If it has a non-zero value then the returned FrameSet will include + Frames representing \texttt{"} intermediate world coordinates\texttt{"} (IWC). These + Frames will have \htmlref{Domain}{Domain} name \texttt{"} IWC\texttt{"} for primary axis descriptions, and + \texttt{"} IWCa\texttt{"} for secondary axis descriptions, where \texttt{"} a\texttt{"} is replaced by + the single alternate axis description character, as used in the + FITS-WCS header. The default value for \texttt{"} Iwc\texttt{"} is zero. + + FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one + axis for each WCS axis, and is the coordinate system produced by the + rotation matrix (represented by FITS keyword PCi\_j, CDi\_j, etc). + For instance, for a 2-D FITS-WCS header describing projected + celestial longitude and latitude, the intermediate world + coordinates represent offsets in degrees from the reference point + within the plane of projection. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + KeyCase +}{ + Are keys case sensitive? +}{ + \sstdescription{ + This attribute is a boolean value which controls how keys are + used. If KeyCase is zero, then key strings supplied to any method + are automatically converted to upper case before being used. If + KeyCase is non-zero (the default), then supplied key strings are + used without modification. + + The value of this attribute can only be changed if the \htmlref{KeyMap}{KeyMap} is + empty. Its value can be set conveniently when creating the KeyMap. + An error will be reported if an attempt is made to change the + attribute value when the KeyMap contains any entries. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + All KeyMaps have this attribute. + } + \sstsubsection{ + \htmlref{Table}{Table} + }{ + The Table class over-rides this attribute by forcing it to zero. + That is, keys within a Table are always case insensitive. + } + } +} +\sstroutine{ + KeyError +}{ + Report an error when getting the value of a non-existant KeyMap entry? +}{ + \sstdescription{ + This attribute is a boolean value which controls how the + astMapGet... + functions behave if the requested key is not found in the \htmlref{KeyMap}{KeyMap}. + If KeyError is zero (the default), then these functions will return + zero + but no error will be reported. If KeyError is non-zero, then the + same values are returned but an error is also reported. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + All KeyMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When setting a new value for KeyError, the supplied value is + propagated to any KeyMaps contained within the supplied KeyMap. + + \sstitem + When clearing the KeyError attribute, the attribute is also + cleared in any KeyMaps contained within the supplied KeyMap. + } + } +} +\sstroutine{ + LTOffset +}{ + The offset from UTC to Local Time, in hours +}{ + \sstdescription{ + This specifies the offset from UTC to Local Time, in hours (fractional + hours can be supplied). It is positive for time zones east of Greenwich. + AST uses the figure as given, without making any attempt to correct for + daylight saving. The default value is zero. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + All TimeFrames have this attribute. + } + } +} +\sstroutine{ + Label(axis) +}{ + Axis label +}{ + \sstdescription{ + This attribute specifies a label to be attached to each axis of + a \htmlref{Frame}{Frame} when it is represented (e.g.) in graphical output. + + If a Label value has not been set for a Frame axis, then a + suitable default is supplied. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default supplied by the Frame class is the string \texttt{"} \htmlref{Axis}{Axis} + $<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for each successive axis. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Label value + (e.g. to \texttt{"} Right ascension\texttt{"} or \texttt{"} Galactic latitude\texttt{"} ) as + appropriate for the particular celestial coordinate system + being represented. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class re-defines the default Label value as + appropriate for the particular time system being represented. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Label attribute of a FrameSet axis is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Axis labels are intended purely for interpretation by human + readers and not by software. + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + LabelAt(axis) +}{ + Where to place numerical labels for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + where numerical axis labels and associated tick marks are + placed. It takes a separate value for each physical axis of a + \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LabelAt(2)=10.0\texttt{"} + specifies where the numerical labels and tick marks for the + second axis should be drawn. + + For each axis, the LabelAt value gives the value on the other + axis at which numerical labels and tick marks should be placed + (remember that Plots suitable for use with astGrid may only + have two axes). For example, in a celestial (RA,Dec) coordinate + system, LabelAt(1) gives a Dec value which defines a line (of + constant Dec) along which the numerical RA labels and their + associated tick marks will be drawn. Similarly, LabelAt(2) gives + the RA value at which the Dec labels and ticks will be drawn. + + The default bahaviour is for the Plot to generate its own + position for numerical labels and tick marks. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The LabelAt value should use the same units as are used + internally for storing coordinate values on the appropriate + axis. For example, with a celestial coordinate system, the + LabelAt value should be in radians, not hours or degrees. + + \sstitem + Normally, the LabelAt value also determines where the lines + representing coordinate axes will be drawn, so that the tick + marks will lie on these lines (but also see the DrawAxes + attribute). + + \sstitem + In some circumstances, numerical labels and tick marks are + drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling} + attribute). In this case, the value of the LabelAt attribute is + ignored. + } + } +} +\sstroutine{ + LabelUnits(axis) +}{ + Use axis unit descriptions in a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether the descriptive labels drawn for each axis of a \htmlref{Plot}{Plot} + should include a description of the units being used on the + axis. It takes a separate value for each physical axis of a + Plot so that, for instance, the setting \texttt{"} LabelUnits(2)=1\texttt{"} + specifies that a unit description should be included in the + label for the second axis. + + If the LabelUnits value of a Plot axis is non-zero, a unit + description will be included in the descriptive label for that + axis, otherwise it will be omitted. The default behaviour is to + include a unit description unless the current \htmlref{Frame}{Frame} of the Plot + is a \htmlref{SkyFrame}{SkyFrame} representing equatorial, ecliptic, galactic or + supergalactic coordinates, in which case it is omitted. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The text used for the unit description is obtained from the + Plot\texttt{'} s \htmlref{Unit(axis)}{Unit(axis)} attribute. + + \sstitem + If no axis is specified, (e.g. \texttt{"} LabelUnits\texttt{"} instead of + \texttt{"} LabelUnits(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the LabelUnits(1) value. + + \sstitem + If the current Frame of the Plot is not a SkyFrame, but includes + axes which were extracted from a SkyFrame, then the default behaviour + is to include a unit description only for those axes which were not + extracted from a SkyFrame. + } + } +} +\sstroutine{ + LabelUp(axis) +}{ + Draw numerical Plot labels upright? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether the numerical labels for each axis of a \htmlref{Plot}{Plot} should be + drawn upright or not. It takes a separate value for each + physical axis of a Plot so that, for instance, the setting + \texttt{"} LabelUp(2)=1\texttt{"} specifies that numerical labels for the second + axis should be drawn upright. + + If the LabelUp value of a Plot axis is non-zero, it causes + numerical labels for that axis to be plotted upright (i.e. as + normal, horizontal text), otherwise labels are drawn parallel to + the axis to which they apply. + + The default is to produce upright labels if the labels are placed + around the edge of the plot, and to produce labels that follow the + axes if the labels are placed within the interior of the plot (see + attribute \htmlref{Labelling}{Labelling}). + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + In some circumstances, numerical labels and tick marks are + drawn around the edges of the plotting area (see the Labelling + attribute). In this case, the value of the LabelUp attribute is + ignored. + + \sstitem + If no axis is specified, (e.g. \texttt{"} LabelUp\texttt{"} instead of + \texttt{"} LabelUp(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the + attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the LabelUp(1) value. + } + } +} +\sstroutine{ + Labelling +}{ + Label and tick placement option for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the strategy for placing numerical labels and tick marks for a \htmlref{Plot}{Plot}. + + If the Labelling value of a Plot is \texttt{"} exterior\texttt{"} (the default), then + numerical labels and their associated tick marks are placed + around the edges of the plotting area, if possible. If this is + not possible, or if the Labelling value is \texttt{"} interior\texttt{"} , then they + are placed along grid lines inside the plotting area. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute may be used to determine the exact + placement of labels and tick marks that are drawn inside the + plotting area. + } + } +} +\sstroutine{ + LatAxis +}{ + Index of the latitude axis +}{ + \sstdescription{ + This read-only attribute gives the index (1 or 2) of the latitude + axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis + permutations). + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + ListSize +}{ + Number of points in a PointList +}{ + \sstdescription{ + This is a read-only attribute giving the number of points in a + \htmlref{PointList}{PointList}. This value is determined when the PointList is created. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + PointList + }{ + All PointLists have this attribute. + } + } +} +\sstroutine{ + LogGap(axis) +}{ + Interval between major axis values of a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the logarithmic interval between the \texttt{"} major\texttt{"} axis values of a \htmlref{Plot}{Plot}, at + which (for example) major tick marks are drawn. It takes a separate + value for each physical axis of the Plot so that, for instance, + the setting \texttt{"} LogGap(2)=100.0\texttt{"} specifies the ratio between adjacent major + values along the second axis. The LogGap attribute is only used when + the LogTicks attribute indicates that the spacing between major axis + values is to be logarithmic. If major axis values are linearly spaced + then the gap is specified using attribute Gap. + + The LogGap value supplied will be rounded to the nearest power of 10. + The reciprocal of the supplied value may be used if this is necessary + to produce usable major axis values. If a zero or negative value is + supplied, an error will be reported when the grid is drawn. The default + behaviour is for the Plot to generate its own LogGap value when + required, based on the range of axis values to be represented. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The LogGap value is a ratio between axis values and is therefore + dimensionless. + + \sstitem + If no axis is specified, (e.g. \texttt{"} LogGap\texttt{"} instead of \texttt{"} LogGap(2)\texttt{"} ), + then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the attribute + value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation + will use just the LogGap(1) value. + } + } +} +\sstroutine{ + LogLabel(axis) +}{ + Use exponential format for numerical axis labels? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether the numerical axis labels should be in normal decimal form + or should be represented as 10 raised to the appropriate power. + That is, an axis value of 1000.0 will be drawn as \texttt{"} 1000.0\texttt{"} if + LogLabel is zero, but as \texttt{"} 10$\wedge$3\texttt{"} if LogLabel is non-zero. If + graphical escape sequences are supported (see attribute \htmlref{Escape}{Escape}), + the power in such exponential labels will be drawn as a small + superscript instead of using a \texttt{"} $\wedge$\texttt{"} character to represent + exponentiation. + + The default is to produce exponential labels if the major tick + marks are logarithmically spaced (see the LogTicks attribute). + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Plot}{Plot} + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} LogLabel\texttt{"} instead of + \texttt{"} LogLabel(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the + attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the LogLabel(1) value. + } + } +} +\sstroutine{ + LogPlot(axis) +}{ + Map the plot logarithmically onto the screen? +}{ + \sstdescription{ + This attribute controls the appearance of all graphics produced by + the \htmlref{Plot}{Plot}, by determining whether the axes of the plotting surface + are mapped logarithmically or linearly onto the base \htmlref{Frame}{Frame} of the + \htmlref{FrameSet}{FrameSet} supplied when the Plot was constructed. It takes a separate + value for each axis of the graphics coordinate system (i.e. the + base Frame in the Plot) so that, for instance, the setting + \texttt{"} LogPlot(2)=1\texttt{"} specifies that the second axis of the graphics + coordinate system (usually the vertical axis) should be mapped + logarithmically onto the second axis of the base Frame of the + FrameSet supplied when the Plot was constructed. + + If the LogPlot value of a Plot axis is non-zero, it causes that + axis to be mapped logarithmically, otherwise (the default) the axis + is mapped linearly. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The setting of the LogPlot attribute provides the default value + for the related LogTicks attribute. By selecting suitable values for + LogPlot and LogTicks, it is possible to have tick marks which are evenly + spaced in value but which are mapped logarithmically onto the screen + (and vice-versa). + + \sstitem + An axis may only be mapped logarithmically if the visible part of + the axis does not include the value zero. The visible part of the + axis is that part which is mapped onto the plotting area, and is + measured within the base Frame of the FrameSet which was supplied when + the Plot was constructed. Any attempt to set LogPlot to a non-zero value + will be ignored (without error) if the visible part of the axis + includes the value zero + + \sstitem + If no axis is specified, (e.g. \texttt{"} LogPlot\texttt{"} instead of + \texttt{"} LogPlot(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the + attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the LogPlot(1) value. + } + } +} +\sstroutine{ + LogTicks(axis) +}{ + Space the major tick marks logarithmically? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether the major tick marks should be spaced logarithmically or + linearly in axis value. It takes a separate value for each physical + axis of the \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LogTicks(2)=1\texttt{"} + specifies that the major tick marks on the second axis should be + spaced logarithmically. + + If the LogTicks value for a physical axis is non-zero, the major + tick marks on that axis will be spaced logarithmically (that is, + there will be a constant ratio between the axis values at adjacent + major tick marks). An error will be reported if the dynamic range of + the axis (the ratio of the largest to smallest displayed axis value) + is less than 10.0. If the LogTicks value is zero, the major tick marks + will be evenly spaced (that is, there will be a constant difference + between the axis values at adjacent major tick marks). The default is + to produce logarithmically spaced tick marks if the corresponding + LogPlot attribute is non-zero and the ratio of maximum axis value + to minimum axis value is 100 or more. If either of these conditions + is not met, the default is to produce linearly spaced tick marks. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The setting of the LogTicks attribute does not affect the mapping + of the plot onto the screen, which is controlled by attribute LogPlot. + By selecting suitable values for LogPlot and LogTicks, it is possible to + have tick marks which are evenly spaced in value but which are mapped + logarithmically onto the screen (and vica-versa). + + \sstitem + An error will be reported when drawing an annotated axis grid if + the visible part of the physical axis includes the value zero. + + \sstitem + If no axis is specified, (e.g. \texttt{"} LogTicks\texttt{"} instead of + \texttt{"} LogTicks(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the + attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the LogTicks(1) value. + } + } +} +\sstroutine{ + LonAxis +}{ + Index of the longitude axis +}{ + \sstdescription{ + This read-only attribute gives the index (1 or 2) of the longitude + axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis + permutations). + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + LutEpsilon +}{ + The relative error of the values held in the took-up table +}{ + \sstdescription{ + This attribute holds the relative error of the values held in the + took-up table. It is used when simplifying a \htmlref{LutMap}{LutMap}, to determine + if the LutMap should be considered linear. Setting a larger value + makes it more likely that a LutMap will be replaced by a \htmlref{WinMap}{WinMap} + (i.e. a linear \htmlref{Mapping}{Mapping}) when simplified. + + The default value is the value of the system constant DBL\_EPSILON + (typically around 1e-16 or 2E-16). If the values in the look-up + table were derived from single precision data, it may be appropriate + to set this attribute to a value around 1E-7. + + Note, the value of this attribute may changed only if the LutMap + has no more than one reference. That is, an error is reported if the + LutMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + LutMap + }{ + All LutMaps have this attribute. + } + } +} +\sstroutine{ + LutInterp +}{ + Look-up table interpolation method +}{ + \sstdescription{ + This attribute indicates the method to be used when finding the + output value of a \htmlref{LutMap}{LutMap} for an input value part way between two + table entries. If it is set to 0 (the default) then linear + interpolation is used. Otherwise, nearest neighbour interpolation + is used. + + Using nearest neighbour interpolation causes AST\_\_BAD to be returned + for any point which falls outside the bounds of the table. Linear + interpolation results in an extrapolated value being returned based + on the two end entries in the table. + + Note, the value of this attribute may changed only if the LutMap + has no more than one reference. That is, an error is reported if the + LutMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + LutMap + }{ + All LutMaps have this attribute. + } + } +} +\sstroutine{ + MajTickLen(axis) +}{ + Length of major tick marks for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the length of the major tick marks drawn on the axes of a \htmlref{Plot}{Plot}. + It takes a separate value for each physical axis of the Plot so + that, for instance, the setting \texttt{"} MajTickLen(2)=0\texttt{"} specifies the + length of the major tick marks drawn on the second axis. + + The MajTickLen value should be given as a fraction of the + minimum dimension of the plotting area. Negative values cause + major tick marks to be placed on the outside of the + corresponding grid line or axis (but subject to any clipping + imposed by the underlying graphics system), while positive + values cause them to be placed on the inside. + + The default behaviour depends on whether a coordinate grid is + drawn inside the plotting area (see the \htmlref{Grid}{Grid} attribute). If so, + the default MajTickLen value is zero (so that major ticks are + not drawn), otherwise the default is $+$0.015. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} MajTickLen\texttt{"} instead of + \texttt{"} MajTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the MajTickLen(1) value. + } + } +} +\sstroutine{ + MapLocked +}{ + Prevent new entries being added to a KeyMap? +}{ + \sstdescription{ + If this boolean attribute is set to + a non-zero value, + an error will be reported if an attempt is made to add a new entry + to the \htmlref{KeyMap}{KeyMap}. Note, the value associated with any existing entries + can still be changed, but no new entries can be stored in the KeyMap. + The default value + (zero) + allows new entries to be added to the KeyMap. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + All KeyMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When setting a new value for MapLocked, the supplied value is + propagated to any KeyMaps contained within the supplied KeyMap. + + \sstitem + When clearing the MapLocked attribute, the attribute is also + cleared in any KeyMaps contained within the supplied KeyMap. + } + } +} +\sstroutine{ + MatchEnd +}{ + Match trailing axes? +}{ + \sstdescription{ + This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} + behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match + another (target) Frame. It applies only in the case where a + match occurs between template and target Frames with different + numbers of axes. + + If the MatchEnd value of the template Frame is zero, then the + axes which occur first in the target Frame will be matched and + any trailing axes (in either the target or template) will be + disregarded. If it is non-zero, the final axes in each Frame + will be matched and any un-matched leading axes will be + disregarded instead. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default MatchEnd value for a Frame is zero, so that + trailing axes are disregarded. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The MatchEnd attribute of a FrameSet is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } +} +\sstroutine{ + MaxAxes +}{ + Maximum number of Frame axes to match +}{ + \sstdescription{ + This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It + specifies the maximum number of axes that the target Frame may + have in order to match the template. + + Normally, this value will equal the number of Frame axes, so + that a template Frame will only match another Frame with the + same number of axes as itself. By setting a different value, + however, the matching process may be used to identify Frames + with specified numbers of axes. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default MaxAxes value for a Frame is equal to the number + of Frame axes (\htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The MaxAxes attribute of a CmpFrame defaults to a large number + (1000000) which is much larger than any likely number of axes in + a Frame. Combined with the \htmlref{MinAxes}{MinAxes} default of zero (for a + CmpFrame), this means that the default behaviour for a CmpFrame + is to match any target Frame that consists of a subset of the + axes in the template CmpFrame. To change this so that a CmpFrame + will only match Frames that have the same number of axes, you + should set the CmpFrame MaxAxes and MinAxes attributes to the + number of axes in the CmpFrame. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The MaxAxes attribute of a FrameSet is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When setting a MaxAxes value, the value of the MinAxes + attribute may also be silently changed so that it remains + consistent with (i.e. does not exceed) the new value. The + default MaxAxes value may also be reduced to remain consistent + with the MinAxes value. + + \sstitem + If a template Frame is used to match a target with a different + number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used + to determine how the individual axes of each Frame should match. + } + } +} +\sstroutine{ + MeshSize +}{ + Number of points used to represent the boundary of a Region +}{ + \sstdescription{ + This attribute controls how many points are used when creating a + mesh of points covering the boundary or volume of a \htmlref{Region}{Region}. Such a + mesh is returned by the + \htmlref{astGetRegionMesh}{astGetRegionMesh} + method. The boundary mesh is also used when testing for overlap + between two Regions: each point in the bomdary mesh of the first + Region is checked to see if it is inside or outside the second Region. + Thus, the reliability of the overlap check depends on the value assigned + to this attribute. If the value used is very low, it is possible for + overlaps to go unnoticed. High values produce more reliable results, but + can result in the overlap test being very slow. The default value is 200 + for two dimensional Regions and 2000 for three or more dimensional + Regions (this attribute is not used for 1-dimensional regions since the + boundary of a simple 1-d Region can only ever have two points). A + value of five is used if the supplied value is less than five. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + \sstsubsection{ + \htmlref{CmpRegion}{CmpRegion} + }{ + The default MeshSize for a CmpRegion is the MeshSize of its + first component Region. + } + \sstsubsection{ + \htmlref{Stc}{Stc} + }{ + The default MeshSize for an Stc is the MeshSize of its + encapsulated Region. + } + } +} +\sstroutine{ + MinAxes +}{ + Minimum number of Frame axes to match +}{ + \sstdescription{ + This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It + specifies the minimum number of axes that the target Frame may + have in order to match the template. + + Normally, this value will equal the number of Frame axes, so + that a template Frame will only match another Frame with the + same number of axes as itself. By setting a different value, + however, the matching process may be used to identify Frames + with specified numbers of axes. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default MinAxes value for a Frame is equal to the number + of Frame axes (\htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The MinAxes attribute of a CmpFrame defaults to zero. Combined + with the \htmlref{MaxAxes}{MaxAxes} default of 1000000 (for a CmpFrame), this means + that the default behaviour for a CmpFrame is to match any target + Frame that consists of a subset of the axes in the template + CmpFrame. To change this so that a CmpFrame will only match Frames + that have the same number of axes, you should set the CmpFrame + MinAxes and MaxAxes attributes to the number of axes in the CmpFrame. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The MinAxes attribute of a FrameSet is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When setting a MinAxes value, the value of the MaxAxes + attribute may also be silently changed so that it remains + consistent with (i.e. is not less than) the new value. The + default MinAxes value may also be reduced to remain consistent + with the MaxAxes value. + + \sstitem + If a template Frame is used to match a target with a different + number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used + to determine how the individual axes of each Frame should match. + } + } +} +\sstroutine{ + MinTick(axis) +}{ + Density of minor tick marks for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the density of minor tick marks which appear between the major + axis values of a \htmlref{Plot}{Plot}. It takes a separate value for each + physical axis of a Plot so that, for instance, the setting + \texttt{"} MinTick(2)=2\texttt{"} specifies the density of minor tick marks along + the second axis. + + The value supplied should be the number of minor divisions + required between each pair of major axis values, this being one + more than the number of minor tick marks to be drawn. By + default, a value is chosen that depends on the gap between major + axis values and the nature of the axis. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} MinTick\texttt{"} instead of + \texttt{"} MinTick(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the MinTick(1) value. + } + } +} +\sstroutine{ + MinTickLen(axis) +}{ + Length of minor tick marks for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + the length of the minor tick marks drawn on the axes of a \htmlref{Plot}{Plot}. + It takes a separate value for each physical axis of the Plot so + that, for instance, the setting \texttt{"} MinTickLen(2)=0\texttt{"} specifies the + length of the minor tick marks drawn on the second axis. + + The MinTickLen value should be given as a fraction of the + minimum dimension of the plotting area. Negative values cause + minor tick marks to be placed on the outside of the + corresponding grid line or axis (but subject to any clipping + imposed by the underlying graphics system), while positive + values cause them to be placed on the inside. + + The default value is $+$0.007. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The number of minor tick marks drawn is determined by the + Plot\texttt{'} s \htmlref{MinTick(axis)}{MinTick(axis)} attribute. + + \sstitem + If no axis is specified, (e.g. \texttt{"} MinTickLen\texttt{"} instead of + \texttt{"} MinTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the MinTickLen(1) value. + } + } +} +\sstroutine{ + NatLat +}{ + Native latitude of the reference point of a FITS-WCS projection +}{ + \sstdescription{ + This attribute gives the latitude of the reference point of the + FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in + radians in the \texttt{"} native spherical\texttt{"} coordinate system. This value is + fixed for most projections, for instance it is PI/2 (90 degrees) + for all zenithal projections. For some projections (e.g. the conics) + the value is not fixed, but is specified by parameter one on the + latitude axis. + + FITS-WCS paper II introduces the concept of a \texttt{"} fiducial point\texttt{"} + which is logical distinct from the projection reference point. + It is easy to confuse the use of these two points. The fiducial + point is the point which has celestial coordinates given by the + CRVAL FITS keywords. The native spherical coordinates for this point + default to the values of the NatLat and \htmlref{NatLon}{NatLon}, but these defaults + mey be over-ridden by values stored in the PVi\_j keywords. Put + another way, the CRVAL keywords will by default give the celestial + coordinates of the projection reference point, but may refer to + some other point if alternative native longitude and latitude values + are provided through the PVi\_j keywords. + + The NatLat attribute is read-only. + } + \sstattributetype{ + Floating point, read-only. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A default value of AST\_\_BAD is used if no latitude value is available. + } + } +} +\sstroutine{ + NatLon +}{ + Native longitude of the reference point of a FITS-WCS projection +}{ + \sstdescription{ + This attribute gives the longitude of the reference point of the + FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in + radians in the \texttt{"} native spherical\texttt{"} coordinate system, and will + usually be zero. See the description of attribute \htmlref{NatLat}{NatLat} for further + information. + + The NatLon attribute is read-only. + } + \sstattributetype{ + Floating point, read-only. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } +} +\sstroutine{ + Naxes +}{ + Number of Frame axes +}{ + \sstdescription{ + This is a read-only attribute giving the number of axes in a + \htmlref{Frame}{Frame} (i.e. the number of dimensions of the coordinate space + which the Frame describes). This value is determined when the + Frame is created. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Naxes attribute of a FrameSet is the same as that of its + current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The Naxes attribute of a CmpFrame is equal to the sum of the + Naxes values of its two component Frames. + } + } +} +\sstroutine{ + Ncard +}{ + Number of FITS header cards in a FitsChan +}{ + \sstdescription{ + This attribute gives the total number of FITS header cards + stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or + deleted. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Ncolumn +}{ + The number of columns in the table +}{ + \sstdescription{ + This attribute holds the number of columns currently in the table. Columns + are added and removed using the + \htmlref{astAddColumn}{astAddColumn} and \htmlref{astRemoveColumn}{astRemoveColumn} + functions. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Table}{Table} + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + NegLon +}{ + Display negative longitude values? +}{ + \sstdescription{ + This attribute is a boolean value which controls how longitude values + are normalized for display by \htmlref{astNorm}{astNorm}. + + If the NegLon attribute is zero, then normalized + longitude values will be in the range zero to 2.pi. If NegLon is + non-zero, then normalized longitude values will be in the range -pi + to pi. + + The default value depends on the current value of the \htmlref{SkyRefIs}{SkyRefIs} + attribute, If SkyRefIs has a value of \texttt{"} Origin\texttt{"} , then the default for + NegLon is one, otherwise the default is zero. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + Negated +}{ + Region negation flag +}{ + \sstdescription{ + This attribute controls whether a \htmlref{Region}{Region} represents the \texttt{"} inside\texttt{"} or + the \texttt{"} outside\texttt{"} of the area which was supplied when the Region was + created. If the attribute value is zero (the default), the Region + represents the inside of the original area. However, if it is non-zero, + it represents the outside of the original area. The value of this + attribute may be toggled using the + \htmlref{astNegate}{astNegate} function. + + Note, whether the boundary is considered to be inside the Region or + not is controlled by the \htmlref{Closed}{Closed} attribute. Changing the value of + the Negated attribute does not change the value of the Closed attribute. + Thus, if Region is closed, then the boundary of the Region will be + inside the Region, whatever the setting of the Negated attribute. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Region + }{ + All Regions have this attribute. + } + } +} +\sstroutine{ + Nframe +}{ + Number of Frames in a FrameSet +}{ + \sstdescription{ + This attrbute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This + value will change as Frames are added or removed, but will + always be at least one. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + FrameSet + }{ + All FrameSets have this attribute. + } + } +} +\sstroutine{ + Nin +}{ + Number of input coordinates for a Mapping +}{ + \sstdescription{ + This attribute gives the number of coordinate values required to + specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of + dimensions of the space in which the Mapping\texttt{'} s input points + reside). + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + If a CmpMap\texttt{'} s component Mappings are joined in series, then + its Nin attribute is equal to the Nin attribute of the first + component (or to the \htmlref{Nout}{Nout} attribute of the second component + if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). + + If a CmpMap\texttt{'} s component Mappings are joined in parallel, then + its Nin attribute is given by the sum of the Nin attributes + of each component (or to the sum of their Nout attributes if + the CmpMap\texttt{'} s Invert attribute is non-zero). + } + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + The Nin attribute for a Frame is always equal to the number + of Frame axes (\htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Nin attribute of a FrameSet is equal to the number of + axes (Naxes attribute) of its base Frame (as specified by the + FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may + therefore change if a new base Frame is selected. + } + } +} +\sstroutine{ + NiterInverse +}{ + Maximum number of iterations for the iterative inverse transformation +}{ + \sstdescription{ + This attribute controls the iterative inverse transformation + used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. + + Its value gives the maximum number of iterations of the + Newton-Raphson algorithm to be used for each transformed position. + The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{PolyMap}{PolyMap} + }{ + All PolyMaps have this attribute. + } + } +} +\sstroutine{ + Nkey +}{ + Number of unique FITS keywords in a FitsChan +}{ + \sstdescription{ + This attribute gives the total number of unique FITS keywords + stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or + deleted. If no keyword occurrs more than once in the FitsChan, the + \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs + more than once, the Nkey attribute value will be smaller than + the Ncard attribute value. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + Nobject +}{ + Number of Objects in class +}{ + \sstdescription{ + This attribute gives the total number of Objects currently in + existence in the same class as the \htmlref{Object}{Object} whose attribute value + is requested. This count does not include Objects which belong + to derived (more specialised) classes. + + This attribute is mainly intended for debugging. It can be used + to detect whether Objects which should have been deleted have, + in fact, been deleted. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + Norm(axis) +}{ + Specifies the plane upon which a Plot3D draws text and markers +}{ + \sstdescription{ + This attribute controls the appearance of text and markers drawn + by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which + text and markers will be drawn by all subsequent invocations of the + \htmlref{astText}{astText} and \htmlref{astMark}{astMark} functions. + + When setting or getting the Norm attribute, the attribute name must + be qualified by an axis index in the range 1 to 3. The 3 elements of + the Norm attribute are together interpreted as a vector in 3D graphics + coordinates that is normal to the plane upon which text and marks + should be drawn. When testing or clearing the attribute, the axis + index is optional. If no index is supplied, then clearing the Norm + attribute will clear all three elements, and testing the Norm attribute + will return a non-zero value if any of the three elements are set. + + The default value is 1.0 for each of the 3 elements. The length of + the vector is insignificant, but an error will be reported when + attempting to draw text or markers if the vector has zero length. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Plot}{Plot} + }{ + All Plot3Ds have this attribute. + } + } +} +\sstroutine{ + NormUnit(axis) +}{ + Normalised physical units for formatted axis values +}{ + \sstdescription{ + The value of this read-only attribute is derived from the current + value of the Unit attribute. It will represent an equivalent system + of units to the Unit attribute, but will potentially be simplified. + For instance, if Unit is set to \texttt{"} s$*$(m/s)\texttt{"} , the NormUnit value will + be \texttt{"} m\texttt{"} . If no simplification can be performed, the value of the + NormUnit attribute will equal that of the Unit attribute. + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + All Frames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + Nout +}{ + Number of output coordinates for a Mapping +}{ + \sstdescription{ + This attribute gives the number of coordinate values generated + by a \htmlref{Mapping}{Mapping} to specify each output point (i.e. the number of + dimensions of the space in which the Mapping\texttt{'} s output points + reside). + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + If a CmpMap\texttt{'} s component Mappings are joined in series, then + its Nout attribute is equal to the Nout attribute of the + second component (or to the \htmlref{Nin}{Nin} attribute of the first + component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). + + If a CmpMap\texttt{'} s component Mappings are joined in parallel, then + its Nout attribute is given by the sum of the Nout attributes + of each component (or to the sum of their Nin attributes if + the CmpMap\texttt{'} s Invert attribute is non-zero). + } + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + The Nout attribute for a Frame is always equal to the number + of Frame axes (\htmlref{Naxes}{Naxes} attribute). + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Nout attribute of a FrameSet is equal to the number of + FrameSet axes (Naxes attribute) which, in turn, is equal to + the Naxes attribute of the FrameSet\texttt{'} s current Frame (as + specified by the \htmlref{Current}{Current} attribute). The Nout attribute value + may therefore change if a new current Frame is selected. + } + } +} +\sstroutine{ + Nparameter +}{ + The number of global parameters in the table +}{ + \sstdescription{ + This attribute holds the number of global parameters currently in the table. + Parameters are added and removed using the + \htmlref{astAddParameter}{astAddParameter} and \htmlref{astRemoveParameter}{astRemoveParameter} + functions. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Table}{Table} + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + Nrow +}{ + The number of rows in the table +}{ + \sstdescription{ + This attribute holds the index of the last row to which any + contents have been added using any of the + astMapPut... + AST\_MAPPUT... + functions. The first row has index 1. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Table}{Table} + }{ + All Tables have this attribute. + } + } +} +\sstroutine{ + NumLab(axis) +}{ + Draw numerical axis labels for a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether labels should be drawn to represent the numerical values + along each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each + physical axis of a Plot so that, for instance, the setting + \texttt{"} NumLab(2)=1\texttt{"} specifies that numerical labels should be drawn + for the second axis. + + If the NumLab value of a Plot axis is non-zero (the default), + then numerical labels will be drawn for that axis, otherwise + they will be omitted. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The drawing of associated descriptive axis labels for a Plot + (describing the quantity being plotted along each axis) is + controlled by the \htmlref{TextLab(axis)}{TextLab(axis)} attribute. + + \sstitem + If no axis is specified, (e.g. \texttt{"} NumLab\texttt{"} instead of + \texttt{"} NumLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect the + attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the NumLab(1) value. + } + } +} +\sstroutine{ + NumLabGap(axis) +}{ + Spacing of numerical labels for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + where numerical axis labels are placed relative to the axes they + describe. It takes a separate value for each physical axis of a + \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} NumLabGap(2)=-0.01\texttt{"} + specifies where the numerical label for the second axis should + be drawn. + + For each axis, the NumLabGap value gives the spacing between the + axis line (or edge of the plotting area, if appropriate) and the + nearest edge of the corresponding numerical axis + labels. Positive values cause the descriptive label to be placed + on the opposite side of the line to the default tick marks, + while negative values cause it to be placed on the same side. + + The NumLabGap value should be given as a fraction of the minimum + dimension of the plotting area, the default value being $+$0.01. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} NumLabGap\texttt{"} instead of + \texttt{"} NumLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the NumLabGap(1) value. + } + } +} +\sstroutine{ + ObjSize +}{ + The in-memory size of the Object +}{ + \sstdescription{ + This attribute gives the total number of bytes of memory used by + the \htmlref{Object}{Object}. This includes any Objects which are encapsulated within + the supplied Object. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + ObsAlt +}{ + The geodetic altitude of the observer +}{ + \sstdescription{ + This attribute specifies the geodetic altitude of the observer, in + metres, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} + class makes no use of this attribute, but specialised subclasses of + Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} + classes use it. The default value is zero. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + \sstsubsection{ + SpecFrame + }{ + Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, + it defines the Doppler shift introduced by the observers diurnal + motion around the earths axis, which is needed when converting to + or from the topocentric standard of rest. The maximum velocity + error which can be caused by an incorrect value is 0.5 km/s. The + default value for the attribute is zero. + } + \sstsubsection{ + TimeFrame + }{ + Together with the ObsLon attribute, it is used when converting + between certain time scales (TDB, TCB, LMST, LAST) + } + } +} +\sstroutine{ + ObsLat +}{ + The geodetic latitude of the observer +}{ + \sstdescription{ + This attribute specifies the geodetic latitude of the observer, in + degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} + class makes no use of this attribute, but specialised subclasses of + Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} + classes use it. The default value is zero. + + The value is stored internally in radians, but is converted to and + from a degrees string for access. Some example input formats are: + \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} , + \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can + optionally be indicated using characters \texttt{"} N\texttt{"} and \texttt{"} S\texttt{"} in place of the + usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the + format \texttt{"} [s]dd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} N\texttt{"} or \texttt{"} S\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + \sstsubsection{ + SpecFrame + }{ + Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, + it defines the Doppler shift introduced by the observers diurnal + motion around the earths axis, which is needed when converting to + or from the topocentric standard of rest. The maximum velocity + error which can be caused by an incorrect value is 0.5 km/s. The + default value for the attribute is zero. + } + \sstsubsection{ + TimeFrame + }{ + Together with the ObsLon attribute, it is used when converting + between certain time scales (TDB, TCB, LMST, LAST) + } + } +} +\sstroutine{ + ObsLon +}{ + The geodetic longitude of the observer +}{ + \sstdescription{ + This attribute specifies the geodetic (or equivalently, geocentric) + longitude of the observer, in degrees, measured positive eastwards. + See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this + attribute, but specialised subclasses of Frame may use it. For instance, + the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value + is zero. + + The value is stored internally in radians, but is converted to and + from a degrees string for access. Some example input formats are: + \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} , + \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can + optionally be indicated using characters \texttt{"} E\texttt{"} and \texttt{"} W\texttt{"} in place of the + usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the + format \texttt{"} [s]ddd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} E\texttt{"} or \texttt{"} W\texttt{"} and the + numerical value is chosen to be less than 180 degrees. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + \sstsubsection{ + SpecFrame + }{ + Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, + it defines the Doppler shift introduced by the observers diurnal + motion around the earths axis, which is needed when converting to + or from the topocentric standard of rest. The maximum velocity + error which can be caused by an incorrect value is 0.5 km/s. The + default value for the attribute is zero. + } + \sstsubsection{ + TimeFrame + }{ + Together with the ObsLon attribute, it is used when converting + between certain time scales (TDB, TCB, LMST, LAST) + } + } +} +\sstroutine{ + PVMax(i) +}{ + Maximum number of FITS-WCS projection parameters +}{ + \sstdescription{ + This attribute specifies the largest legal index for a PV projection + parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the + largest legal value for \texttt{"} m\texttt{"} when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"} attribute). + The axis index is specified by i, and should be in the range 1 to 99. + The value for each axis is determined by the projection type specified + when the WcsMap + is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be + changed. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } +} +\sstroutine{ + PVi\_m +}{ + FITS-WCS projection parameters +}{ + \sstdescription{ + This attribute specifies the projection parameter values to be + used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection. + Each PV attribute name should include two integers, i and m, + separated by an underscore. The axis index is specified + by i, and should be in the range 1 to 99. The parameter number + is specified by m, and should be in the range 0 to 99. For + example, \texttt{"} PV2\_1=45.0\texttt{"} would specify a value for projection + parameter 1 of axis 2 in a WcsMap. + + These projection parameters correspond exactly to the values + stored using the FITS-WCS keywords \texttt{"} PV1\_1\texttt{"} , \texttt{"} PV1\_2\texttt{"} , etc. This + means that projection parameters which correspond to angles must + be given in degrees (despite the fact that the angular + coordinates and other attributes used by a WcsMap are in + radians). + + The set of projection parameters used by a WcsMap depends on the + type of projection, which is determined by its \htmlref{WcsType}{WcsType} + parameter. Most projections either do not require projection + parameters, or use parameters 1 and 2 associated with the latitude + axis. You should consult the FITS-WCS paper for details. + + Some projection parameters have default values (as defined in + the FITS-WCS paper) which apply if no explicit value is given. + You may omit setting a value for these \texttt{"} optional\texttt{"} parameters and the + default will apply. Some projection parameters, however, have no + default and a value must be explicitly supplied. This is most + conveniently + done using the \texttt{"} options\texttt{"} argument of \htmlref{astWcsMap}{astWcsMap} (q.v.) when a WcsMap + is first created. An error will result when a WcsMap is used to + transform coordinates if any of its required projection + parameters has not been set and lacks a default value. + + A \texttt{"} get\texttt{"} operation for a parameter which has not been assigned a value + will return the default value defined in the FITS-WCS paper, or + AST\_\_BAD if the paper indicates that the parameter has no default. + A default value of zero is returned for parameters which are not + accessed by the projection. + + Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude + axis to hold the native longitude and latitude of the fiducial + point of the projection, in degrees. The default values for these + parameters are determined by the projection type. The AST-specific + TPN projection does not use this convention - all projection + parameters for both axes are used to represent polynomical correction + terms, and the native longitude and latitude at the fiducial point may + not be changed from the default values of zero and 90 degrees. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The value of this attribute may changed only if the WcsMap + has no more than one reference. That is, an error is reported if the + WcsMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + + \sstitem + If the projection parameter values given for a WcsMap do not + satisfy all the required constraints (as defined in the FITS-WCS + paper), then an error will result when the WcsMap is used to + transform coordinates. + } + } +} +\sstroutine{ + PcdCen(axis) +}{ + Centre coordinates of pincushion/barrel distortion +}{ + \sstdescription{ + This attribute specifies the centre of the pincushion/barrel + distortion implemented by a \htmlref{PcdMap}{PcdMap}. It takes a separate value for + each axis of the PcdMap so that, for instance, the settings + \texttt{"} PcdCen(1)=345.0,PcdCen(2)=-104.4\texttt{"} specify that the pincushion + distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2 + respectively. This attribute is set when a PcdMap is created, but may + later be modified. If the attribute is cleared, the default value for + both axes is zero. + + Note, the value of this attribute may changed only if the PcdMap + has no more than one reference. That is, an error is reported if the + PcdMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + PcdMap + }{ + All PcdMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If no axis is specified, (e.g. \texttt{"} PcdCen\texttt{"} instead of + \texttt{"} PcdCen(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of both axes, while a \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} + operation will use just the PcdCen(1) value. + } + } +} +\sstroutine{ + Permute +}{ + Permute axis order? +}{ + \sstdescription{ + This attribute is a boolean value which controls how a \htmlref{Frame}{Frame} + behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match + another (target) Frame. It specifies whether the axis order of + the target Frame may be permuted in order to obtain a match. + + If the template\texttt{'} s Permute value is zero, it will match a target + only if it can do so without changing the order of its + axes. Otherwise, it will attempt to permute the target\texttt{'} s axes as + necessary. + + The default value is 1, so that axis permutation will be attempted. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. However, the Frame class + effectively ignores this attribute and behaves as if it has + the value 1. This is because the axes of a basic Frame are + not distinguishable and will always match any other Frame + whatever their order. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + Unlike a basic Frame, the SkyFrame class makes use of this + attribute. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Permute attribute of a FrameSet is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } +} +\sstroutine{ + PolarLong +}{ + The longitude value to assign to either pole +}{ + \sstdescription{ + This attribute holds the longitude value, in radians, to be + returned when a Cartesian position corresponding to either the north + or south pole is transformed into spherical coordinates. The + default value is zero. + + Note, the value of this attribute may changed only if the \htmlref{SphMap}{SphMap} + has no more than one reference. That is, an error is reported if the + SphMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + SphMap + }{ + All SphMaps have this attribute. + } + } +} +\sstroutine{ + PolyTan +}{ + Use PVi\_m keywords to define distorted TAN projection? +}{ + \sstdescription{ + This attribute is a boolean value which specifies how FITS \texttt{"} TAN\texttt{"} + projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign + encoded FITS header. If zero, the projection is assumed to conform + to the published FITS-WCS standard. If positive, the convention + for a distorted TAN projection included in an early draft version + of FITS-WCS paper II are assumed. In this convention the + coefficients of a polynomial distortion to be applied to + intermediate world coordinates are specified by the \htmlref{PVi\_m}{PVi\_m} keywords. + This convention was removed from the paper before publication and so + does not form part of the standard. Indeed, it is incompatible with + the published standard because it re-defines the meaning of the + first five PVi\_m keywords on the longitude axis, which are reserved + by the published standard for other purposes. However, headers that + use this convention are still to be found, for instance the SCAMP + utility (http://www.astromatic.net/software/scamp) creates them. + + The default value for the PolyTan attribute is -1. A negative + values causes the used convention to depend on the contents + of the \htmlref{FitsChan}{FitsChan}. If the FitsChan contains any PVi\_m keywords for + the latitude axis, or if it contains PVi\_m keywords for the + longitude axis with \texttt{"} m\texttt{"} greater than 4, then the distorted TAN + convention is used. Otherwise, the standard convention is used. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + PreserveAxes +}{ + Preserve axes? +}{ + \sstdescription{ + This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by + \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It + determines which axes appear (and in what order) in the \texttt{"} result\texttt{"} + Frame produced. + + If PreserveAxes is zero in the template Frame, then the result + Frame will have the same number (and order) of axes as the + template. If it is non-zero, however, the axes of the target + Frame will be preserved, so that the result Frame will have the + same number (and order) of axes as the target. + + The default value is zero, so that target axes are not preserved + and the result Frame resembles the template. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + All Frames have this attribute. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The PreserveAxes attribute of a FrameSet is the same as that + of its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } +} +\sstroutine{ + ProjP(m) +}{ + FITS-WCS projection parameters +}{ + \sstdescription{ + This attribute provides aliases for the PV attributes, which + specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap} + when implementing a FITS-WCS sky projection. ProjP is retained for + compatibility with previous versions of FITS-WCS and AST. New + applications should use the PV attibute instead. + + Attributes ProjP(0) to ProjP(9) correspond to attributes PV$<$axlat$>$\_0 + to PV$<$axlat$>$\_9, where $<$axlat$>$ is replaced by the index of the + latitude axis (given by attribute WcsAxis(2)). See PV for further + details. + + Note, the value of this attribute may changed only if the WcsMap + has no more than one reference. That is, an error is reported if the + WcsMap has been cloned, either by including it within another object + such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } +} +\sstroutine{ + Projection +}{ + Sky projection description +}{ + \sstdescription{ + This attribute provides a place to store a description of the + type of sky projection used when a \htmlref{SkyFrame}{SkyFrame} is attached to a + 2-dimensional object, such as an image or plotting surface. For + example, typical values might be \texttt{"} orthographic\texttt{"} , \texttt{"} Hammer-Aitoff\texttt{"} + or \texttt{"} cylindrical equal area\texttt{"} . + + The Projection value is purely descriptive and does not affect + the celestial coordinate system represented by the SkyFrame in + any way. If it is set to a non-blank string, the description + provided may be used when forming the default value for the + SkyFrame\texttt{'} s \htmlref{Title}{Title} attribute (so that typically it will appear in + graphical output, for instance). The default value is an empty + string. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + RefCount +}{ + Count of active Object pointers +}{ + \sstdescription{ + This attribute gives the number of active pointers associated + with an \htmlref{Object}{Object}. It is modified whenever pointers are created or + annulled (by \htmlref{astClone}{astClone}, \htmlref{astAnnul}{astAnnul} or \htmlref{astEnd}{astEnd} for example). The count + includes the initial pointer issued when the Object was created. + + If the reference count for an Object falls to zero as the result + of annulling a pointer to it, then the Object will be deleted. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + RefDec +}{ + The declination of the reference point +}{ + \sstdescription{ + This attribute specifies the FK5 J2000.0 declination of a reference + point on the sky. See the description of attribute \htmlref{RefRA}{RefRA} for details. + The default RefDec is \texttt{"} 0:0:0\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + RefRA +}{ + The right ascension of the reference point +}{ + \sstdescription{ + This attribute, together with the \htmlref{RefDec}{RefDec} attribute, specifies the FK5 + J2000.0 coordinates of a reference point on the sky. For 1-dimensional + spectra, this should normally be the position of the source. For + spectral data with spatial coverage (spectral cubes, etc), this should + be close to centre of the spatial coverage. It is used to define the + correction for Doppler shift to be applied when using the + \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert} + method to convert between different standards of rest. + + The \htmlref{SpecFrame}{SpecFrame} class assumes this velocity correction is spatially + invariant. If a single SpecFrame is used (for instance, as a + component of a \htmlref{CmpFrame}{CmpFrame}) to describe spectral values at different + points on the sky, then it is assumes that the doppler shift at any + spatial position is the same as at the reference position. The + maximum velocity error introduced by this assumption is of the order + of V$*$SIN(FOV), where FOV is the angular field of view, and V is the + relative velocity of the two standards of rest. As an example, when + correcting from the observers rest frame (i.e. the topocentric rest + frame) to the kinematic local standard of rest the maximum value of V + is about 20 km/s, so for 5 arc-minute field of view the maximum velocity + error introduced by the correction will be about 0.03 km/s. As another + example, the maximum error when correcting from the observers rest frame + to the local group is about 5 km/s over a 1 degree field of view. + + The RefRA and RefDec attributes are stored internally in radians, but + are converted to and from a string for access. The format \texttt{"} hh:mm:ss.ss\texttt{"} + is used for RefRA, and \texttt{"} dd:mm:ss.s\texttt{"} is used for RefDec. The methods + \htmlref{astSetRefPos}{astSetRefPos} and \htmlref{astGetRefPos}{astGetRefPos} may be used to access the values of + these attributes directly as unformatted values in radians. + + The default for RefRA is \texttt{"} 0:0:0\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + SpecFrame + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + RegionClass +}{ + The AST class name of the Region encapsulated within an Stc +}{ + \sstdescription{ + This is a read-only attribute giving the AST class name of the + \htmlref{Region}{Region} encapsulated within an \htmlref{Stc}{Stc} (that is, the class of the Region + which was supplied when the Stc was created). + } + \sstattributetype{ + String, read-only. + } + \sstapplicability{ + \sstsubsection{ + Stc + }{ + All Stc objects this attribute. + } + } +} +\sstroutine{ + Report +}{ + Report transformed coordinates? +}{ + \sstdescription{ + This attribute controls whether coordinate values are reported + whenever a \htmlref{Mapping}{Mapping} is used to transform a set of points. If its + value is zero (the default), no report is made. However, if it + is non-zero, the coordinates of each point are reported (both + before and after transformation) by writing them to standard + output. + + This attribute is provided as an aid to debugging, and to avoid + having to report values explicitly in simple programs. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + When applied to a compound Mapping (CmpMap), only the Report + attribute of the CmpMap, and not those of its component + Mappings, is used. Coordinate information is never reported + for the component Mappings individually, only for the + complete CmpMap. + } + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + When applied to any Frame, the formatting capabilities of the + Frame (as provided by the \htmlref{astFormat}{astFormat} function) will be used to + format the reported coordinates. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + When applied to any FrameSet, the formatting capabilities of + the base and current Frames will be used (as above) to + individually format the input and output coordinates, as + appropriate. The Report attribute of a FrameSet is not itself + affected by selecting a new base or current Frame, but the + resulting formatting capabilities may be. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Unlike most other attributes, the value of the Report + attribute is not transferred when a Mapping is copied. Instead, + its value is undefined (and therefore defaults to zero) in any + copy. Similarly, it becomes undefined in any external + representation of a Mapping produced by the \htmlref{astWrite}{astWrite} function. + } + } +} +\sstroutine{ + ReportLevel +}{ + Determines which read/write conditions are reported +}{ + \sstdescription{ + This attribute determines which, if any, of the conditions that occur + whilst reading or writing an \htmlref{Object}{Object} should be reported. These + conditions will generate either a fatal error or a warning, as + determined by attribute \htmlref{Strict}{Strict}. ReportLevel can take any of the + following values: + + 0 - Do not report any conditions. + + 1 - \htmlref{Report}{Report} only conditions where significant information content has been + changed. For instance, an unsupported time-scale has been replaced by a + supported near-equivalent time-scale. Another example is if a basic + \htmlref{Channel}{Channel} unexpected encounters data items that may have been introduced + by later versions of AST. + + 2 - Report the above, and in addition report significant default + values. For instance, if no time-scale was specified when reading an + Object from an external data source, report the default time-scale + that is being used. + + 3 - Report the above, and in addition report any other potentially + interesting conditions that have no significant effect on the + conversion. For instance, report if a time-scale of \texttt{"} TT\texttt{"} + (terrestrial time) is used in place of \texttt{"} ET\texttt{"} (ephemeris time). This + change has no signficiant effect because ET is the predecessor of, + and is continuous with, TT. Synonyms such as \texttt{"} IAT\texttt{"} and \texttt{"} TAI\texttt{"} are + another example. + + The default value is 1. Note, there are many other conditions that + can occur whilst reading or writing an Object that completely + prevent the conversion taking place. Such conditions will always + generate errors, irrespective of the ReportLevel and Strict attributes. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + All Channels have this attribute. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + All the conditions selected by the FitsChan \htmlref{Warnings}{Warnings} attribute are + reported at level 1. + } + } +} +\sstroutine{ + RestFreq +}{ + The rest frequency +}{ + \sstdescription{ + This attribute specifies the frequency corresponding to zero + velocity. It is used when converting between between velocity-based + coordinate systems and and other coordinate systems (such as frequency, + wavelength, energy, etc). The default value is 1.0E5 GHz. + + When setting a new value for this attribute, the new value can be + supplied either directly as a frequency, or indirectly as a wavelength + or energy, in which case the supplied value is converted to a frequency + before being stored. The nature of the supplied value is indicated by + appending text to the end of the numerical value indicating the units in + which the value is supplied. If the units are not specified, then the + supplied value is assumed to be a frequency in units of GHz. If the + supplied unit is a unit of frequency, the supplied value is assumed to + be a frequency in the given units. If the supplied unit is a unit of + length, the supplied value is assumed to be a (vacuum) wavelength. If + the supplied unit is a unit of energy, the supplied value is assumed to + be an energy. For instance, the following strings all result in + a rest frequency of around 1.4E14 Hz being used: \texttt{"} 1.4E5\texttt{"} , \texttt{"} 1.4E14 Hz\texttt{"} , + \texttt{"} 1.4E14 s$*$$*$-1\texttt{"} , \texttt{"} 1.4E5 GHz\texttt{"} , \texttt{"} 2.14E-6 m\texttt{"} , \texttt{"} 21400 Angstrom\texttt{"} , \texttt{"} 9.28E-20 J\texttt{"} , + \texttt{"} 9.28E-13 erg\texttt{"} , \texttt{"} 0.58 eV\texttt{"} , etc. + + When getting the value of this attribute, the returned value is + always a frequency in units of GHz. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + RootCorner +}{ + Specifies which edges of the 3D box should be annotated +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + which edges of the cube enclosing the 3D graphics space are used + for displaying numerical and descriptive axis labels. The attribute + value identifies one of the eight corners of the cube within + which graphics are being drawn (i.e. the cube specified by the + \texttt{"} graphbox\texttt{"} parameter when \htmlref{astPlot3D}{astPlot3D} + was called tp create the \htmlref{Plot3D}{Plot3D}). \htmlref{Axis}{Axis} labels and tick marks will + be placed on the three cube edges that meet at the given corner. + + The attribute value should consist of three character, each of + which must be either \texttt{"} U\texttt{"} or \texttt{"} L\texttt{"} . The first character in the string + specifies the position of the corner on the first graphics axis. + If the character is \texttt{"} U\texttt{"} then the corner is at the upper bound on the + first graphics axis. If it is \texttt{"} L\texttt{"} , then the corner is at the lower + bound on the first axis. Likewise, the second and third characters + in the string specify the location of the corner on the second and + third graphics axes. + + For instance, corner \texttt{"} LLL\texttt{"} is the corner that is at the lower bound + on all three graphics axes, and corner \texttt{"} ULU\texttt{"} is at the upper bound + on axes 1 and 3 but at the lower bound on axis 2. + + The default value is \texttt{"} LLL\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Plot3D + }{ + All Plot3Ds have this attribute. + } + } +} +\sstroutine{ + Seed +}{ + Random number seed for a MathMap +}{ + \sstdescription{ + This attribute, which may take any integer value, determines the + sequence of random numbers produced by the random number functions in + \htmlref{MathMap}{MathMap} expressions. It is set to an unpredictable default value when + a MathMap is created, so that by default each MathMap uses a different + set of random numbers. + + If required, you may set this Seed attribute to a value of your + choosing in order to produce repeatable behaviour from the random + number functions. You may also enquire the Seed value (e.g. if an + initially unpredictable value has been used) and then use it to + reproduce the resulting sequence of random numbers, either from the + same MathMap or from another one. + + Clearing the Seed attribute gives it a new unpredictable default + value. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + MathMap + }{ + All MathMaps have this attribute. + } + } +} +\sstroutine{ + SideBand +}{ + Indicates which sideband a dual sideband spectrum represents +}{ + \sstdescription{ + This attribute indicates whether the \htmlref{DSBSpecFrame}{DSBSpecFrame} currently + represents its lower or upper sideband, or an offset from the local + oscillator frequency. When querying the current value, the returned + string is always one of \texttt{"} usb\texttt{"} (for upper sideband), \texttt{"} lsb\texttt{"} (for lower + sideband), or \texttt{"} lo\texttt{"} (for offset from the local oscillator frequency). + When setting a new value, any of the strings \texttt{"} lsb\texttt{"} , \texttt{"} usb\texttt{"} , \texttt{"} observed\texttt{"} , + \texttt{"} image\texttt{"} or \texttt{"} lo\texttt{"} may be supplied (case insensitive). The \texttt{"} observed\texttt{"} + sideband is which ever sideband (upper or lower) contains the central + spectral position given by attribute \htmlref{DSBCentre}{DSBCentre}, and the \texttt{"} image\texttt{"} + sideband is the other sideband. It is the sign of the \htmlref{IF}{IF} attribute + which determines if the observed sideband is the upper or lower + sideband. The default value for SideBand is the observed sideband. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + DSBSpecFrame + }{ + All DSBSpecFrames have this attribute. + } + } +} +\sstroutine{ + SimpFI +}{ + Forward-inverse MathMap pairs simplify? +}{ + \sstdescription{ + This attribute should be set to a non-zero value if applying a + \htmlref{MathMap}{MathMap}\texttt{'} s forward transformation, followed immediately by the matching + inverse transformation will always restore the original set of + coordinates. It indicates that AST may replace such a sequence of + operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered + while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). + + By default, the SimpFI attribute is zero, so that AST will not perform + this simplification unless you have set SimpFI to indicate that it is + safe to do so. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + MathMap + }{ + All MathMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For simplification to occur, the two MathMaps must be in series and + be identical (with textually identical transformation + functions). Functional equivalence is not sufficient. + + \sstitem + The consent of both MathMaps is required before simplification can + take place. If either has a SimpFI value of zero, then simplification + will not occur. + + \sstitem + The SimpFI attribute controls simplification only in the case where + a MathMap\texttt{'} s forward transformation is followed by the matching inverse + transformation. It does not apply if an inverse transformation is + followed by a forward transformation. This latter case is controlled + by the \htmlref{SimpIF}{SimpIF} attribute. + + \sstitem + The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those + defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"} and + \texttt{"} inv\texttt{"} parameters of its constructor function). If the MathMap is + inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the + SimpFI and SimpIF attributes will be interchanged. + } + } +} +\sstroutine{ + SimpIF +}{ + Inverse-forward MathMap pairs simplify? +}{ + \sstdescription{ + This attribute should be set to a non-zero value if applying a + \htmlref{MathMap}{MathMap}\texttt{'} s inverse transformation, followed immediately by the matching + forward transformation will always restore the original set of + coordinates. It indicates that AST may replace such a sequence of + operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered + while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}). + + By default, the SimpIF attribute is zero, so that AST will not perform + this simplification unless you have set SimpIF to indicate that it is + safe to do so. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + MathMap + }{ + All MathMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For simplification to occur, the two MathMaps must be in series and + be identical (with textually identical transformation + functions). Functional equivalence is not sufficient. + + \sstitem + The consent of both MathMaps is required before simplification can + take place. If either has a SimpIF value of zero, then simplification + will not occur. + + \sstitem + The SimpIF attribute controls simplification only in the case where + a MathMap\texttt{'} s inverse transformation is followed by the matching forward + transformation. It does not apply if a forward transformation is + followed by an inverse transformation. This latter case is controlled + by the \htmlref{SimpFI}{SimpFI} attribute. + + \sstitem + The \texttt{"} forward\texttt{"} and \texttt{"} inverse\texttt{"} transformations referred to are those + defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"} and + \texttt{"} inv\texttt{"} parameters of its constructor function). If the MathMap is + inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the + SimpFI and SimpIF attributes will be interchanged. + } + } +} +\sstroutine{ + SimpVertices +}{ + Simplify a Polygon by transforming its vertices? +}{ + \sstdescription{ + This attribute controls the behaviour of the + \htmlref{astSimplify}{astSimplify} + method when applied to a \htmlref{Polygon}{Polygon}. The simplified Polygon is created + by transforming the vertices from the \htmlref{Frame}{Frame} in which the Polygon + was originally defined into the Frame currently represented by the + Polygon. If SimpVertices is non-zero (the default) then this + simplified Polygon is returned without further checks. If SimpVertices + is zero, a check is made that the edges of the new Polygon do not + depart significantly from the edges of the original Polygon (as + determined by the uncertainty associated with the Polygon). This + could occur, for instance, if the \htmlref{Mapping}{Mapping} frrm the original to the + current Frame is highly non-linear. If this check fails, the + original unsimplified Polygon is returned without change. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Polygon + }{ + All Polygons have this attribute. + } + } +} +\sstroutine{ + SinkFile +}{ + Output file to which to data should be written +}{ + \sstdescription{ + This attribute specifies the name of a file to which the \htmlref{Channel}{Channel} + should write data. If specified it is used in preference to any sink + function specified when the Channel was created. + + Assigning a new value to this attribute will cause any previously + opened SinkFile to be closed. The first subsequent call to + \htmlref{astWrite}{astWrite} + will attempt to open the new file (an error will be reported if the + file cannot be opened), and write data to it. All subsequent call to + astWrite + will write data to the new file, until the SinkFile attribute is + cleared or changed. + + Clearing the attribute causes any open SinkFile to be closed. All + subsequent data writes will use the sink function specified when the + Channel was created, or will write to standard output if no sink + function was specified. + + If no value has been assigned to SinkFile, a null string will be + returned if an attempt is made to get the attribute value. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + When the FitsChan is destroyed, any headers in the FitsChan will be + written out to the sink file, if one is specified (if not, the + sink function used when the FitsChan was created is used). The + sink file is a text file (not a FITS file) containing one header + per line. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A new SinkFile will over-write any existing file with the same + name unless the existing file is write protected, in which case an + error will be reported. + + \sstitem + Any open SinkFile is closed when the Channel is deleted. + + \sstitem + If the Channel is copied or dumped + (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow}) + the SinkFile attribute is left in a cleared state in the output + Channel (i.e. the value of the SinkFile attribute is not copied). + } + } +} +\sstroutine{ + Size(element) +}{ + Character size for a Plot element +}{ + \sstdescription{ + This attribute determines the character size used when drawing + each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a + separate value for each graphical element so that, for instance, + the setting \texttt{"} Size(title)=2.0\texttt{"} causes the Plot title to be drawn + using twice the default character size. + + The range of character sizes available and the appearance of the + resulting text is determined by the underlying graphics system. + The default behaviour is for all graphical elements to be drawn + using the default character size supplied by this graphics + system. + } + \sstattributetype{ + Floating Point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of the graphical elements available, see the + description of the Plot class. + + \sstitem + If no graphical element is specified, (e.g. \texttt{"} Size\texttt{"} instead + of \texttt{"} Size(title)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will + affect the attribute value of all graphical elements, while a + \texttt{"} get\texttt{"} or \texttt{"} test\texttt{"} operation will use just the Size(TextLab) + value. + } + } +} +\sstroutine{ + SizeGuess +}{ + The expected size of the KeyMap +}{ + \sstdescription{ + This is attribute gives an estimate of the number of entries that + will be stored in the \htmlref{KeyMap}{KeyMap}. It is used to tune the internal + properties of the KeyMap for speed and efficiency. A larger value + will result in faster access at the expense of increased memory + requirements. However if the SizeGuess value is much larger than + the actual size of the KeyMap, then there will be little, if any, + speed gained by making the SizeGuess even larger. The default value + is 300. + + The value of this attribute can only be changed if the KeyMap is + empty. Its value can be set conveniently when creating the KeyMap. + An error will be reported if an attempt is made to set or clear the + attribute when the KeyMap contains any entries. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + All KeyMaps have this attribute. + } + } +} +\sstroutine{ + Skip +}{ + Skip irrelevant data? +}{ + \sstdescription{ + This is a boolean attribute which indicates whether the \htmlref{Object}{Object} + data being read through a \htmlref{Channel}{Channel} are inter-mixed with other, + irrelevant, external data. + + If Skip is zero (the default), then the source of input data is + expected to contain descriptions of AST Objects and comments and + nothing else (if anything else is read, an error will + result). If Skip is non-zero, then any non-Object data + encountered between Objects will be ignored and simply skipped + over in order to reach the next Object. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + All Channels have this attribute. + } + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + The FitsChan class sets the default value of this attribute + to 1, so that all irrelevant FITS headers will normally be + ignored. + } + } +} +\sstroutine{ + SkyRef(axis) +}{ + Position defining the offset coordinate system +}{ + \sstdescription{ + This attribute allows a \htmlref{SkyFrame}{SkyFrame} to represent offsets, rather than + absolute axis values, within the coordinate system specified by the + \htmlref{System}{System} attribute. If supplied, SkyRef should be set to hold the + longitude and latitude of a point within the coordinate system + specified by the System attribute. The coordinate system represented + by the SkyFrame will then be rotated in order to put the specified + position at either the pole or the origin of the new coordinate system + (as indicated by the \htmlref{SkyRefIs}{SkyRefIs} attribute). The orientation of the + modified coordinate system is then controlled using the SkyRefP + attribute. + + If an integer axis index is included in the attribute name (e.g. + \texttt{"} SkyRef(1)\texttt{"} ) then the attribute value should be supplied as a single + floating point axis value, in radians, when setting a value for the + attribute, and will be returned in the same form when getting the value + of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} + or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are + given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). + + If no axis index is included in the attribute name (e.g. \texttt{"} SkyRef\texttt{"} ) then + the attribute value should be supplied as a character string + containing two formatted axis values (an axis 1 value followed by a + comma, followed by an axis 2 value). The same form + will be used when getting the value of the attribute. + + The default values for SkyRef are zero longitude and zero latitude. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the System attribute of the SkyFrame is changed, any position + given for SkyRef is transformed into the new System. + + \sstitem + If a value has been assigned to SkyRef attribute, then + the default values for certain attributes are changed as follows: + the default axis Labels for the SkyFrame are modified by appending + \texttt{"} offset\texttt{"} to the end, the default axis Symbols for the SkyFrame are + modified by prepending the character \texttt{"} D\texttt{"} to the start, and the + default title is modified by replacing the projection information by the + origin information. + } + } + \sstdiytopic{ + Aligning SkyFrames with Offset Coordinate Systems + }{ + The offset coordinate system within a SkyFrame should normally be + considered as a superficial \texttt{"} re-badging\texttt{"} of the axes of the coordinate + system specified by the System attribute - it merely provides an + alternative numerical \texttt{"} label\texttt{"} for each position in the System coordinate + system. The SkyFrame retains full knowledge of the celestial coordinate + system on which the offset coordinate system is based (given by the + System attribute). For instance, the SkyFrame retains knowledge of the + way that one celestial coordinate system may \texttt{"} drift\texttt{"} with respect to + another over time. Normally, if you attempt to align two SkyFrames (e.g. + using the \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame} routine), + the effect of any offset coordinate system defined in either SkyFrame + will be removed, resulting in alignment being performed in the + celestial coordinate system given by the \htmlref{AlignSystem}{AlignSystem} attribute. + However, by setting the \htmlref{AlignOffset}{AlignOffset} attribute ot a non-zero value, it + is possible to change this behaviour so that the effect of the offset + coordinate system is not removed when aligning two SkyFrames. + } +} +\sstroutine{ + SkyRefIs +}{ + Selects the nature of the offset coordinate system +}{ + \sstdescription{ + This attribute controls how the values supplied for the SkyRef and + SkyRefP attributes are used. These three attributes together allow + a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin + or pole within the coordinate system specified by the \htmlref{System}{System} attribute, + rather than absolute axis values. SkyRefIs can take one of the + case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"} or \texttt{"} Ignored\texttt{"} . + + If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system + represented by the SkyFrame is modified to put the origin of longitude + and latitude at the position specified by the SkyRef attribute. + + If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented + by the SkyFrame is modified to put the north pole at the position + specified by the SkyRef attribute. + + If SkyRefIs is set to \texttt{"} Ignored\texttt{"} (the default), then any value set for the + SkyRef attribute is ignored, and the SkyFrame represents the coordinate + system specified by the System attribute directly without any rotation. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + SkyRefP(axis) +}{ + Position on primary meridian of offset coordinate system +}{ + \sstdescription{ + This attribute is used to control the orientation of the offset + coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used, + it should be set to hold the longitude and latitude of a point within + the coordinate system specified by the \htmlref{System}{System} attribute. The offset + coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in + order to put the position supplied for SkyRefP on the zero longitude + meridian. This rotation is about an axis from the centre of the + celestial sphere to the point specified by the SkyRef attribute. + The default value for SkyRefP is usually the north pole (that is, a + latitude of $+$90 degrees in the coordinate system specified by the System + attribute). The exception to this is if the SkyRef attribute is + itself set to either the north or south pole. In these cases the + default for SkyRefP is the origin (that is, a (0,0) in the coordinate + system specified by the System attribute). + + If an integer axis index is included in the attribute name (e.g. + \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single + floating point axis value, in radians, when setting a value for the + attribute, and will be returned in the same form when getting the value + of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} + or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are + given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). + + If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then + the attribute value should be supplied as a character string + containing two formatted axis values (an axis 1 value followed by a + comma, followed by an axis 2 value). The same form + will be used when getting the value of the attribute. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If the position given by the SkyRef attribute defines the origin + of the offset coordinate system (that is, if the SkyRefIs attribute + is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations + which will put the supplied SkyRefP position on the zero longitude + meridian. The orientation which is actually used is the one which + gives the SkyRefP position a positive latitude in the offset coordinate + system (the other possible orientation would give the SkyRefP position + a negative latitude). + + \sstitem + An error will be reported if an attempt is made to use a + SkyRefP value which is co-incident with SkyRef or with the point + diametrically opposite to SkyRef on the celestial sphere. The + reporting of this error is deferred until the SkyRef and SkyRefP + attribute values are used within a calculation. + + \sstitem + If the System attribute of the SkyFrame is changed, any position + given for SkyRefP is transformed into the new System. + } + } +} +\sstroutine{ + SkyTol +}{ + The smallest significant shift in sky coordinates +}{ + \sstdescription{ + This attribute indicates the accuracy of the axis values that will + be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two + positions within the SkyFrame is smaller than the value of SkyTol, + then the two positions will (for the puposes indicated below) be + considered to be co-incident. + + This value is used only when constructing the \htmlref{Mapping}{Mapping} between + two different SkyFrames (for instance, when calling + \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame}). + If the transformation between the two SkyFrames causes positions to + shift by less than SkyTol arc-seconds, then the transformation is + replaced by a \htmlref{UnitMap}{UnitMap}. This could in certain circumatances allow + major simplifications to be made to the transformation between + any pixel grids associated with the two SkyFrames (for instance, if + each SkyFrame is part of the WCS \htmlref{FrameSet}{FrameSet} associated with an image). + + A common case is when two SkyFrames use the FK5 system, but have + slightly different \htmlref{Epoch}{Epoch} values. If the \htmlref{AlignSystem}{AlignSystem} attribute has + its default value of \texttt{"} ICRS\texttt{"} , then the transformation between the + two SkyFrames will include a very small rotation (FK5 rotates with + respect to ICRS as a rate of about 0.0005 arc-seconds per year). In + most circumstances such a small rotation is insignificant. Setting + SkyTol to some suitably small non-zero value will cause this + rotation to be ignored, allowing much simpler transformations to + be used. + + The test to determine the shift introduced by transforming between + the two SkyFrames is performed by transforming a set of 14 position + spread evenly over the whole sky. The largest shift produced at any + of these 14 positions is compared to the value of SkyTol. + + The SkyTol value is in units of arc-seconds, and the default value + is 0.001. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + SkyFrame + }{ + All SkyFrames have this attribute. + } + } +} +\sstroutine{ + SortBy +}{ + Determines how keys are sorted in a KeyMap +}{ + \sstdescription{ + This attribute determines the order in which keys are returned by the + \htmlref{astMapKey}{astMapKey} + function. It may take the following values (the default is \texttt{"} None\texttt{"} ): + + \sstitemlist{ + + \sstitem + \texttt{"} None\texttt{"} : The keys are returned in an arbitrary order. This is the + fastest method as it avoids the need for a sorted list of keys to + be maintained and used. + + \sstitem + \texttt{"} AgeDown\texttt{"} : The keys are returned in the order in which values were + stored in the \htmlref{KeyMap}{KeyMap}, with the key for the most recent value being + returned last. If the value of an existing entry is changed, it goes + to the end of the list. + + \sstitem + \texttt{"} AgeUp\texttt{"} : The keys are returned in the order in which values were + stored in the KeyMap, with the key for the most recent value being + returned first. If the value of an existing entry is changed, it goes + to the top of the list. + + \sstitem + \texttt{"} KeyAgeDown\texttt{"} : The keys are returned in the order in which they + were originally stored in the KeyMap, with the most recent key being + returned last. If the value of an existing entry is changed, its + position in the list does not change. + + \sstitem + \texttt{"} KeyAgeUp\texttt{"} : The keys are returned in the order in which they + were originally stored in the KeyMap, with the most recent key being + returned first. If the value of an existing entry is changed, its + position in the list does not change. + + \sstitem + \texttt{"} KeyDown\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} + being returned last. + + \sstitem + \texttt{"} KeyUp\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"} + being returned first. + } + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + KeyMap + }{ + All KeyMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If a new value is assigned to SortBy (or if SortBy is cleared), + all entries currently in the KeyMap are re-sorted according to the + new SortBy value. + } + } +} +\sstroutine{ + SourceFile +}{ + Input file from which to read data +}{ + \sstdescription{ + This attribute specifies the name of a file from which the \htmlref{Channel}{Channel} + should read data. If specified it is used in preference to any source + function specified when the Channel was created. + + Assigning a new value to this attribute will cause any previously + opened SourceFile to be closed. The first subsequent call to + \htmlref{astRead}{astRead} + will attempt to open the new file (an error will be reported if the + file cannot be opened), and read data from it. All subsequent call to + astRead + will read data from the new file, until the SourceFile attribute is + cleared or changed. + + Clearing the attribute causes any open SourceFile to be closed. All + subsequent data reads will use the source function specified when the + Channel was created, or will read from standard input if no source + function was specified. + + If no value has been assigned to SourceFile, a null string will be + returned if an attempt is made to get the attribute value. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{FitsChan}{FitsChan} + }{ + In the case of a FitsChan, the specified SourceFile supplements + the source function specified when the FitsChan was created, + rather than replacing the source function. The source file + should be a text file (not a FITS file) containing one header per + line. When a value is assigned to SourceFile, the file is opened + and read immediately, and all headers read from the file are + appended to the end of any header already in the FitsChan. The file + is then closed. Clearing the SourceFile attribute has no further + effect, other than nullifying the string (i.e. the file name) + associated with the attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Any open SourceFile is closed when the Channel is deleted. + + \sstitem + If the Channel is copied or dumped + (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow}) + the SourceFile attribute is left in a cleared state in the output + Channel (i.e. the value of the SourceFile attribute is not copied). + } + } +} +\sstroutine{ + SourceSys +}{ + Spectral system in which the source velocity is stored +}{ + \sstdescription{ + This attribute identifies the spectral system in which the + \htmlref{SourceVel}{SourceVel} attribute value (the source velocity) is supplied and + returned. It can be one of the following: + + \sstitemlist{ + + \sstitem + \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) + + \sstitem + \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) + + \sstitem + \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) + + \sstitem + \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) + + \sstitem + \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) + + } + When setting a new value for the SourceVel attribute, the source + velocity should be supplied in the spectral system indicated + by this attribute. Likewise, when getting the value of the SourceVel + attribute, the velocity will be returned in this spectral system. + + If the value of SourceSys is changed, the value stored for SourceVel + will be converted from the old to the new spectral systems. + + The default value is \texttt{"} VELO\texttt{"} (apparent radial velocity). + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + SourceVRF +}{ + Rest frame in which the source velocity is stored +}{ + \sstdescription{ + This attribute identifies the rest frame in which the source + velocity or redshift is stored (the source velocity or redshift is + accessed using attribute \htmlref{SourceVel}{SourceVel}). When setting a new value for the + SourceVel attribute, the source velocity or redshift should be supplied + in the rest frame indicated by this attribute. Likewise, when getting + the value of the SourceVel attribute, the velocity or redshift will be + returned in this rest frame. + + If the value of SourceVRF is changed, the value stored for SourceVel + will be converted from the old to the new rest frame. + + The values which can be supplied are the same as for the \htmlref{StdOfRest}{StdOfRest} + attribute (except that SourceVRF cannot be set to \texttt{"} Source\texttt{"} ). The + default value is \texttt{"} Helio\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + SourceVel +}{ + The source velocity +}{ + \sstdescription{ + This attribute (together with \htmlref{SourceSys}{SourceSys}, \htmlref{SourceVRF}{SourceVRF}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) + defines the \texttt{"} Source\texttt{"} standard of rest (see attribute \htmlref{StdOfRest}{StdOfRest}). This is + a rest frame which is moving towards the position given by RefRA and + RefDec at a velocity given by SourceVel. A positive value means + the source is moving away from the observer. When a new value is + assigned to this attribute, the supplied value is assumed to refer + to the spectral system specified by the SourceSys attribute. For + instance, the SourceVel value may be supplied as a radio velocity, a + redshift, a beta factor, etc. Similarly, when the current value of + the SourceVel attribute is obtained, the returned value will refer + to the spectral system specified by the SourceSys value. If the + SourceSys value is changed, any value previously stored for the SourceVel + attribute will be changed automatically from the old spectral system + to the new spectral system. + + When setting a value for SourceVel, the value should be supplied in the + rest frame specified by the SourceVRF attribute. Likewise, when getting + the value of SourceVel, it will be returned in the rest frame specified + by the SourceVRF attribute. + + The default SourceVel value is zero. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + All SpecFrames have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + It is important to set an appropriate value for SourceVRF and + SourceSys before setting a value for SourceVel. If a new value is later + set for SourceVRF or SourceSys, the value stored for SourceVel will + simultaneously be changed to the new standard of rest or spectral + system. + } + } +} +\sstroutine{ + SpecOrigin +}{ + The zero point for SpecFrame axis values +}{ + \sstdescription{ + This specifies the origin from which all spectral values are measured. + The default value (zero) results in the \htmlref{SpecFrame}{SpecFrame} describing + absolute spectral values in the system given by the \htmlref{System}{System} attribute + (e.g. frequency, velocity, etc). If a SpecFrame is to be used to + describe offset from some origin, the SpecOrigin attribute + should be set to hold the required origin value. The SpecOrigin value + stored inside the SpecFrame structure is modified whenever SpecFrame + attribute values are changed so that it refers to the original spectral + position. + + When setting a new value for this attribute, the supplied value is assumed + to be in the system, units and standard of rest described by the SpecFrame. + Likewise, when getting the value of this attribute, the value is returned + in the system, units and standard of rest described by the SpecFrame. If + any of these attributes are changed, then any previously stored SpecOrigin + value will also be changed so that refers to the new system, units or + standard of rest. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + SpecFrame + }{ + All SpecFrames have this attribute. + } + } +} +\sstroutine{ + SpecVal +}{ + The spectral position at which flux values are measured +}{ + \sstdescription{ + This attribute specifies the spectral position (frequency, wavelength, + etc.), at which the values described by the \htmlref{FluxFrame}{FluxFrame} are measured. + It is used when determining the \htmlref{Mapping}{Mapping} between between FluxFrames. + + The default value and spectral system used for this attribute are + both specified when the FluxFrame is created. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + FluxFrame + }{ + All FluxFrames have this attribute. + } + } +} +\sstroutine{ + StcsArea +}{ + Return the CoordinateArea component when reading an STC-S document? +}{ + \sstdescription{ + This is a boolean attribute which controls what is returned + by the + \htmlref{astRead}{astRead} + function when it is used to read from an \htmlref{StcsChan}{StcsChan}. + If StcsArea is set non-zero (the default), then a \htmlref{Region}{Region} + representing the STC CoordinateArea will be returned by + astRead. + If StcsArea is set to zero, then the STC CoordinateArea + will not be returned. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + StcsChan + }{ + All StcsChans have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} can be used to + specify other Objects to be returned by + astRead. + If more than one of these attributes is set non-zero, then the + actual \htmlref{Object}{Object} returned by + astRead + will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this + case, the Region representing the STC CoordinateArea will be + stored in the returned KeyMap using the key \texttt{"} AREA\texttt{"} . If StcsArea + is the only attribute to be set non-zero, then the Object returned by + astRead + will be the CoordinateArea Region itself. + + \sstitem + The class of Region used to represent the CoordinateArea for each + STC-S sub-phrase is determined by the first word in the + sub-phrase (the \texttt{"} sub-phrase identifier\texttt{"} ). The individual sub-phrase + Regions are combined into a single \htmlref{Prism}{Prism}, which is then simplified + using \htmlref{astSimplify}{astSimplify} + to form the returned region. + + \sstitem + Sub-phrases that represent a single value ( that is, have + identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} or \texttt{"} Redshift\texttt{"} ) are + considered to be be part of the STC CoordinateArea component. + + \sstitem + The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have + its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no + start time is specified by the sub-phrase, then the stop time will be + used instead. If no stop time is specified by the sub-phrase, then + the single time value specified in the sub-phrase will be used + instead. Subsequently clearing the TimeOrigin attribute (or setting + its value to zero) will cause the TimeFrame to reprsent absolute times. + + \sstitem + The \htmlref{Epoch}{Epoch} attribute for the returned Region is set in the same + way as the TimeOrigin attribute (see above). + } + } +} +\sstroutine{ + StcsCoords +}{ + Return the Coordinates component when reading an STC-S document? +}{ + \sstdescription{ + This is a boolean attribute which controls what is returned + by the + \htmlref{astRead}{astRead} + function when it is used to read from an \htmlref{StcsChan}{StcsChan}. + If StcsCoords is set non-zero, then a \htmlref{PointList}{PointList} + representing the STC Coordinates will be returned by + astRead. + If StcsCoords is set to zero (the default), then the STC + Coordinates will not be returned. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + StcsChan + }{ + All StcsChans have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Other attributes such as \htmlref{StcsArea}{StcsArea} and \htmlref{StcsProps}{StcsProps} can be used to + specify other Objects to be returned by + astRead. + If more than one of these attributes is set non-zero, then the + actual \htmlref{Object}{Object} returned by + astRead + will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this + case, the PointList representing the STC Coordinates will be + stored in the returned KeyMap using the key \texttt{"} COORDS\texttt{"} . If StcsCoords + is the only attribute to be set non-zero, then the Object returned by + astRead + will be the Coordinates PointList itself. + + \sstitem + The Coordinates component is specified by the additional axis + values embedded within the body of each STC-S sub-phrase that + represents an extended area. Sub-phrases that represent a single + value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"} + or \texttt{"} Redshift\texttt{"} ) are not considered to be be part of the STC + Coordinates component. + + \sstitem + If the STC-S documents does not contain a Coordinates component, + then a NULL object pointer + will be returned by + astRead + if the Coordinates component is the only object being returned. If + other objects are also being returned (see attributes StcsProps and + StcsArea), then the returned KeyMap will contain a \texttt{"} COORDS\texttt{"} key + only if the Coordinates component is read succesfully. + + \sstitem + The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have + its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no + start time is specified by the sub-phrase, then the stop time will be + used instead. If no stop time is specified by the sub-phrase, then + the single time value specified in the sub-phrase will be used + instead. Subsequently clearing the TimeOrigin attribute (or setting + its value to zero) will cause the TimeFrame to reprsent absolute times. + + \sstitem + The \htmlref{Epoch}{Epoch} attribute for the returned \htmlref{Region}{Region} is set in the same + way as the TimeOrigin attribute (see above). + } + } +} +\sstroutine{ + StcsLength +}{ + Controls output line length +}{ + \sstdescription{ + This attribute specifies the maximum length to use when writing out + text through the sink function supplied when the \htmlref{StcsChan}{StcsChan} was created. + It is ignored if the \htmlref{Indent}{Indent} attribute is zero (in which case the text + supplied to the sink function can be of any length). The default value + is 70. + + The number of characters in each string written out through the sink + function will not usually be greater than the value of this attribute + (but may be less). However, if any single word in the STC-S + description exceeds the specified length, then the word will be + written out as a single line. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + StcsChan + }{ + All StcsChans have this attribute. + } + } +} +\sstroutine{ + StcsProps +}{ + Return all properties when reading an STC-S document? +}{ + \sstdescription{ + This is a boolean attribute which controls what is returned + by the + \htmlref{astRead}{astRead} + function when it is used to read from an \htmlref{StcsChan}{StcsChan}. + If StcsProps is set non-zero, then a \htmlref{KeyMap}{KeyMap} containing all the + properties read from the STC-S document will be returned by + astRead. + If StcsProps is set to zero (the default), then the properties + will not be returned. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + StcsChan + }{ + All StcsChans have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsArea}{StcsArea} can be used to + specify other Objects to be returned by + astRead. + If more than one of these attributes is set non-zero, then the + actual \htmlref{Object}{Object} returned by + astRead + will be a KeyMap containing the requested Objects. In this + case, the properties KeyMap will be stored in the returned KeyMap + using the key \texttt{"} PROPS\texttt{"} . If StcsProps is the only attribute to be + set non-zero, then the Object returned by + astRead + will be the properties KeyMap itself. + + \sstitem + The KeyMap containing the properties will have entries for one or + more of the following keys: \texttt{"} TIME\_PROPS\texttt{"} , \texttt{"} SPACE\_PROPS\texttt{"} , \texttt{"} SPECTRAL\_PROPS\texttt{"} + and \texttt{"} REDSHIFT\_PROPS\texttt{"} . Each of these entries will be another KeyMap + containing the properties of the corresponding STC-S sub-phrase. + } + } +} +\sstroutine{ + StdOfRest +}{ + Standard of rest +}{ + \sstdescription{ + This attribute identifies the standard of rest to which the spectral + axis values of a \htmlref{SpecFrame}{SpecFrame} refer, and may take any of the values + listed in the \texttt{"} Standards of Rest\texttt{"} section (below). + + The default StdOfRest value is \texttt{"} Helio\texttt{"} . + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + SpecFrame + }{ + All SpecFrames have this attribute. + } + } + \sstdiytopic{ + Standards of Rest + }{ + The SpecFrame class supports the following StdOfRest values (all are + case-insensitive): + + \sstitemlist{ + + \sstitem + \texttt{"} Topocentric\texttt{"} , \texttt{"} Topocent\texttt{"} or \texttt{"} Topo\texttt{"} : The observers rest-frame (assumed + to be on the surface of the earth). Spectra recorded in this standard of + rest suffer a Doppler shift which varies over the course of a day + because of the rotation of the observer around the axis of the earth. + This standard of rest must be qualified using the \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon}, + \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes. + + \sstitem + \texttt{"} Geocentric\texttt{"} , \texttt{"} Geocentr\texttt{"} or \texttt{"} Geo\texttt{"} : The rest-frame of the earth centre. + Spectra recorded in this standard of rest suffer a Doppler shift which + varies over the course of a year because of the rotation of the earth + around the Sun. This standard of rest must be qualified using the Epoch, + RefRA and RefDec attributes. + + \sstitem + \texttt{"} Barycentric\texttt{"} , \texttt{"} Barycent\texttt{"} or \texttt{"} Bary\texttt{"} : The rest-frame of the solar-system + barycentre. Spectra recorded in this standard of rest suffer a Doppler + shift which depends both on the velocity of the Sun through the Local + Standard of Rest, and on the movement of the planets through the solar + system. This standard of rest must be qualified using the Epoch, RefRA + and RefDec attributes. + + \sstitem + \texttt{"} Heliocentric\texttt{"} , \texttt{"} Heliocen\texttt{"} or \texttt{"} Helio\texttt{"} : The rest-frame of the Sun. + Spectra recorded in this standard of rest suffer a Doppler shift which + depends on the velocity of the Sun through the Local Standard of Rest. + This standard of rest must be qualified using the RefRA and RefDec + attributes. + + \sstitem + \texttt{"} LSRK\texttt{"} , \texttt{"} LSR\texttt{"} : The rest-frame of the kinematical Local Standard of + Rest. Spectra recorded in this standard of rest suffer a Doppler shift + which depends on the velocity of the kinematical Local Standard of Rest + through the galaxy. This standard of rest must be qualified using the + RefRA and RefDec attributes. + + \sstitem + \texttt{"} LSRD\texttt{"} : The rest-frame of the dynamical Local Standard of Rest. Spectra + recorded in this standard of rest suffer a Doppler shift which depends + on the velocity of the dynamical Local Standard of Rest through the + galaxy. This standard of rest must be qualified using the RefRA and + RefDec attributes. + + \sstitem + \texttt{"} Galactic\texttt{"} , \texttt{"} Galactoc\texttt{"} or \texttt{"} Gal\texttt{"} : The rest-frame of the galactic centre. + Spectra recorded in this standard of rest suffer a Doppler shift which + depends on the velocity of the galactic centre through the local group. + This standard of rest must be qualified using the RefRA and RefDec + attributes. + + \sstitem + \texttt{"} Local\_group\texttt{"} , \texttt{"} Localgrp\texttt{"} or \texttt{"} LG\texttt{"} : The rest-frame of the local group. + This standard of rest must be qualified using the RefRA and RefDec + attributes. + + \sstitem + \texttt{"} Source\texttt{"} , or \texttt{"} src\texttt{"} : The rest-frame of the source. This standard of + rest must be qualified using the RefRA, RefDec and \htmlref{SourceVel}{SourceVel} attributes. + + } + Where more than one alternative \htmlref{System}{System} value is shown above, the + first of these will be returned when an enquiry is made. + } +} +\sstroutine{ + Strict +}{ + Report an error if any unexpeted data items are found? +}{ + \sstdescription{ + This is a boolean attribute which indicates whether a warning + rather than an error should be issed for insignificant conversion + problems. If it is set non-zero, then fatal errors are issued + instead of warnings, resulting in the + AST error status being set. + If Strict is zero (the default), then execution continues after minor + conversion problems, and a warning message is added to the \htmlref{Channel}{Channel} + structure. Such messages can be retrieved using the + \htmlref{astWarnings}{astWarnings} + function. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Channel + }{ + All Channels have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This attribute was introduced in AST version 5.0. Prior to this + version of AST unexpected data items read by a basic Channel always + caused an error to be reported. So applications linked against + versions of AST prior to version 5.0 may not be able to read \htmlref{Object}{Object} + descriptions created by later versions of AST, if the Object\texttt{'} s class + description has changed. + } + } +} +\sstroutine{ + Style(element) +}{ + Line style for a Plot element +}{ + \sstdescription{ + This attribute determines the line style used when drawing each + element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a + separate value for each graphical element so that, for instance, + the setting \texttt{"} Style(border)=2\texttt{"} causes the Plot border to be drawn + using line style 2 (which might result in, say, a dashed line). + + The range of integer line styles available and their appearance + is determined by the underlying graphics system. The default + behaviour is for all graphical elements to be drawn using the + default line style supplied by this graphics system (normally, + this is likely to give a solid line). + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of the graphical elements available, see the + description of the Plot class. + + \sstitem + If no graphical element is specified, (e.g. \texttt{"} Style\texttt{"} instead of + \texttt{"} Style(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the Style(\htmlref{Border}{Border}) value. + } + } +} +\sstroutine{ + Symbol(axis) +}{ + Axis symbol +}{ + \sstdescription{ + This attribute specifies a short-form symbol to be used to + represent coordinate values for a particular axis of a + \htmlref{Frame}{Frame}. This might be used (e.g.) in algebraic expressions where + a full description of the axis would be inappropriate. Examples + include \texttt{"} RA\texttt{"} and \texttt{"} Dec\texttt{"} (for Right Ascension and Declination). + + If a Symbol value has not been set for a Frame axis, then a + suitable default is supplied. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default Symbol value supplied by the Frame class is the + string \texttt{"} $<$\htmlref{Domain}{Domain}$>$$<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for successive + axes, and $<$Domain$>$ is the value of the Frame\texttt{'} s Domain + attribute (truncated if necessary so that the final string + does not exceed 15 characters). If no Domain value has been + set, \texttt{"} x\texttt{"} is used as the $<$Domain$>$ value in constructing this + default string. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Symbol value + (e.g. to \texttt{"} RA\texttt{"} or \texttt{"} Dec\texttt{"} ) as appropriate for the particular + celestial coordinate system being represented. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class re-defines the default Symbol value as + appropriate for the particular time system being represented. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Symbol attribute of a FrameSet axis is the same as that + of its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + System +}{ + Coordinate system used to describe positions within the domain +}{ + \sstdescription{ + In general it is possible for positions within a given physical + domain to be described using one of several different coordinate + systems. For instance, the \htmlref{SkyFrame}{SkyFrame} class can use galactic + coordinates, equatorial coordinates, etc, to describe positions on + the sky. As another example, the \htmlref{SpecFrame}{SpecFrame} class can use frequency, + wavelength, velocity, etc, to describe a position within an + electromagnetic spectrum. The System attribute identifies the particular + coordinate system represented by a \htmlref{Frame}{Frame}. Each class of Frame + defines a set of acceptable values for this attribute, as listed + below (all are case insensitive). Where more than one alternative + System value is shown, the first of will be returned when an + enquiry is made. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The System attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} , + and may not be altered. + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The System attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} , + and may not be altered. In addition, the CmpFrame class allows + the System attribute to be referenced for a component Frame by + including the index of an axis within the required component + Frame. For instance, \texttt{"} System(3)\texttt{"} refers to the System attribute + of the component Frame which includes axis 3 of the CmpFrame. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The System attribute of a FrameSet is the same as that of its + current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + \sstsubsection{ + SkyFrame + }{ + The SkyFrame class supports the following System values and + associated celestial coordinate systems: + + \sstitemlist{ + + \sstitem + \texttt{"} AZEL\texttt{"} : Horizon coordinates. The longitude axis is azimuth + such that geographic north has an azimuth of zero and geographic + east has an azimuth of $+$PI/2 radians. The zenith has elevation + $+$PI/2. When converting to and from other celestial coordinate + systems, no corrections are applied for atmospheric refraction + or polar motion (however, a correction for diurnal aberattion is + applied). Note, unlike most other + celestial coordinate systems, this system is right handed. Also, + unlike other SkyFrame systems, the AzEl system is sensitive to + the timescale in which the \htmlref{Epoch}{Epoch} value is supplied. This is + because of the gross diurnal rotation which this system undergoes, + causing a small change in time to translate to a large rotation. + When converting to or from an AzEl system, the Epoch value for + both source and destination SkyFrames should be supplied in the + TDB timescale. The difference between TDB and TT is between 1 + and 2 milliseconds, and so a TT value can usually be supplied in + place of a TDB value. The TT timescale is related to TAI via + TT = TAI $+$ 32.184 seconds. + + \sstitem + \texttt{"} ECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the + ecliptic and mean equinox specified by the qualifying \htmlref{Equinox}{Equinox} + value. + + \sstitem + \texttt{"} FK4\texttt{"} : The old FK4 (barycentric) equatorial coordinate system, + which should be qualified by an Equinox value. The underlying + model on which this is based is non-inertial and rotates slowly + with time, so for accurate work FK4 coordinate systems should + also be qualified by an Epoch value. + + \sstitem + \texttt{"} FK4-NO-E\texttt{"} or \texttt{"} FK4\_NO\_E\texttt{"} : The old FK4 (barycentric) equatorial + system but without the \texttt{"} E-terms of aberration\texttt{"} (e.g. some radio + catalogues). This coordinate system should also be qualified by + both an Equinox and an Epoch value. + + \sstitem + \texttt{"} FK5\texttt{"} or \texttt{"} EQUATORIAL\texttt{"} : The modern FK5 (barycentric) equatorial + coordinate system. This should be qualified by an Equinox value. + + \sstitem + \texttt{"} GALACTIC\texttt{"} : Galactic coordinates (IAU 1958). + + \sstitem + \texttt{"} GAPPT\texttt{"} , \texttt{"} GEOCENTRIC\texttt{"} or \texttt{"} APPARENT\texttt{"} : The geocentric apparent + equatorial coordinate system, which gives the apparent positions + of sources relative to the true plane of the Earth\texttt{'} s equator and + the equinox (the coordinate origin) at a time specified by the + qualifying Epoch value. (Note that no Equinox is needed to + qualify this coordinate system because no model \texttt{"} mean equinox\texttt{"} + is involved.) These coordinates give the apparent right + ascension and declination of a source for a specified date of + observation, and therefore form an approximate basis for + pointing a telescope. Note, however, that they are applicable to + a fictitious observer at the Earth\texttt{'} s centre, and therefore + ignore such effects as atmospheric refraction and the (normally + much smaller) aberration of light due to the rotational velocity + of the Earth\texttt{'} s surface. Geocentric apparent coordinates are + derived from the standard FK5 (J2000.0) barycentric coordinates + by taking account of the gravitational deflection of light by + the Sun (usually small), the aberration of light caused by the + motion of the Earth\texttt{'} s centre with respect to the barycentre + (larger), and the precession and nutation of the Earth\texttt{'} s spin + axis (normally larger still). + + \sstitem + \texttt{"} HELIOECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the + ecliptic and mean equinox of J2000.0, in which an offset is added to + the longitude value which results in the centre of the sun being at + zero longitude at the date given by the Epoch attribute. Attempts to + set a value for the Equinox attribute will be ignored, since this + system is always referred to J2000.0. + + \sstitem + \texttt{"} ICRS\texttt{"} : The Internation Celestial Reference System, realised + through the Hipparcos catalogue. Whilst not an equatorial system + by definition, the ICRS is very close to the FK5 (J2000) system + and is usually treated as an equatorial system. The distinction + between ICRS and FK5 (J2000) only becomes important when accuracies + of 50 milli-arcseconds or better are required. ICRS need not be + qualified by an Equinox value. + + \sstitem + \texttt{"} J2000\texttt{"} : An equatorial coordinate system based on the mean + dynamical equator and equinox of the J2000 epoch. The dynamical + equator and equinox differ slightly from those used by the FK5 + model, and so a \texttt{"} J2000\texttt{"} SkyFrame will differ slightly from an + \texttt{"} FK5(Equinox=J2000)\texttt{"} SkyFrame. The J2000 System need not be + qualified by an Equinox value + + \sstitem + \texttt{"} SUPERGALACTIC\texttt{"} : De Vaucouleurs Supergalactic coordinates. + + \sstitem + \texttt{"} UNKNOWN\texttt{"} : Any other general spherical coordinate system. No + \htmlref{Mapping}{Mapping} can be created between a pair of SkyFrames if either of the + SkyFrames has System set to \texttt{"} Unknown\texttt{"} . + + } + Currently, the default System value is \texttt{"} ICRS\texttt{"} . However, this + default may change in future as new astrometric standards + evolve. The intention is to track the most modern appropriate + standard. For this reason, you should use the default only if + this is what you intend (and can tolerate any associated slight + change in future). If you intend to use the ICRS system + indefinitely, then you should specify it explicitly. + } + \sstsubsection{ + SpecFrame + }{ + The SpecFrame class supports the following System values and + associated spectral coordinate systems (the default is \texttt{"} WAVE\texttt{"} - + wavelength). They are all defined in FITS-WCS paper III: + + \sstitemlist{ + + \sstitem + \texttt{"} FREQ\texttt{"} : Frequency (GHz) + + \sstitem + \texttt{"} ENER\texttt{"} or \texttt{"} ENERGY\texttt{"} : Energy (J) + + \sstitem + \texttt{"} WAVN\texttt{"} or \texttt{"} WAVENUM\texttt{"} : Wave-number (1/m) + + \sstitem + \texttt{"} WAVE\texttt{"} or \texttt{"} WAVELEN\texttt{"} : Vacuum wave-length (Angstrom) + + \sstitem + \texttt{"} AWAV\texttt{"} or \texttt{"} AIRWAVE\texttt{"} : Wave-length in air (Angstrom) + + \sstitem + \texttt{"} VRAD\texttt{"} or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s) + + \sstitem + \texttt{"} VOPT\texttt{"} or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s) + + \sstitem + \texttt{"} ZOPT\texttt{"} or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless) + + \sstitem + \texttt{"} BETA\texttt{"} : Beta factor (dimensionless) + + \sstitem + \texttt{"} VELO\texttt{"} or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s) + + } + The default value for the Unit attribute for each system is shown + in parentheses. Note that the default value for the ActiveUnit flag + is non-zero + for a SpecFrame, meaning that changes to the Unit attribute for + a SpecFrame will result in the SpecFrame being re-mapped within + its enclosing FrameSet in order to reflect the change in units + (see \htmlref{astSetActiveUnit}{astSetActiveUnit} function for further information). + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class supports the following System values and + associated coordinate systems (the default is \texttt{"} MJD\texttt{"} ): + + \sstitemlist{ + + \sstitem + \texttt{"} MJD\texttt{"} : Modified Julian Date (d) + + \sstitem + \texttt{"} JD\texttt{"} : Julian Date (d) + + \sstitem + \texttt{"} JEPOCH\texttt{"} : Julian epoch (yr) + + \sstitem + \texttt{"} BEPOCH\texttt{"} : Besselian (yr) + + } + The default value for the Unit attribute for each system is shown + in parentheses. Strictly, these systems should not allow changes + to be made to the units. For instance, the usual definition of + \texttt{"} MJD\texttt{"} and \texttt{"} JD\texttt{"} include the statement that the values will be in + units of days. However, AST does allow the use of other units + with all the above supported systems (except BEPOCH), on the + understanding that conversion to the \texttt{"} correct\texttt{"} units involves + nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, + 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined + in terms of tropical years of 365.2422 days, rather than the + usual Julian year of 365.25 days. Therefore, to avoid any + confusion, the Unit attribute is automatically cleared to \texttt{"} yr\texttt{"} when + a System value of BEPOCH System is selected, and an error is + reported if any attempt is subsequently made to change the Unit + attribute. + + Note that the default value for the ActiveUnit flag + is non-zero + for a TimeFrame, meaning that changes to the Unit attribute for + a TimeFrame will result in the TimeFrame being re-mapped within + its enclosing FrameSet in order to reflect the change in units + (see astSetActiveUnit function for further information). + } + \sstsubsection{ + \htmlref{FluxFrame}{FluxFrame} + }{ + The FluxFrame class supports the following System values and + associated systems for measuring observed value: + + \sstitemlist{ + + \sstitem + \texttt{"} FLXDN\texttt{"} : Flux per unit frequency (W/m$\wedge$2/Hz) + + \sstitem + \texttt{"} FLXDNW\texttt{"} : Flux per unit wavelength (W/m$\wedge$2/Angstrom) + + \sstitem + \texttt{"} SFCBR\texttt{"} : Surface brightness in frequency units (W/m$\wedge$2/Hz/arcmin$*$$*$2) + + \sstitem + \texttt{"} SFCBRW\texttt{"} : Surface brightness in wavelength units (W/m$\wedge$2/Angstrom/arcmin$*$$*$2) + + } + The above lists specified the default units for each System. If an + explicit value is set for the Unit attribute but no value is set + for System, then the default System value is determined by the Unit + string (if the units are not appropriate for describing any of the + supported Systems then an error will be reported when an attempt is + made to access the System value). If no value has been specified for + either Unit or System, then System=FLXDN and Unit=W/m$\wedge$2/Hz are + used. + } + } +} +\sstroutine{ + TabOK +}{ + Should the FITS-WCS -TAB algorithm be recognised? +}{ + \sstdescription{ + This attribute is an integer value which indicates if the \texttt{"} -TAB\texttt{"} + algorithm, defined in FITS-WCS paper III, should be supported by + the \htmlref{FitsChan}{FitsChan}. The default value is zero. A zero or negative value + results in no support for -TAB axes (i.e. axes that have \texttt{"} -TAB\texttt{"} + in their CTYPE keyword value). In this case, the + \htmlref{astWrite}{astWrite} + method will return zero if the write operation would required the + use of the -TAB algorithm, and the + \htmlref{astRead}{astRead} + method will return + a NULL pointer + if any axis in the supplied header uses the -TAB algorithm. + + If TabOK is set to a non-zero positive integer, these methods will + recognise and convert axes described by the -TAB algorithm, as + follows: + + The astWrite + method will generate headers that use the -TAB algorithm (if + possible) if no other known FITS-WCS algorithm can be used to + describe the supplied \htmlref{FrameSet}{FrameSet}. This will result in a table of + coordinate values and index vectors being stored in the FitsChan. + After the write operation, the calling application should check to + see if such a table has been stored in the FitsChan. If so, the + table should be retrived from the FitsChan using the + \htmlref{astGetTables}{astGetTables} + method, and the data (and headers) within it copied into a new + FITS binary table extension. See + astGetTables + for more information. The FitsChan uses a \htmlref{FitsTable}{FitsTable} object to store + the table data and headers. This FitsTable will contain the required + columns and headers as described by FITS-WCS paper III - the + coordinates array will be in a column named \texttt{"} COORDS\texttt{"} , and the index + vector(s) will be in columns named \texttt{"} INDEX$<$i$>$\texttt{"} (where $<$i$>$ is the index + of the corresponding FITS WCS axis). Note, index vectors are only + created if required. The EXTNAME value will be set to the value of the + AST\_\_TABEXTNAME constant (currently \texttt{"} WCS-TAB\texttt{"} ). The EXTVER header + will be set to the positive integer value assigned to the TabOK + attribute. No value will be stored for the EXTLEVEL header, and should + therefore be considered to default to 1. + + The astRead + method will generate a FrameSet from headers that use the -TAB + algorithm so long as the necessary FITS binary tables are made + available. There are two ways to do this: firstly, if the application + knows which FITS binary tables will be needed, then it can create a + Fitstable describing each such table and store it in the FitsChan + (using method + \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) before invoking the astRead method. + Secondly, if the application does not know which FITS binary tables + will be needed by + astRead, + then it can register a call-back function with the FitsChan using + method + \htmlref{astTableSource}{astTableSource}. + This call-back function will be called from within + astRead + if and when a -TAB header is encountered. When called, its arguments + will give the name, version and level of the FITS extension containing + a required table. The call-back function should read this table from + an external FITS file, and create a corresponding FitsTable which + it should then return to + astRead. Note, currently astRead + can only handle -TAB headers that describe 1-dimensional (i.e. + separable) axes. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } +} +\sstroutine{ + TextLab(axis) +}{ + Draw descriptive axis labels for a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether textual labels should be drawn to describe the quantity + being represented on each axis of a \htmlref{Plot}{Plot}. It takes a separate + value for each physical axis of a Plot so that, for instance, + the setting \texttt{"} TextLab(2)=1\texttt{"} specifies that descriptive labels + should be drawn for the second axis. + + If the TextLab value of a Plot axis is non-zero, then + descriptive labels will be drawn for that axis, otherwise they + will be omitted. The default behaviour is to draw descriptive + labels if tick marks and numerical labels are being drawn around + the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute), + but to omit them otherwise. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The text used for the descriptive labels is derived from the + Plot\texttt{'} s \htmlref{Label(axis)}{Label(axis)} attribute, together with its \htmlref{Unit(axis)}{Unit(axis)} + attribute if appropriate (see the \htmlref{LabelUnits(axis)}{LabelUnits(axis)} attribute). + + \sstitem + The drawing of numerical axis labels for a Plot (which + indicate values on the axis) is controlled by the \htmlref{NumLab(axis)}{NumLab(axis)} + attribute. + + \sstitem + If no axis is specified, (e.g. \texttt{"} TextLab\texttt{"} instead of + \texttt{"} TextLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the TextLab(1) value. + } + } +} +\sstroutine{ + TextLabGap(axis) +}{ + Spacing of descriptive axis labels for a Plot +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + where descriptive axis labels are placed relative to the axes they + describe. It takes a separate value for each physical axis of a + \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} TextLabGap(2)=0.01\texttt{"} + specifies where the descriptive label for the second axis should + be drawn. + + For each axis, the TextLabGap value gives the spacing between the + descriptive label and the edge of a box enclosing all other parts + of the annotated grid (excluding other descriptive labels). The gap + is measured to the nearest edge of the label (i.e. the top or the + bottom). Positive values cause the descriptive label to be placed + outside the bounding box, while negative values cause it to be placed + inside. + + The TextLabGap value should be given as a fraction of the minimum + dimension of the plotting area, the default value being $+$0.01. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If drawn, descriptive labels are always placed at the edges of + the plotting area, even although the corresponding numerical + labels may be drawn along axis lines in the interior of the + plotting area (see the \htmlref{Labelling}{Labelling} attribute). + + \sstitem + If no axis is specified, (e.g. \texttt{"} TextLabGap\texttt{"} instead of + \texttt{"} TextLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the TextLabGap(1) value. + } + } +} +\sstroutine{ + TickAll +}{ + Draw tick marks on all edges of a Plot? +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + whether tick marks should be drawn on all edges of a \htmlref{Plot}{Plot}. + + If the TickAll value of a Plot is non-zero (the default), then + tick marks will be drawn on all edges of the Plot. Otherwise, + they will be drawn only on those edges where the numerical and + descriptive axis labels are drawn (see the \htmlref{Edge(axis)}{Edge(axis)} + attribute). + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + In some circumstances, numerical labels and tick marks are + drawn along grid lines inside the plotting area, rather than + around its edges (see the \htmlref{Labelling}{Labelling} attribute). In this case, + the value of the TickAll attribute is ignored. + } + } +} +\sstroutine{ + TimeOrigin +}{ + The zero point for TimeFrame axis values +}{ + \sstdescription{ + This specifies the origin from which all time values are measured. + The default value (zero) results in the \htmlref{TimeFrame}{TimeFrame} describing + absolute time values in the system given by the \htmlref{System}{System} attribute + (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to + describe elapsed time since some origin, the TimeOrigin attribute + should be set to hold the required origin value. The TimeOrigin value + stored inside the TimeFrame structure is modified whenever TimeFrame + attribute values are changed so that it refers to the original moment + in time. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + TimeFrame + }{ + All TimeFrames have this attribute. + } + } + \sstdiytopic{ + Input Formats + }{ + The formats accepted when setting a TimeOrigin value are listed + below. They are all case-insensitive and are generally tolerant + of extra white space and alternative field delimiters: + + \sstitemlist{ + + \sstitem + Besselian \htmlref{Epoch}{Epoch}: Expressed in decimal years, with or without + decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). + + \sstitem + Julian Epoch: Expressed in decimal years, with or without + decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). + + \sstitem + Units: An unqualified decimal value is interpreted as a value in + the system specified by the TimeFrame\texttt{'} s System attribute, in the + units given by the TimeFrame\texttt{'} s Unit attribute. Alternatively, an + appropriate unit string can be appended to the end of the floating + point value (\texttt{"} 123.4 d\texttt{"} for example), in which case the supplied value + is scaled into the units specified by the Unit attribute. + + \sstitem + Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for + example). + + \sstitem + Modified Julian Date: With or without decimal places + (\texttt{"} MJD 54321.4\texttt{"} for example). + + \sstitem + Gregorian Calendar Date: With the month expressed either as an + integer or a 3-character abbreviation, and with optional decimal + places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or + \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is + given, the time refers to the start of the day (zero hours). + + \sstitem + Gregorian Date and Time: Any calendar date (as above) but with + a fraction of a day expressed as hours, minutes and seconds + (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be + separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). + } + } + \sstdiytopic{ + Output Format + }{ + When enquiring TimeOrigin values, the returned formatted floating + point value represents a value in the TimeFrame\texttt{'} s System, in the unit + specified by the TimeFrame\texttt{'} s Unit attribute. + } +} +\sstroutine{ + TimeScale +}{ + Time scale +}{ + \sstdescription{ + This attribute identifies the time scale to which the time axis values + of a \htmlref{TimeFrame}{TimeFrame} refer, and may take any of the values listed in the + \texttt{"} Time Scales\texttt{"} section (below). + + The default TimeScale value depends on the current \htmlref{System}{System} value; if + the current TimeFrame system is \texttt{"} Besselian epoch\texttt{"} the default is + \texttt{"} TT\texttt{"} , otherwise it is \texttt{"} TAI\texttt{"} . Note, if the System attribute is set + so that the TimeFrame represents Besselian \htmlref{Epoch}{Epoch}, then an error + will be reported if an attempt is made to set the TimeScale to + anything other than TT. + + Note, the supported time scales fall into two groups. The first group + containing UT1, GMST, LAST and LMST define time in terms of the + orientation of the earth. The second group (containing all the remaining + time scales) define time in terms of an atomic process. Since the rate of + rotation of the earth varies in an unpredictable way, conversion between + two timescales in different groups relies on a value being supplied for + the \htmlref{Dut1}{Dut1} attribute (defined by the parent \htmlref{Frame}{Frame} class). This attribute + specifies the difference between the UT1 and UTC time scales, in seconds, + and defaults to zero. See the documentation for the Dut1 attribute for + further details. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + TimeFrame + }{ + All TimeFrames have this attribute. + } + } + \sstdiytopic{ + Time Scales + }{ + The TimeFrame class supports the following TimeScale values (all are + case-insensitive): + + \sstitemlist{ + + \sstitem + \texttt{"} TAI\texttt{"} - International Atomic Time + + \sstitem + \texttt{"} UTC\texttt{"} - Coordinated Universal Time + + \sstitem + \texttt{"} UT1\texttt{"} - Universal Time + + \sstitem + \texttt{"} GMST\texttt{"} - Greenwich Mean Sidereal Time + + \sstitem + \texttt{"} LAST\texttt{"} - Local Apparent Sidereal Time + + \sstitem + \texttt{"} LMST\texttt{"} - Local Mean Sidereal Time + + \sstitem + \texttt{"} TT\texttt{"} - Terrestrial Time + + \sstitem + \texttt{"} TDB\texttt{"} - Barycentric Dynamical Time + + \sstitem + \texttt{"} TCB\texttt{"} - Barycentric Coordinate Time + + \sstitem + \texttt{"} TCG\texttt{"} - Geocentric Coordinate Time + + \sstitem + \texttt{"} LT\texttt{"} - Local Time (the offset from UTC is given by attribute \htmlref{LTOffset}{LTOffset}) + + } + An very informative description of these and other time scales is + available at http://www.ucolick.org/$\sim$sla/leapsecs/timescales.html. + } + \sstdiytopic{ + UTC \htmlref{Warnings}{Warnings} + }{ + UTC should ideally be expressed using separate hours, minutes and + seconds fields (or at least in seconds for a given date) if leap seconds + are to be taken into account. Since the TimeFrame class represents + each moment in time using a single floating point number (the axis value) + there will be an ambiguity during a leap second. Thus an error of up to + 1 second can result when using AST to convert a UTC time to another + time scale if the time occurs within a leap second. Leap seconds + occur at most twice a year, and are introduced to take account of + variation in the rotation of the earth. The most recent leap second + occurred on 1st January 1999. Although in the vast majority of cases + leap second ambiguities won\texttt{'} t matter, there are potential problems in + on-line data acquisition systems and in critical applications involving + taking the difference between two times. + } +} +\sstroutine{ + Title +}{ + Frame title +}{ + \sstdescription{ + This attribute holds a string which is used as a title in (e.g.) + graphical output to describe the coordinate system which a \htmlref{Frame}{Frame} + represents. Examples might be \texttt{"} Detector Coordinates\texttt{"} or + \texttt{"} Galactic Coordinates\texttt{"} . + + If a Title value has not been set for a Frame, then a suitable + default is supplied, depending on the class of the Frame. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default supplied by the Frame class is \texttt{"} $<$n$>$-d coordinate + system\texttt{"} , where $<$n$>$ is the number of Frame axes (\htmlref{Naxes}{Naxes} + attribute). + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The CmpFrame class re-defines the default Title value to be + \texttt{"} $<$n$>$-d compound coordinate system\texttt{"} , where $<$n$>$ is the number + of CmpFrame axes (Naxes attribute). + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Title attribute of a FrameSet is the same as that of its + current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A Frame\texttt{'} s Title is intended purely for interpretation by human + readers and not by software. + } + } +} +\sstroutine{ + TitleGap +}{ + Vertical spacing for a Plot title +}{ + \sstdescription{ + This attribute controls the appearance of an annotated + coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining + where the title of a \htmlref{Plot}{Plot} is drawn. + + Its value gives the spacing between the bottom edge of the title + and the top edge of a bounding box containing all the other parts + of the annotated grid. Positive values cause the title to be + drawn outside the box, while negative values cause it to be drawn + inside. + + The TitleGap value should be given as a fraction of the minimum + dimension of the plotting area, the default value being $+$0.05. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + \sstsubsection{ + \htmlref{Plot3D}{Plot3D} + }{ + The Plot3D class ignores this attributes since it does not draw + a \htmlref{Title}{Title}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The text used for the title is obtained from the Plot\texttt{'} s Title + attribute. + } + } +} +\sstroutine{ + Tol +}{ + Plotting tolerance +}{ + \sstdescription{ + This attribute specifies the plotting tolerance (or resolution) + to be used for the graphical output produced by a \htmlref{Plot}{Plot}. Smaller + values will result in smoother and more accurate curves being + drawn, but may slow down the plotting process. Conversely, + larger values may speed up the plotting process in cases where + high resolution is not required. + + The Tol value should be given as a fraction of the minimum + dimension of the plotting area, and should lie in the range + from 1.0e-7 to 1.0. By default, a value of 0.01 is used. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } +} +\sstroutine{ + TolInverse +}{ + Target relative error for the iterative inverse transformation +}{ + \sstdescription{ + This attribute controls the iterative inverse transformation + used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. + + Its value gives the target relative error in teh axis values of + each transformed position. Further iterations will be performed + until the target relative error is reached, or the maximum number + of iterations given by attribute \htmlref{NiterInverse}{NiterInverse} is reached. + + The default value is 1.0E-6. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{PolyMap}{PolyMap} + }{ + All PolyMaps have this attribute. + } + } +} +\sstroutine{ + Top(axis) +}{ + Highest axis value to display +}{ + \sstdescription{ + This attribute gives the highest axis value to be displayed (for + instance, by the \htmlref{astGrid}{astGrid} method). + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Frame}{Frame} + }{ + The default supplied by the Frame class is to display all axis + values, without any limit. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Top value to $+$90 degrees + for latitude axes, and 180 degrees for co-latitude axes. The + default for longitude axes is to display all axis values. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + TranForward +}{ + Forward transformation defined? +}{ + \sstdescription{ + This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform + coordinates in the \texttt{"} forward\texttt{"} direction (i.e. converting input + coordinates into output coordinates). If this attribute is + non-zero, the forward transformation is available. Otherwise, it + is not. + } + \sstattributetype{ + Integer (boolean), read-only. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + The TranForward attribute value for a CmpMap is given by the + boolean AND of the value for each component Mapping. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The TranForward attribute of a FrameSet applies to the + transformation which converts between the FrameSet\texttt{'} s base + \htmlref{Frame}{Frame} and its current Frame (as specified by the \htmlref{Base}{Base} and + \htmlref{Current}{Current} attributes). This value is given by the boolean AND + of the TranForward values which apply to each of the + individual sub-Mappings required to perform this conversion. + The TranForward attribute value for a FrameSet may therefore + change if a new Base or Current Frame is selected. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error will result if a Mapping with a TranForward value of + zero is used to transform coordinates in the forward direction. + } + } +} +\sstroutine{ + TranInverse +}{ + Inverse transformation defined? +}{ + \sstdescription{ + This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform + coordinates in the \texttt{"} inverse\texttt{"} direction (i.e. converting output + coordinates back into input coordinates). If this attribute is + non-zero, the inverse transformation is available. Otherwise, it + is not. + } + \sstattributetype{ + Integer (boolean), readonly. + } + \sstapplicability{ + \sstsubsection{ + Mapping + }{ + All Mappings have this attribute. + } + \sstsubsection{ + \htmlref{CmpMap}{CmpMap} + }{ + The TranInverse attribute value for a CmpMap is given by the + boolean AND of the value for each component Mapping. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The TranInverse attribute of a FrameSet applies to the + transformation which converts between the FrameSet\texttt{'} s current + \htmlref{Frame}{Frame} and its base Frame (as specified by the \htmlref{Current}{Current} and + \htmlref{Base}{Base} attributes). This value is given by the boolean AND of + the TranInverse values which apply to each of the individual + sub-Mappings required to perform this conversion. + The TranInverse attribute value for a FrameSet may therefore + change if a new Base or Current Frame is selected. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + An error will result if a Mapping with a TranInverse value of + zero is used to transform coordinates in the inverse direction. + } + } +} +\sstroutine{ + Unit(axis) +}{ + Physical units for formatted axis values +}{ + \sstdescription{ + This attribute contains a textual representation of the physical + units used to represent formatted coordinate values on a particular + axis of a \htmlref{Frame}{Frame}. + The \htmlref{astSetActiveUnit}{astSetActiveUnit} function controls how the Unit values + are used. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Frame + }{ + The default supplied by the Frame class is an empty string. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + The SkyFrame class re-defines the default Unit value (e.g. to + \texttt{"} hh:mm:ss.sss\texttt{"} ) to describe the character string returned by + the \htmlref{astFormat}{astFormat} function when formatting coordinate values. + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + The SpecFrame class re-defines the default Unit value so that it + is appropriate for the current \htmlref{System}{System} value. See the System + attribute for details. An error will be reported if an attempt + is made to use an inappropriate Unit. + } + \sstsubsection{ + \htmlref{TimeFrame}{TimeFrame} + }{ + The TimeFrame class re-defines the default Unit value so that it + is appropriate for the current System value. See the System + attribute for details. An error will be reported if an attempt + is made to use an inappropriate Unit (e.g. \texttt{"} km\texttt{"} ). + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The Unit attribute of a FrameSet axis is the same as that of + its current Frame (as specified by the \htmlref{Current}{Current} attribute). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This attribute described the units used when an axis value is + formatted into a string using + astFormat. + In some cases these units may be different to those used to represent + floating point axis values within application code (for instance a + SkyFrame always uses radians to represent floating point axis values). + The InternalUnit attribute described the units used for floating + point values. + + \sstitem + When specifying this attribute by name, it should be + subscripted with the number of the Frame axis to which it + applies. + } + } +} +\sstroutine{ + UnitRadius +}{ + SphMap input vectors lie on a unit sphere? +}{ + \sstdescription{ + This is a boolean attribute which indicates whether the + 3-dimensional vectors which are supplied as input to a \htmlref{SphMap}{SphMap} + are known to always have unit length, so that they lie on a unit + sphere centred on the origin. + + If this condition is true (indicated by setting UnitRadius + non-zero), it implies that a \htmlref{CmpMap}{CmpMap} which is composed of a + SphMap applied in the forward direction followed by a similar + SphMap applied in the inverse direction may be simplified + (e.g. by \htmlref{astSimplify}{astSimplify}) to become a \htmlref{UnitMap}{UnitMap}. This is because the + input and output vectors will both have unit length and will + therefore have the same coordinate values. + + If UnitRadius is zero (the default), then although the output + vector produced by the CmpMap (above) will still have unit + length, the input vector may not have. This will, in general, + change the coordinate values, so it prevents the pair of SphMaps + being simplified. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + SphMap + }{ + All SphMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This attribute is intended mainly for use when SphMaps are + involved in a sequence of Mappings which project (e.g.) a + dataset on to the celestial sphere. By regarding the celestial + sphere as a unit sphere (and setting UnitRadius to be non-zero) + it becomes possible to cancel the SphMaps present, along with + associated sky projections, when two datasets are aligned using + celestial coordinates. This often considerably improves + performance. + + \sstitem + Such a situations often arises when interpreting FITS data and + is handled automatically by the \htmlref{FitsChan}{FitsChan} class. + + \sstitem + The value of the UnitRadius attribute is used only to control + the simplification of Mappings and has no effect on the value of + the coordinates transformed by a SphMap. The lengths of the + input 3-dimensional Cartesian vectors supplied are always + ignored, even if UnitRadius is non-zero. + + \sstitem + The value of this attribute may changed only if the SphMap + has no more than one reference. That is, an error is reported if the + SphMap has been cloned, either by including it within another object + such as a CmpMap or \htmlref{FrameSet}{FrameSet} or by calling the + \htmlref{astClone}{astClone} + function. + } + } +} +\sstroutine{ + UseDefs +}{ + Use default values for unspecified attributes? +}{ + \sstdescription{ + This attribute specifies whether default values should be used + internally for object attributes which have not been assigned a + value explicitly. If a non-zero value (the default) is supplied for + UseDefs, then default values will be used for attributes which have + not explicitly been assigned a value. If zero is supplied for UseDefs, + then an error will be reported if an attribute for which no explicit + value has been supplied is needed internally within AST. + + Many attributes (including the UseDefs attribute itself) are unaffected + by the setting of the UseDefs attribute, and default values will always + be used without error for such attributes. The \texttt{"} Applicability:\texttt{"} section + below lists the attributes which are affected by the setting of UseDefs. + + Note, UseDefs only affects access to attributes internally within + AST. The public accessor functions such as + astGetC + is unaffected by the UseDefs attribute - default values will always + be returned if no value has been set. Application code should use the + \htmlref{astTest}{astTest} + function if required to determine if a value has been set for an + attribute. + } + \sstattributetype{ + Integer (boolean). + } + \sstapplicability{ + \sstsubsection{ + \htmlref{Object}{Object} + }{ + All Objects have this attribute, but ignore its setting except + as described below for individual classes. + } + \sstsubsection{ + \htmlref{FrameSet}{FrameSet} + }{ + The default value of UseDefs for a FrameSet is redefined to be + the UseDefs value of its current \htmlref{Frame}{Frame}. + } + \sstsubsection{ + \htmlref{CmpFrame}{CmpFrame} + }{ + The default value of UseDefs for a CmpFrame is redefined to be + the UseDefs value of its first component Frame. + } + \sstsubsection{ + \htmlref{Region}{Region} + }{ + The default value of UseDefs for a Region is redefined to be + the UseDefs value of its encapsulated Frame. + } + \sstsubsection{ + Frame + }{ + If UseDefs is zero, an error is reported when aligning Frames if the + \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat} or \htmlref{ObsLon}{ObsLon} attribute is required but has not been + assigned a value explicitly. + } + \sstsubsection{ + \htmlref{SkyFrame}{SkyFrame} + }{ + If UseDefs is zero, an error is reported when aligning SkyFrames + if any of the following attributes are required but have not been + assigned a value explicitly: Epoch, \htmlref{Equinox}{Equinox}. + } + \sstsubsection{ + \htmlref{SpecFrame}{SpecFrame} + }{ + If UseDefs is zero, an error is reported when aligning SpecFrames + if any of the following attributes are required but have not been + assigned a value explicitly: Epoch, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec}, \htmlref{RestFreq}{RestFreq}, + \htmlref{SourceVel}{SourceVel}, \htmlref{StdOfRest}{StdOfRest}. + } + \sstsubsection{ + \htmlref{DSBSpecFrame}{DSBSpecFrame} + }{ + If UseDefs is zero, an error is reported when aligning DSBSpecFrames + or when accessing the \htmlref{ImagFreq}{ImagFreq} attribute if any of the following + attributes are required but have not been assigned a value explicitly: + Epoch, \htmlref{DSBCentre}{DSBCentre}, \htmlref{IF}{IF}. + } + } +} +\sstroutine{ + Variant +}{ + Indicates which variant of the current Frame is to be used +}{ + \sstdescription{ + This attribute can be used to change the \htmlref{Mapping}{Mapping} that connects the + current \htmlref{Frame}{Frame} to the other Frames in the \htmlref{FrameSet}{FrameSet}. By default, each + Frame in a FrameSet is connected to the other Frames by a single + Mapping that can only be changed by using the + \htmlref{astRemapFrame}{astRemapFrame} + method. However, it is also possible to associate multiple Mappings + with a Frame, each Mapping having an identifying name. If this is + done, the \texttt{"} Variant\texttt{"} attribute can be set to indicate the name of + the Mapping that is to be used with the current Frame. + + A possible (if unlikely) use-case is to create a FrameSet that can + be used to describe the WCS of an image formed by co-adding images + of two different parts of the sky. In such an image, each pixel contains + flux from two points on the sky.and so the WCS for the image should + ideally contain one pixel Frame and two SkyFrames - one describing + each of the two co-added images. There is nothing to prevent a + FrameSet containing two explicit SkyFrames, but the problem then arises + of how to distinguish between them. The two primary characteristics of + a Frame that distinguishes it from other Frames are its class and its + \htmlref{Domain}{Domain} attribute value. The class of a Frame cannot be changed, but we + could in principle use two different Domain values to distinguish the + two SkyFrames. However, in practice it is not uncommon for application + software to assume that SkyFrames will have the default Domain value + of \texttt{"} SKY\texttt{"} . That is, instead of searching for Frames that have a class + of \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , such software searches for Frames that have a Domain + of \texttt{"} SKY\texttt{"} . To alleviate this problem, it is possible to add a single + SkyFrame to the FrameSet, but specifying two alternate Mappings to + use with the SkyFrame. Setting the \texttt{"} Variant\texttt{"} attribute to the name + of one or the other of these alternate Mappings will cause the + SkyFrame to be remapped within the FrameSet so that it uses the + specified Mapping. The same facility can be used with any class of + Frame, not just SkyFrames. + + To use this facility, the Frame should first be added to the + FrameSet in the usual manner using the + \htmlref{astAddFrame}{astAddFrame} method. By default, the Mapping supplied to astAddFrame + is assigned a name equal to the Domain name of the Frame. To assign a + different name to it, the + \htmlref{astAddVariant}{astAddVariant} + method should then be called specifying the required name and a NULL + Mapping. The + astAddVariant + method should then be called repeatedly to add each required extra + Mapping to the current Frame, supplying a unique name for each one. + + Each Frame in a FrameSet can have its own set of variant Mappings. + To control the Mappings in use with a specific Frame, you need first + to make it the current Frame in the FrameSet. + + The + \htmlref{astMirrorVariants}{astMirrorVariants} function + allows the effects of variant Mappings associated with a nominated + Frame to be propagated to other Frames in the FrameSet. + + Once this has been done, setting a new value for the \texttt{"} Variant\texttt{"} + attribute of a FrameSet will cause the current Frame in the + FrameSet to be remapped to use the specified variant Mapping. An + error will be reported if the current Frame has no variant Mapping + with the supplied name. + + Getting the value of the \texttt{"} Variant\texttt{"} attribute will return the name + of the variant Mapping currently in use with the current Frame. If + the Frame has no variant Mappings, the value will default to the + Domain name of the current Frame. + + Clearing the \texttt{"} Variant\texttt{"} attribute will have the effect of removing + all variant Mappings (except for the currently selected Mapping) from + the current Frame. + + Testing the \texttt{"} Variant\texttt{"} attribute will return + a non-zero value + if the current Frame contains any variant Mappings, and + zero + otherwise. + + A complete list of the names associated with all the available + variant Mappings in the current Frame can be obtained from the + \htmlref{AllVariants}{AllVariants} attribute. + + If a Frame with variant Mappings is remapped using the + astRemapFrame + method, the currently selected variant Mapping is used by + astRemapFrame + and the other variant Mappings are removed from the Frame. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + FrameSet + }{ + All FrameSets have this attribute. + } + } +} +\sstroutine{ + Warnings +}{ + Controls the issuing of warnings about various conditions +}{ + \sstdescription{ + This attribute controls the issuing of warnings about selected + conditions when an \htmlref{Object}{Object} or keyword is read from or written to a + \htmlref{FitsChan}{FitsChan}. The value supplied for the Warnings attribute should + consist of a space separated list of condition names (see the + \htmlref{AllWarnings}{AllWarnings} attribute for a list of the currently defined names). + Each name indicates a condition which should be reported. The default + value for Warnings is the string \texttt{"} BadKeyName BadKeyValue Tnx Zpx + BadCel BadMat BadPV BadCTYPE\texttt{"} . + + The text of any warning will be stored within the FitsChan in the + form of one or more new header cards with keyword ASTWARN. If + required, applications can check the FitsChan for ASTWARN cards + (using \htmlref{astFindFits}{astFindFits}) after the call to \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} has been + performed, and report the text of any such cards to the user. ASTWARN + cards will be propagated to any output header unless they are + deleted from the FitsChan using \htmlref{astDelFits}{astDelFits}. + } + \sstattributetype{ + String + } + \sstapplicability{ + \sstsubsection{ + FitsChan + }{ + All FitsChans have this attribute. + } + } + \sstnotes{ + This attribute only controls the warnings that are to be stored as + a set of header cards in the FitsChan as described above. It has no + effect on the storage of warnings in the parent \htmlref{Channel}{Channel} structure. + All warnings are stored in the parent Channel structure, from where + they can be retrieved using the + \htmlref{astWarnings}{astWarnings} + function. + } +} +\sstroutine{ + WcsAxis(lonlat) +}{ + FITS-WCS projection axes +}{ + \sstdescription{ + This attribute gives the indices of the longitude and latitude + coordinates of the FITS-WCS projection within the coordinate + space used by a \htmlref{WcsMap}{WcsMap}. These indices are defined when the + WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot + subsequently be altered. + + If \texttt{"} lonlat\texttt{"} is 1, the index of the longitude axis is + returned. Otherwise, if it is 2, the index of the latitude axis + is returned. + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } +} +\sstroutine{ + WcsType +}{ + FITS-WCS projection type +}{ + \sstdescription{ + This attribute specifies which type of FITS-WCS projection will + be performed by a \htmlref{WcsMap}{WcsMap}. The value is specified when a WcsMap + is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be + changed. + + The values used are represented by macros with names of + the form \texttt{"} AST\_\_XXX\texttt{"} , where \texttt{"} XXX\texttt{"} is the (upper case) 3-character + code used by the FITS-WCS \texttt{"} CTYPEi\texttt{"} keyword to identify the + projection. For example, possible values are AST\_\_TAN (for the + tangent plane or gnomonic projection) and AST\_\_AIT (for the + Hammer-Aitoff projection). AST\_\_TPN is an exception in that it + is not part of the FITS-WCS standard (it represents a TAN + projection with polynomial correction terms as defined in an early + draft of the FITS-WCS paper). + } + \sstattributetype{ + Integer, read-only. + } + \sstapplicability{ + \sstsubsection{ + WcsMap + }{ + All WcsMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of available projections, see the FITS-WCS paper. + } + } +} +\sstroutine{ + Width(element) +}{ + Line width for a Plot element +}{ + \sstdescription{ + This attribute determines the line width used when drawing each + element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a + separate value for each graphical element so that, for instance, + the setting \texttt{"} Width(border)=2.0\texttt{"} causes the Plot border to be + drawn using a line width of 2.0. A value of 1.0 results in a + line thickness which is approximately 0.0005 times the length of + the diagonal of the entire display surface. + + The actual appearance of lines drawn with any particular width, + and the range of available widths, is determined by the + underlying graphics system. The default behaviour is for all + graphical elements to be drawn using the default line width + supplied by this graphics system. This will not necessarily + correspond to a Width value of 1.0. + } + \sstattributetype{ + Floating point. + } + \sstapplicability{ + \sstsubsection{ + Plot + }{ + All Plots have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + For a list of the graphical elements available, see the + description of the Plot class. + + \sstitem + If no graphical element is specified, (e.g. \texttt{"} Width\texttt{"} instead of + \texttt{"} Width(border)\texttt{"} ), then a \texttt{"} set\texttt{"} or \texttt{"} clear\texttt{"} operation will affect + the attribute value of all graphical elements, while a \texttt{"} get\texttt{"} or + \texttt{"} test\texttt{"} operation will use just the Width(\htmlref{Border}{Border}) value. + } + } +} +\sstroutine{ + XmlFormat +}{ + System for formatting Objects as XML +}{ + \sstdescription{ + This attribute specifies the formatting system to use when AST + Objects are written out as XML through an \htmlref{XmlChan}{XmlChan}. It + affects the behaviour of the \htmlref{astWrite}{astWrite} function when + they are used to transfer any AST \htmlref{Object}{Object} to or from an external + XML representation. + + The XmlChan class allows AST objects to be represented in the form + of XML in several ways (conventions) and the XmlFormat attribute is + used to specify which of these should be used. The formatting options + available are outlined in the \texttt{"} Formats Available\texttt{"} section below. + + By default, an XmlChan will attempt to determine which format system + is already in use, and will set the default XmlFormat value + accordingly (so that subsequent I/O operations adopt the same + conventions). It does this by looking for certain critical items + which only occur in particular formats. For details of how this + works, see the \texttt{"} Choice of Default Format\texttt{"} section below. If you wish + to ensure that a particular format system is used, independently of + any XML already read, you should set an explicit XmlFormat value + yourself. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + XmlChan + }{ + All XmlChans have this attribute. + } + } + \sstdiytopic{ + Formats Available + }{ + The XmlFormat attribute can take any of the following (case + insensitive) string values to select the corresponding formatting + system: + + \sstitemlist{ + + \sstitem + \texttt{"} NATIVE\texttt{"} : This is a direct conversion to XML of the heirarchical + format used by a standard XML channel (and also by the NATIVE + encoding of a \htmlref{FitsChan}{FitsChan}). + + \sstitem + \texttt{"} QUOTED\texttt{"} : This is the same as NATIVE format except that extra + information is included which allows client code to convert the + XML into a form which can be read by a standard AST \htmlref{Channel}{Channel}. This + extra information indicates which AST attribute values should be + enclosed in quotes before being passed to a Channel. + + \sstitem + \texttt{"} IVOA\texttt{"} : This is a format that uses an early draft of the STC-X schema + developed by the International Virtual Observatory Alliance (IVOA - + see \texttt{"} http://www.ivoa.net/\texttt{"} ) to describe coordinate systems, regions, + mappings, etc. Support is limited to V1.20 described at + \texttt{"} http://www.ivoa.net/Documents/WD/STC/STC-20050225.html\texttt{"} . Since the + version of STC-X finally adopted by the IVOA differs in several + significant respects from V1.20, this format is now mainly of + historical interest. Note, the alternative \texttt{"} STC-S\texttt{"} format (a + simpler non-XML encoding of the STC metadata) is supported by the + \htmlref{StcsChan}{StcsChan} class. + } + } + \sstdiytopic{ + Choice of Default Format; + }{ + If the XmlFormat attribute of an XmlChan is not set, the default + value it takes is determined by the presence of certain critical + items within the document most recently read using + \htmlref{astRead}{astRead}. + The sequence of decision used to arrive at the default value is as + follows: + + \sstitemlist{ + + \sstitem + If the previous document read contained any elements in any of the STC + namespaces (\texttt{"} urn:nvo-stc\texttt{"} , \texttt{"} urn:nvo-coords\texttt{"} or \texttt{"} urn:nvo-region\texttt{"} ), then + the default value is IVOA. + + \sstitem + If the previous document read contained any elements in the AST + namespace which had an associated XML attribute called \texttt{"} quoted\texttt{"} , then + the default value is QUOTED. + + \sstitem + Otherwise, if none of these conditions is met (as would be the + case if no document had yet been read), then NATIVE format is + used. + + } + Setting an explicit value for the XmlFormat attribute always + over-rides this default behaviour. + } + \sstdiytopic{ + The IVOA Format + }{ + The IVOA support caters only for certain parts of V1.20 of the + draft Space-Time Coordinate (STC) schema (see + http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this + draft has now been superceded by an officially adopted version that + differs in several significant respects from V1.20. Consequently, + the \texttt{"} IVOA\texttt{"} XmlChan format is of historical interest only. + + The following points should be noted when using an XmlChan to read + or write STC information (note, this list is currently incomplete): + + \sstitemlist{ + + \sstitem + Objects can currently only be read using this format, not written. + + \sstitem + The AST object generated by reading an $<$STCMetadata$>$ element will + be an instance of one of the AST \texttt{"} \htmlref{Stc}{Stc}\texttt{"} classes: \htmlref{StcResourceProfile}{StcResourceProfile}, + \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcObsDataLocation}{StcObsDataLocation}. + + \sstitem + When reading an $<$STCMetadata$>$ element, the axes in the returned + AST Object will be in the order space, time, spectral, redshift, + irrespective of the order in which the axes occur in the $<$STCMetadata$>$ + element. If the supplied $<$STCMetadata$>$ element does not contain all of + these axes, the returned AST Object will also omit them, but the + ordering of those axes which are present will be as stated above. If + the spatial frame represents a celestial coordinate system the + spatial axes will be in the order (longitude, latitude). + + \sstitem + Until such time as the AST \htmlref{TimeFrame}{TimeFrame} is complete, a simple + 1-dimensional \htmlref{Frame}{Frame} (with \htmlref{Domain}{Domain} set to TIME) will be used to + represent the STC $<$TimeFrame$>$ element. Consequently, most of the + information within a $<$TimeFrame$>$ element is currently ignored. + + \sstitem + $<$SpaceFrame$>$ elements can only be read if they describe a celestial + longitude and latitude axes supported by the AST \htmlref{SkyFrame}{SkyFrame} class. The + space axes will be returned in the order (longitude, latitude). + + \sstitem + Velocities associated with SpaceFrames cannot be read. + + \sstitem + Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element + are currently ignored. + + \sstitem + Any second or subsequent $<$AstroCoordSystem$>$ found within an + STCMetaData element is ignored. + + \sstitem + Any second or subsequent $<$AstroCoordArea$>$ found within an + STCMetaData element is ignored. + + \sstitem + Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored. + + \sstitem + Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored. + + \sstitem + $<$SpaceFrame$>$ elements can only be read if they refer to + one of the following space reference frames: ICRS, GALACTIC\_II, + SUPER\_GALACTIC, HEE, FK4, FK5, ECLIPTIC. + + \sstitem + $<$SpaceFrame$>$ elements can only be read if the reference + position is TOPOCENTER. Also, any planetary ephemeris is ignored. + + \sstitem + Regions: there is currently no support for STC regions of type + Sector, ConvexHull or SkyIndex. + + \sstitem + The AST \htmlref{Region}{Region} read from a CoordInterval element is considered to + be open if either the lo\_include or the hi\_include attribute is + set to false. + + \sstitem + $<$RegionFile$>$ elements are not supported. + + \sstitem + Vertices within $<$\htmlref{Polygon}{Polygon}$>$ elements are always considered to be + joined using great circles (that is, $<$SmallCircle$>$ elements are + ignored). + } + } +} +\sstroutine{ + XmlLength +}{ + Controls output buffer length +}{ + \sstdescription{ + This attribute specifies the maximum length to use when writing out + text through the sink function supplied when the \htmlref{XmlChan}{XmlChan} was created. + + The number of characters in each string written out through the sink + function will not be greater than the value of this attribute (but + may be less). A value of zero (the default) means there is no limit - + each string can be of any length. + } + \sstattributetype{ + Integer. + } + \sstapplicability{ + \sstsubsection{ + XmlChan + }{ + All XmlChans have this attribute. + } + } +} +\sstroutine{ + XmlPrefix +}{ + The namespace prefix to use when writing +}{ + \sstdescription{ + This attribute is a string which is to be used as the namespace + prefix for all XML elements created as a result of writing an AST + \htmlref{Object}{Object} out through an \htmlref{XmlChan}{XmlChan}. The URI associated with the namespace + prefix is given by the symbolic constant AST\_\_XMLNS defined in + ast.h. + A definition of the namespace prefix is included in each top-level + element produced by the XmlChan. + + The default value is a blank string which causes no prefix to be + used. In this case each top-level element will set the default + namespace to be the value of AST\_\_XMLNS. + } + \sstattributetype{ + String. + } + \sstapplicability{ + \sstsubsection{ + Object + }{ + All Objects have this attribute. + } + } +} +\sstroutine{ + Zoom +}{ + ZoomMap scale factor +}{ + \sstdescription{ + This attribute holds the \htmlref{ZoomMap}{ZoomMap} scale factor, by which + coordinate values are multiplied (by the forward transformation) + or divided (by the inverse transformation). The default value + is unity. + + Note that if a ZoomMap is inverted (e.g. by using \htmlref{astInvert}{astInvert}), + then the reciprocal of this zoom factor will, in effect, be + used. + + In general, \htmlref{Mapping}{Mapping} attributes cannot be changed after the Mapping + has been created (the exception to this is the \htmlref{Invert}{Invert} attribute, + which can be changed at any time). However, several of the oldest + Mapping classes - including the ZoomMap class - were introduced + into the AST library before this restriction was enforced. To + reduce the chances of breaking existing software, the attributes of + such Mappings may still be changed, but only for Mapping instances + that have exactly one active reference. In other words, an error will + be reported if an attempt is made to set or clear an attribute of a + Mapping (other than the Invert attribute) if that Mapping has been + cloned. Mappings are cloned when they are incorporated into another + object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet}, or when the + \htmlref{astClone}{astClone} + function is used. + } + \sstattributetype{ + Double precision. + } + \sstapplicability{ + \sstsubsection{ + ZoomMap + }{ + All ZoomMaps have this attribute. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + The Zoom attribute may not be set to zero. + } + } +} +\normalsize + +\cleardoublepage +\section{\label{ss:classdescriptions}AST Class Descriptions} +\small +\sstroutine{ + Axis +}{ + Store axis information +}{ + \sstdescription{ + The Axis class is used to store information associated with a + particular axis of a \htmlref{Frame}{Frame}. It is used internally by the AST + library and has no constructor function. You should encounter it + only within textual output (e.g. from \htmlref{astWrite}{astWrite}). + } + \sstconstructor{ + None. + } + \sstdiytopic{ + Inheritance + }{ + The Axis class inherits from the \htmlref{Object}{Object} class. + } +} +\sstroutine{ + Box +}{ + A box region with sides parallel to the axes of a Frame +}{ + \sstdescription{ + The Box class implements a \htmlref{Region}{Region} which represents a box with sides + parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given + range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the + only real difference being that the Interval class allows some axis + limits to be unspecified. Note, a Box will only look like a box if + the Frame geometry is approximately flat. For instance, a Box centred + close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box + (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a + pole). + } + \sstconstructor{ + \htmlref{astBox}{astBox} + } + \sstdiytopic{ + Inheritance + }{ + The Box class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The Box class does not define any new attributes beyond + those which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + The Box class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + Channel +}{ + Basic (textual) I/O channel +}{ + \sstdescription{ + The Channel class implements low-level input/output for the AST + library. Writing an \htmlref{Object}{Object} to a Channel will generate a textual + representation of that Object, and reading from a Channel will + create a new Object from its textual representation. + + Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting text. By default, however, + a Channel will read from standard input and write to standard + output. Alternatively, a Channel can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + } + \sstconstructor{ + \htmlref{astChannel}{astChannel} + } + \sstdiytopic{ + Inheritance + }{ + The Channel class inherits from the Object class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Objects, every + Channel also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Comment}{Comment}: Include textual comments in output? + + \sstitem + \htmlref{Full}{Full}: Set level of output detail + + \sstitem + \htmlref{Indent}{Indent}: Indentation increment between objects + + \sstitem + \htmlref{ReportLevel}{ReportLevel}: Selects the level of error reporting + + \sstitem + \htmlref{SinkFile}{SinkFile}: The path to a file to which the Channel should write + + \sstitem + \htmlref{Skip}{Skip}: Skip irrelevant data? + + \sstitem + \htmlref{SourceFile}{SourceFile}: The path to a file from which the Channel should read + + \sstitem + \htmlref{Strict}{Strict}: Generate errors instead of warnings? + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Objects, the + following functions may also be applied to all Channels: + + \sstitemlist{ + + \sstitem + \htmlref{astWarnings}{astWarnings}: Return warnings from the previous read or write + + \sstitem + \htmlref{astPutChannelData}{astPutChannelData}: Store data to pass to source or sink functions + + \sstitem + \htmlref{astRead}{astRead}: Read an Object from a Channel + + \sstitem + \htmlref{astWrite}{astWrite}: Write an Object to a Channel + } + } +} +\sstroutine{ + Circle +}{ + A circular or spherical region within a Frame +}{ + \sstdescription{ + The Circle class implements a \htmlref{Region}{Region} which represents a circle or + sphere within a \htmlref{Frame}{Frame}. + } + \sstconstructor{ + \htmlref{astCircle}{astCircle} + } + \sstdiytopic{ + Inheritance + }{ + The Circle class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The Circle class does not define any new attributes beyond + those which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Regions, the + following functions may also be applied to all Circles: + + \sstitemlist{ + + \sstitem + \htmlref{astCirclePars}{astCirclePars}: Get the geometric parameters of the Circle + } + } +} +\sstroutine{ + CmpFrame +}{ + Compound Frame +}{ + \sstdescription{ + A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames + (of any class) to be merged together to form a more complex + Frame. The axes of the two component Frames then appear together + in the resulting CmpFrame (those of the first Frame, followed by + those of the second Frame). + + Since a CmpFrame is itself a Frame, it can be used as a + component in forming further CmpFrames. Frames of arbitrary + complexity may be built from simple individual Frames in this + way. + + Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a + Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap}, + but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region} + (a sub-class of Frame), then the CmpFrame will use the Region as a + Mapping when transforming values for axes described by the Region. + Thus input axis values corresponding to positions which are outside the + Region will result in bad output axis values. + } + \sstconstructor{ + \htmlref{astCmpFrame}{astCmpFrame} + } + \sstdiytopic{ + Inheritance + }{ + The CmpFrame class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + The CmpFrame class does not define any new attributes beyond + those which are applicable to all Frames. However, the attributes + of the component Frames can be accessed as if they were attributes + of the CmpFrame. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} + and a \htmlref{SkyFrame}{SkyFrame}, then the CmpFrame will recognise the \texttt{"} \htmlref{Equinox}{Equinox}\texttt{"} + attribute and forward access requests to the component SkyFrame. + Likewise, it will recognise the \texttt{"} \htmlref{RestFreq}{RestFreq}\texttt{"} attribute and forward + access requests to the component SpecFrame. An axis index can + optionally be appended to the end of any attribute name, in which + case the request to access the attribute will be forwarded to the + primary Frame defining the specified axis. + } + \sstdiytopic{ + Functions + }{ + The CmpFrame class does not define any new functions beyond those + which are applicable to all Frames. + } +} +\sstroutine{ + CmpMap +}{ + Compound Mapping +}{ + \sstdescription{ + A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component + Mappings (of any class) to be connected together to form a more + complex Mapping. This connection may either be \texttt{"} in series\texttt{"} + (where the first Mapping is used to transform the coordinates of + each point and the second mapping is then applied to the + result), or \texttt{"} in parallel\texttt{"} (where one Mapping transforms the + earlier coordinates for each point and the second Mapping + simultaneously transforms the later coordinates). + + Since a CmpMap is itself a Mapping, it can be used as a + component in forming further CmpMaps. Mappings of arbitrary + complexity may be built from simple individual Mappings in this + way. + } + \sstconstructor{ + \htmlref{astCmpMap}{astCmpMap} + } + \sstdiytopic{ + Inheritance + }{ + The CmpMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The CmpMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The CmpMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + CmpRegion +}{ + A combination of two regions within a single Frame +}{ + \sstdescription{ + A CmpRegion is a \htmlref{Region}{Region} which allows two component + Regions (of any class) to be combined to form a more complex + Region. This combination may be performed a boolean AND, OR + or XOR (exclusive OR) operator. If the AND operator is + used, then a position is inside the CmpRegion only if it is + inside both of its two component Regions. If the OR operator is + used, then a position is inside the CmpRegion if it is inside + either (or both) of its two component Regions. If the XOR operator + is used, then a position is inside the CmpRegion if it is inside + one but not both of its two component Regions. Other operators can + be formed by negating one or both component Regions before using + them to construct a new CmpRegion. + + The two component Region need not refer to the same coordinate + \htmlref{Frame}{Frame}, but it must be possible for the + \htmlref{astConvert}{astConvert} + function to determine a \htmlref{Mapping}{Mapping} between them (an error will be + reported otherwise when the CmpRegion is created). For instance, + a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame} + with a Region defined within a Galactic SkyFrame. This is + acceptable because the SkyFrame class knows how to convert between + these two systems, and consequently the + astConvert + function will also be able to convert between them. In such cases, + the second component Region will be mapped into the coordinate Frame + of the first component Region, and the Frame represented by the + CmpRegion as a whole will be the Frame of the first component Region. + + Since a CmpRegion is itself a Region, it can be used as a + component in forming further CmpRegions. Regions of arbitrary + complexity may be built from simple individual Regions in this + way. + } + \sstconstructor{ + \htmlref{astCmpRegion}{astCmpRegion} + } + \sstdiytopic{ + Inheritance + }{ + The CmpRegion class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The CmpRegion class does not define any new attributes beyond those + which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + The CmpRegion class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + DSBSpecFrame +}{ + Dual sideband spectral coordinate system description +}{ + \sstdescription{ + A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents + positions in a spectrum obtained using a dual sideband instrument. + Such an instrument produces a spectrum in which each point contains + contributions from two distinctly different frequencies, one from + the \texttt{"} lower side band\texttt{"} (LSB) and one from the \texttt{"} upper side band\texttt{"} (USB). + Corresponding LSB and USB frequencies are connected by the fact + that they are an equal distance on either side of a fixed central + frequency known as the \texttt{"} Local Oscillator\texttt{"} (LO) frequency. + + When quoting a position within such a spectrum, it is necessary to + indicate whether the quoted position is the USB position or the + corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this + indication. Another option that the SideBand attribute provides is + to represent a spectral position by its topocentric offset from the + LO frequency. + + In practice, the LO frequency is specified by giving the distance + from the LO frequency to some \texttt{"} central\texttt{"} spectral position. Typically + this central position is that of some interesting spectral feature. + The distance from this central position to the LO frequency is known + as the \texttt{"} intermediate frequency\texttt{"} (\htmlref{IF}{IF}). The value supplied for IF can + be a signed value in order to indicate whether the LO frequency is + above or below the central position. + } + \sstconstructor{ + \htmlref{astDSBSpecFrame}{astDSBSpecFrame} + } + \sstdiytopic{ + Inheritance + }{ + The DSBSpecFrame class inherits from the SpecFrame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all SpecFrames, every + DSBSpecFrame also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AlignSideBand}{AlignSideBand}: Should alignment occur between sidebands? + + \sstitem + \htmlref{DSBCentre}{DSBCentre}: The central position of interest. + + \sstitem + \htmlref{IF}{IF}: The intermediate frequency used to define the LO frequency. + + \sstitem + \htmlref{ImagFreq}{ImagFreq}: The image sideband equivalent of the rest frequency. + + \sstitem + \htmlref{SideBand}{SideBand}: Indicates which sideband the DSBSpecFrame represents. + } + } + \sstdiytopic{ + Functions + }{ + The DSBSpecFrame class does not define any new functions beyond those + which are applicable to all SpecFrames. + } +} +\sstroutine{ + DssMap +}{ + Map points using a Digitised Sky Survey plate solution +}{ + \sstdescription{ + The DssMap class implements a \htmlref{Mapping}{Mapping} which transforms between + 2-dimensional pixel coordinates and an equatorial sky coordinate + system (right ascension and declination) using a Digitised Sky + Survey (DSS) astrometric plate solution. + + The input coordinates are pixel numbers along the first and + second dimensions of an image, where the centre of the first + pixel is located at (1,1) and the spacing between pixel centres + is unity. + + The output coordinates are right ascension and declination in + radians. The celestial coordinate system used (FK4, FK5, etc.) + is unspecified, and will usually be indicated by appropriate + keywords in a FITS header. + } + \sstconstructor{ + The DssMap class does not have a constructor function. A DssMap + is created only as a by-product of reading a \htmlref{FrameSet}{FrameSet} (using + \htmlref{astRead}{astRead}) from a \htmlref{FitsChan}{FitsChan} which contains FITS header cards + describing a DSS plate solution, and whose \htmlref{Encoding}{Encoding} attribute is + set to \texttt{"} DSS\texttt{"} . The result of such a read, if successful, is a + FrameSet whose base and current Frames are related by a DssMap. + } + \sstdiytopic{ + Inheritance + }{ + The DssMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The DssMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The DssMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Ellipse +}{ + An elliptical region within a 2-dimensional Frame +}{ + \sstdescription{ + The Ellipse class implements a \htmlref{Region}{Region} which represents a ellipse + within a 2-dimensional \htmlref{Frame}{Frame}. + } + \sstconstructor{ + \htmlref{astEllipse}{astEllipse} + } + \sstdiytopic{ + Inheritance + }{ + The Ellipse class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The Ellipse class does not define any new attributes beyond + those which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Regions, the + following functions may also be applied to all Ellipses: + + \sstitemlist{ + + \sstitem + \htmlref{astEllipsePars}{astEllipsePars}: Get the geometric parameters of the Ellipse + } + } +} +\sstroutine{ + FitsChan +}{ + I/O Channel using FITS header cards to represent Objects +}{ + \sstdescription{ + A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O + operations involving the use of FITS (Flexible Image Transport + \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a + description of that Object composed of FITS header cards, and + reading from a FitsChan will create a new Object from its FITS + header card description. + + While a FitsChan is active, it represents a buffer which may + contain zero or more 80-character \texttt{"} header cards\texttt{"} conforming to + FITS conventions. Any sequence of FITS-conforming header cards + may be stored, apart from the \texttt{"} END\texttt{"} card whose existence is + merely implied. The cards may be accessed in any order by using + the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"} + card, to which subsequent operations apply. Searches + based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new + cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and + existing ones may be deleted (\htmlref{astDelFits}{astDelFits}), extracted (\htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}), + or changed (astSetFits$<$X$>$). + + When you create a FitsChan, you have the option of specifying + \texttt{"} source\texttt{"} and \texttt{"} sink\texttt{"} functions which connect it to external data + stores by reading and writing FITS header cards. If you provide + a source function, it is used to fill the FitsChan with header cards + when it is accessed for the first time. If you do not provide a + source function, the FitsChan remains empty until you explicitly enter + data into it (e.g. using astPutFits, astPutCards, astWrite + or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from + which headers should be read). When the FitsChan is deleted, any + remaining header cards in the FitsChan can be saved in either of + two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the + name of a text file to which header cards should be written), or 2) + by providing a sink function (used to to deliver header cards to an + external data store). If you do not provide a sink function or a + value for SinkFile, any header cards remaining when the FitsChan + is deleted will be lost, so you should arrange to extract them + first if necessary + (e.g. using astFindFits or \htmlref{astRead}{astRead}). + + Coordinate system information may be described using FITS header + cards using several different conventions, termed + \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a + FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute + determines how the Object is converted to (or from) a + description involving FITS header cards. In general, different + encodings will result in different sets of header cards to + describe the same Object. Examples of encodings include the DSS + encoding (based on conventions used by the STScI Digitised Sky + Survey data), the FITS-WCS encoding (based on a proposed FITS + standard) and the NATIVE encoding (a near loss-less way of + storing AST Objects in FITS headers). + + The available encodings differ in the range of Objects they can + represent, in the number of Object descriptions that can coexist + in the same FitsChan, and in their accessibility to other + (external) astronomy applications (see the Encoding attribute + for details). Encodings are not necessarily mutually exclusive + and it may sometimes be possible to describe the same Object in + several ways within a particular set of FITS header cards by + using several different encodings. + + The detailed behaviour of astRead and astWrite, when used with + a FitsChan, depends on the encoding in use. In general, however, + all successful use of astRead is destructive, so that FITS header cards + are consumed in the process of reading an Object, and are + removed from the FitsChan (this deletion can be prevented for + specific cards by calling the + \htmlref{astRetainFits}{astRetainFits} function). + An unsuccessful call of + astRead + (for instance, caused by the FitsChan not containing the necessary + FITS headers cards needed to create an Object) results in the + contents of the FitsChan being left unchanged. + + If the encoding in use allows only a single Object description + to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF + encodings), then write operations using astWrite will + over-write any existing Object description using that + encoding. Otherwise (e.g. the NATIVE encoding), multiple Object + descriptions are written sequentially and may later be read + back in the same sequence. + } + \sstconstructor{ + \htmlref{astFitsChan}{astFitsChan} + } + \sstdiytopic{ + Inheritance + }{ + The FitsChan class inherits from the Channel class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Channels, every + + FitsChan also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AllWarnings}{AllWarnings}: A list of the available conditions + + \sstitem + \htmlref{Card}{Card}: Index of current FITS card in a FitsChan + + \sstitem + \htmlref{CardComm}{CardComm}: The comment of the current FITS card in a FitsChan + + \sstitem + \htmlref{CardName}{CardName}: The keyword name of the current FITS card in a FitsChan + + \sstitem + \htmlref{CardType}{CardType}: The data type of the current FITS card in a FitsChan + + \sstitem + \htmlref{CarLin}{CarLin}: Ignore spherical rotations on CAR projections? + + \sstitem + \htmlref{CDMatrix}{CDMatrix}: Use a CD matrix instead of a PC matrix? + + \sstitem + \htmlref{Clean}{Clean}: Remove cards used whilst reading even if an error occurs? + + \sstitem + \htmlref{DefB1950}{DefB1950}: Use FK4 B1950 as default equatorial coordinates? + + \sstitem + \htmlref{Encoding}{Encoding}: System for encoding Objects as FITS headers + + \sstitem + \htmlref{FitsAxisOrder}{FitsAxisOrder}: Sets the order of WCS axes within new FITS-WCS headers + + \sstitem + \htmlref{FitsDigits}{FitsDigits}: Digits of precision for floating-point FITS values + + \sstitem + \htmlref{Iwc}{Iwc}: Add a \htmlref{Frame}{Frame} describing Intermediate World Coords? + + \sstitem + \htmlref{Ncard}{Ncard}: Number of FITS header cards in a FitsChan + + \sstitem + \htmlref{Nkey}{Nkey}: Number of unique keywords in a FitsChan + + \sstitem + \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"} algorithm be recognised? + + \sstitem + \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection? + + \sstitem + \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Channels, the + following functions may also be applied to all FitsChans: + + \sstitemlist{ + + \sstitem + \htmlref{astDelFits}{astDelFits}: Delete the current FITS card in a FitsChan + + \sstitem + \htmlref{astEmptyFits}{astEmptyFits}: Delete all cards in a FitsChan + + \sstitem + \htmlref{astFindFits}{astFindFits}: Find a FITS card in a FitsChan by keyword + + \sstitem + \htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}: Get a keyword value from a FitsChan + + \sstitem + \htmlref{astGetTables}{astGetTables}: Retrieve any FitsTables from a FitsChan + + \sstitem + \htmlref{astPurgeWCS}{astPurgeWCS}: Delete all WCS-related cards in a FitsChan + + \sstitem + \htmlref{astPutCards}{astPutCards}: Stores a set of FITS header card in a FitsChan + + \sstitem + \htmlref{astPutFits}{astPutFits}: Store a FITS header card in a FitsChan + + \sstitem + \htmlref{astPutTable}{astPutTable}: Store a single \htmlref{FitsTable}{FitsTable} in a FitsChan + + \sstitem + \htmlref{astPutTables}{astPutTables}: Store multiple FitsTables in a FitsChan + + \sstitem + \htmlref{astReadFits}{astReadFits}: Read cards in through the source function + + \sstitem + \htmlref{astRemoveTables}{astRemoveTables}: Remove one or more FitsTables from a FitsChan + + \sstitem + \htmlref{astRetainFits}{astRetainFits}: Ensure current card is retained in a FitsChan + + \sstitem + \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}: Store a new keyword value in a FitsChan + + \sstitem + \htmlref{astShowFits}{astShowFits}: Display the contents of a FitsChan on standard output + + \sstitem + \htmlref{astTableSource}{astTableSource}: Register a source function for FITS table access + + \sstitem + \htmlref{astTestFits}{astTestFits}: Test if a keyword has a defined value in a FitsChan + + \sstitem + \htmlref{astWriteFits}{astWriteFits}: Write all cards out to the sink function + + \sstitem + AST\_SHOWFITS: Display the contents of a FitsChan on standard output + } + } +} +\sstroutine{ + FitsTable +}{ + A representation of a FITS binary table +}{ + \sstdescription{ + The FitsTable class is a representation of a FITS binary table. It + inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the + binary data of the main table, and a \htmlref{FitsChan}{FitsChan} (encapsulated within + the FitsTable) is used to hold the FITS header. + + Note - it is not recommended to use the FitsTable class to store + very large tables. + + FitsTables are primarily geared towards the needs of the \texttt{"} -TAB\texttt{"} + algorithm defined in FITS-WCS paper 2, and so do not support all + features of FITS binary tables. In particularly, they do not + provide any equivalent to the following features of FITS binary + tables: \texttt{"} heap\texttt{"} data (i.e. binary data following the main table), + columns holding complex values, columns holding variable length + arrays, scaled columns, column formats, columns holding bit values, + 8-byte integer values or logical values. + } + \sstconstructor{ + \htmlref{astFitsTable}{astFitsTable} + } + \sstdiytopic{ + Inheritance + }{ + The FitsTable class inherits from the Table class. + } + \sstdiytopic{ + Attributes + }{ + The FitsTable class does not define any new attributes beyond + those which are applicable to all Tables. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Tables, the + following functions may also be applied to all FitsTables: + + \sstitemlist{ + + \sstitem + \htmlref{astColumnNull}{astColumnNull}: Get/set the null value for a column of a FitsTable + + \sstitem + \htmlref{astColumnSize}{astColumnSize}: Get number of bytes needed to hold a full column of data + + \sstitem + \htmlref{astGetColumnData}{astGetColumnData}: Retrieve all the data values stored in a column + + \sstitem + \htmlref{astGetTableHeader}{astGetTableHeader}: Get the FITS headers from a FitsTable + + \sstitem + \htmlref{astPutColumnData}{astPutColumnData}: Store data values in a column + + \sstitem + \htmlref{astPutTableHeader}{astPutTableHeader}: Store FITS headers within a FitsTable + } + } +} +\sstroutine{ + FluxFrame +}{ + Measured flux description +}{ + \sstdescription{ + A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various systems used to represent the signal level in an + observation. The particular coordinate system to be used is specified + by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by + other attributes such as the units, etc (see the description of the + System attribute for details). + + All flux values are assumed to be measured at the same frequency or + wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is + more appropriate for use with images rather than spectra. + } + \sstconstructor{ + \htmlref{astFluxFrame}{astFluxFrame} + } + \sstdiytopic{ + Inheritance + }{ + The FluxFrame class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + FluxFrame also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{SpecVal}{SpecVal}: The spectral position at which the flux values are measured. + } + } + \sstdiytopic{ + Functions + }{ + The FluxFrame class does not define any new functions beyond those + which are applicable to all Frames. + } +} +\sstroutine{ + Frame +}{ + Coordinate system description +}{ + \sstdescription{ + This class is used to represent coordinate systems. It does this + in rather the same way that a frame around a graph describes the + coordinate space in which data are plotted. Consequently, a + Frame has a \htmlref{Title}{Title} (string) attribute, which describes the + coordinate space, and contains axes which in turn hold + information such as Label and Units strings which are used for + labelling (e.g.) graphical output. In general, however, the + number of axes is not restricted to two. + + Functions are available for converting Frame coordinate values + into a form suitable for display, and also for calculating + distances and offsets between positions within the Frame. + + Frames may also contain knowledge of how to transform to and + from related coordinate systems. + } + \sstconstructor{ + \htmlref{astFrame}{astFrame} + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When used as a \htmlref{Mapping}{Mapping}, a Frame implements a unit (null) + transformation in both the forward and inverse directions + (equivalent to a \htmlref{UnitMap}{UnitMap}). The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attribute values are + both equal to the number of Frame axes. + } + } + \sstdiytopic{ + Inheritance + }{ + The Frame class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + Frame also has the following attributes (if the Frame has only one + axis, the axis specifier can be omited from the following attribute + names): + + \sstitemlist{ + + \sstitem + \htmlref{AlignSystem}{AlignSystem}: Coordinate system used to align Frames + + \sstitem + \htmlref{Bottom(axis)}{Bottom(axis)}: Lowest axis value to display + + \sstitem + \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}: Number of digits of precision + + \sstitem + \htmlref{Direction(axis)}{Direction(axis)}: Display axis in conventional direction? + + \sstitem + \htmlref{Domain}{Domain}: Coordinate system domain + + \sstitem + \htmlref{Dut1}{Dut1}: Difference between the UT1 and UTC timescale + + \sstitem + \htmlref{Epoch}{Epoch}: Epoch of observation + + \sstitem + \htmlref{Format(axis)}{Format(axis)}: Format specification for axis values + + \sstitem + \htmlref{InternalUnit(axis)}{InternalUnit(axis)}: Physical units for unformated axis values + + \sstitem + \htmlref{Label(axis)}{Label(axis)}: \htmlref{Axis}{Axis} label + + \sstitem + \htmlref{MatchEnd}{MatchEnd}: Match trailing axes? + + \sstitem + \htmlref{MaxAxes}{MaxAxes}: Maximum number of Frame axes to match + + \sstitem + \htmlref{MinAxes}{MinAxes}: Minimum number of Frame axes to match + + \sstitem + \htmlref{Naxes}{Naxes}: Number of Frame axes + + \sstitem + \htmlref{NormUnit(axis)}{NormUnit(axis)}: Normalised physical units for formatted axis values + + \sstitem + \htmlref{ObsAlt}{ObsAlt}: Geodetic altitude of observer + + \sstitem + \htmlref{ObsLat}{ObsLat}: Geodetic latitude of observer + + \sstitem + \htmlref{ObsLon}{ObsLon}: Geodetic longitude of observer + + \sstitem + \htmlref{Permute}{Permute}: Permute axis order? + + \sstitem + \htmlref{PreserveAxes}{PreserveAxes}: Preserve axes? + + \sstitem + \htmlref{Symbol(axis)}{Symbol(axis)}: Axis symbol + + \sstitem + \htmlref{System}{System}: Coordinate system used to describe the domain + + \sstitem + \htmlref{Title}{Title}: Frame title + + \sstitem + \htmlref{Top(axis)}{Top(axis)}: Highest axis value to display + + \sstitem + \htmlref{Unit(axis)}{Unit(axis)}: Physical units for formatted axis values + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Mappings, the + following functions may also be applied to all Frames: + + \sstitemlist{ + + \sstitem + \htmlref{astAngle}{astAngle}: Calculate the angle subtended by two points at a third point + + \sstitem + \htmlref{astAxAngle}{astAxAngle}: Find the angle from an axis, to a line through two points + + \sstitem + \htmlref{astAxDistance}{astAxDistance}: Calculate the distance between two axis values + + \sstitem + \htmlref{astAxNorm}{astAxNorm}: Normalises an array of axis values + + \sstitem + \htmlref{astAxOffset}{astAxOffset}: Calculate an offset along an axis + + \sstitem + \htmlref{astConvert}{astConvert}: Determine how to convert between two coordinate systems + + \sstitem + \htmlref{astDistance}{astDistance}: Calculate the distance between two points in a Frame + + \sstitem + \htmlref{astFindFrame}{astFindFrame}: Find a coordinate system with specified characteristics + + \sstitem + \htmlref{astFormat}{astFormat}: Format a coordinate value for a Frame axis + + \sstitem + \htmlref{astGetActiveUnit}{astGetActiveUnit}: Determines how the Unit attribute will be used + + \sstitem + \htmlref{astIntersect}{astIntersect}: Find the intersection between two geodesic curves + + \sstitem + \htmlref{astMatchAxes}{astMatchAxes}: Find any corresponding axes in two Frames + + \sstitem + \htmlref{astNorm}{astNorm}: Normalise a set of Frame coordinates + + \sstitem + \htmlref{astOffset}{astOffset}: Calculate an offset along a geodesic curve + + \sstitem + \htmlref{astOffset2}{astOffset2}: Calculate an offset along a geodesic curve in a 2D Frame + + \sstitem + \htmlref{astPermAxes}{astPermAxes}: Permute the order of a Frame\texttt{'} s axes + + \sstitem + \htmlref{astPickAxes}{astPickAxes}: Create a new Frame by picking axes from an existing one + + \sstitem + \htmlref{astResolve}{astResolve}: Resolve a vector into two orthogonal components + + \sstitem + \htmlref{astSetActiveUnit}{astSetActiveUnit}: Specify how the Unit attribute should be used + + \sstitem + \htmlref{astUnformat}{astUnformat}: Read a formatted coordinate value for a Frame axis + } + } +} +\sstroutine{ + FrameSet +}{ + Set of inter-related coordinate systems +}{ + \sstdescription{ + A FrameSet consists of a set of one or more Frames (which + describe coordinate systems), connected together by Mappings + (which describe how the coordinate systems are inter-related). A + FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair + of these Frames (i.e. to convert between any of the coordinate + systems which it describes). The individual Frames are + identified within the FrameSet by an integer index, with Frames + being numbered consecutively from one as they are added to the + FrameSet. + + Every FrameSet has a \texttt{"} base\texttt{"} \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"} Frame (which + are allowed to be the same). Any of the Frames may be nominated + to hold these positions, and the choice is determined by the + values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold + the indices of the relevant Frames. By default, the first Frame + added to a FrameSet is its base Frame, and the last one added is + its current Frame. + + The base Frame describes the \texttt{"} native\texttt{"} coordinate system of + whatever the FrameSet is used to calibrate (e.g. the pixel + coordinates of an image) and the current Frame describes the + \texttt{"} apparent\texttt{"} coordinate system in which it should be viewed + (e.g. displayed, etc.). Any further Frames represent a library + of alternative coordinate systems, which may be selected by + making them current. + + When a FrameSet is used in a context that requires a Frame, + (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current + Frame is used. A FrameSet may therefore be used in place of its + current Frame in most situations. + + When a FrameSet is used in a context that requires a Mapping, + the Mapping used is the one between its base Frame and its + current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"} + coordinates into \texttt{"} apparent\texttt{"} ones, and vice versa. Like any + Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which + has the effect of interchanging its base and current Frames and + hence of reversing the Mapping between them. + + Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of + Frame), either explicitly or as components within CmpFrames. In this + case the Mapping between a pair of Frames within a FrameSet will + include the effects of the clipping produced by any Regions included + in the path between the Frames. + } + \sstconstructor{ + \htmlref{astFrameSet}{astFrameSet} + } + \sstdiytopic{ + Inheritance + }{ + The FrameSet class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + FrameSet also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AllVariants}{AllVariants}: List of all variant mappings store with current Frame + + \sstitem + \htmlref{Base}{Base}: FrameSet base Frame index + + \sstitem + \htmlref{Current}{Current}: FrameSet current Frame index + + \sstitem + \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet + + \sstitem + \htmlref{Variant}{Variant}: Name of variant mapping in use by current Frame + + } + Every FrameSet also inherits any further attributes that belong + to its current Frame, regardless of that Frame\texttt{'} s class. (For + example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{SkyFrame} class, is + inherited by any FrameSet which has a SkyFrame as its current + Frame.) The set of attributes belonging to a FrameSet may therefore + change when a new current Frame is selected. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Frames, the + following functions may also be applied to all FrameSets: + + \sstitemlist{ + + \sstitem + \htmlref{astAddFrame}{astAddFrame}: Add a Frame to a FrameSet to define a new coordinate + system + + \sstitem + \htmlref{astAddVariant}{astAddVariant}: Add a variant Mapping to the current Frame + + \sstitem + \htmlref{astGetFrame}{astGetFrame}: Obtain a pointer to a specified Frame in a FrameSet + + \sstitem + \htmlref{astGetMapping}{astGetMapping}: Obtain a Mapping between two Frames in a FrameSet + + \sstitem + \htmlref{astMirrorVariants}{astMirrorVariants}: Make the current Frame mirror variant Mappings in another Frame + + \sstitem + \htmlref{astRemapFrame}{astRemapFrame}: Modify a Frame\texttt{'} s relationship to the other Frames in a + FrameSet + + \sstitem + \htmlref{astRemoveFrame}{astRemoveFrame}: Remove a Frame from a FrameSet + } + } +} +\sstroutine{ + GrismMap +}{ + Transform 1-dimensional coordinates using a grism dispersion equation +}{ + \sstdescription{ + A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms + 1-dimensional coordinates using the spectral dispersion equation + described in FITS-WCS paper III \texttt{"} Representation of spectral + coordinates in FITS\texttt{"} . This describes the dispersion produced by + gratings, prisms and grisms. + + When initially created, the forward transformation of a GrismMap + transforms input \texttt{"} grism parameter\texttt{"} values into output wavelength + values. The \texttt{"} grism parameter\texttt{"} is a dimensionless value which is + linearly related to position on the detector. It is defined in FITS-WCS + paper III as \texttt{"} the offset on the detector from the point of intersection + of the camera axis, measured in units of the effective local length\texttt{"} . + The units in which wavelength values are expected or returned is + determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and + \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will + also be used for the wavelength values. + } + \sstconstructor{ + \htmlref{astGrismMap}{astGrismMap} + } + \sstdiytopic{ + Inheritance + }{ + The GrismMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + GrismMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{GrismNR}{GrismNR}: The refractive index at the reference wavelength + + \sstitem + \htmlref{GrismNRP}{GrismNRP}: Rate of change of refractive index with wavelength + + \sstitem + \htmlref{GrismWaveR}{GrismWaveR}: The reference wavelength + + \sstitem + \htmlref{GrismAlpha}{GrismAlpha}: The angle of incidence of the incoming light + + \sstitem + \htmlref{GrismG}{GrismG}: The grating ruling density + + \sstitem + \htmlref{GrismM}{GrismM}: The interference order + + \sstitem + \htmlref{GrismEps}{GrismEps}: The angle between the normal and the dispersion plane + + \sstitem + \htmlref{GrismTheta}{GrismTheta}: Angle between normal to detector plane and reference ray + } + } + \sstdiytopic{ + Functions + }{ + The GrismMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Interval +}{ + A region representing an interval on one or more axes of a Frame +}{ + \sstdescription{ + The Interval class implements a \htmlref{Region}{Region} which represents upper + and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to + be within the region represented by the Interval, the point must + satisfy all the restrictions placed on all the axes. The point is + outside the region if it fails to satisfy any one of the restrictions. + Each axis may have either an upper limit, a lower limit, both or + neither. If both limits are supplied but are in reverse order (so + that the lower limit is greater than the upper limit), then the + interval is an excluded interval, rather than an included interval. + + Note, The Interval class makes no allowances for cyclic nature of + some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box} + should usually be used in these cases since this requires the user + to think about suitable upper and lower limits, + } + \sstconstructor{ + \htmlref{astInterval}{astInterval} + } + \sstdiytopic{ + Inheritance + }{ + The Interval class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The Interval class does not define any new attributes beyond + those which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + The Interval class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + IntraMap +}{ + Map points using a private transformation function +}{ + \sstdescription{ + The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which + encapsulates a privately-defined coordinate transformation + other AST Mapping. This allows you to create Mappings that + perform any conceivable coordinate transformation. + + However, an IntraMap is intended for use within a single program + or a private suite of software, where all programs have access + to the same coordinate transformation functions (i.e. can be + linked against them). IntraMaps should not normally be stored in + datasets which may be exported for processing by other software, + since that software will not have the necessary transformation + functions available, resulting in an error. + + You must register any coordinate transformation functions to be + used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap. + } + \sstconstructor{ + \htmlref{astIntraMap}{astIntraMap} (also see astIntraReg) + } + \sstdiytopic{ + Inheritance + }{ + The IntraMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + IntraMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{IntraFlag}{IntraFlag}: IntraMap identification string + } + } + \sstdiytopic{ + Functions + }{ + The IntraMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + KeyMap +}{ + Store a set of key/value pairs +}{ + \sstdescription{ + The KeyMap class is used to store a set of values with associated keys + which identify the values. The keys are strings. These may be case + sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and + trailing spaces are ignored. The value associated with a key can be + integer (signed 4 and 2 byte, or unsigned 1 byte), floating point + (single or double precision), + void pointer, + character string or AST \htmlref{Object}{Object} pointer. Each + value can be a scalar or a one-dimensional vector. A KeyMap is + conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an + input into an output - the input is the key, and the output is the + value associated with the key. However, this is only a conceptual + similarity, and it should be noted that the KeyMap class inherits from + the Object class rather than the Mapping class. The methods of the + Mapping class cannot be used with a KeyMap. + } + \sstconstructor{ + \htmlref{astKeyMap}{astKeyMap} + } + \sstdiytopic{ + Inheritance + }{ + The KeyMap class inherits from the Object class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Objects, every + KeyMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{KeyCase}{KeyCase}: Sets the case in which keys are stored + + \sstitem + \htmlref{KeyError}{KeyError}: \htmlref{Report}{Report} an error if the requested key does not exist? + + \sstitem + \htmlref{SizeGuess}{SizeGuess}: The expected size of the KeyMap. + + \sstitem + \htmlref{SortBy}{SortBy}: Determines how keys are sorted in a KeyMap. + + \sstitem + \htmlref{MapLocked}{MapLocked}: Prevent new entries being added to the KeyMap? + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Objects, the + following functions may also be applied to all KeyMaps: + + \sstitemlist{ + + \sstitem + \htmlref{astMapDefined}{astMapDefined}: Does a KeyMap contain a defined value for a key? + + \sstitem + \htmlref{astMapGet0$<$X$>$}{astMapGet0$<$X$>$}: Get a named scalar entry from a KeyMap + + \sstitem + \htmlref{astMapGet1$<$X$>$}{astMapGet1$<$X$>$}: Get a named vector entry from a KeyMap + + \sstitem + \htmlref{astMapGetElem$<$X$>$}{astMapGetElem$<$X$>$}: Get an element of a named vector entry from a KeyMap + + \sstitem + \htmlref{astMapHasKey}{astMapHasKey}: Does the KeyMap contain a named entry? + + \sstitem + \htmlref{astMapKey}{astMapKey}: Return the key name at a given index in the KeyMap + + \sstitem + \htmlref{astMapLenC}{astMapLenC}: Get the length of a named character entry in a KeyMap + + \sstitem + \htmlref{astMapLength}{astMapLength}: Get the length of a named entry in a KeyMap + + \sstitem + \htmlref{astMapCopy}{astMapCopy}: Copy entries from one KeyMap into another + + \sstitem + \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$}: Add a new scalar entry to a KeyMap + + \sstitem + \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$}: Add a new vector entry to a KeyMap + + \sstitem + \htmlref{astMapPutElem$<$X$>$}{astMapPutElem$<$X$>$}: Puts a value into a vector entry in a KeyMap + + \sstitem + \htmlref{astMapPutU}{astMapPutU}: Add a new entry to a KeyMap with an undefined value + + \sstitem + \htmlref{astMapRemove}{astMapRemove}: Removed a named entry from a KeyMap + + \sstitem + \htmlref{astMapRename}{astMapRename}: Rename an existing entry in a KeyMap + + \sstitem + \htmlref{astMapSize}{astMapSize}: Get the number of entries in a KeyMap + + \sstitem + \htmlref{astMapType}{astMapType}: Return the data type of a named entry in a map + } + } +} +\sstroutine{ + LutMap +}{ + Transform 1-dimensional coordinates using a lookup table +}{ + \sstdescription{ + A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms + 1-dimensional coordinates by using linear interpolation in a + lookup table. + + Each input coordinate value is first scaled to give the index of + an entry in the table by subtracting a starting value (the input + coordinate corresponding to the first table entry) and dividing + by an increment (the difference in input coordinate value + between adjacent table entries). + + The resulting index will usually contain a fractional part, so + the output coordinate value is then generated by interpolating + linearly between the appropriate entries in the table. If the + index lies outside the range of the table, linear extrapolation + is used based on the two nearest entries (i.e. the two entries + at the start or end of the table, as appropriate). If either of the + entries used for the interplation has a value of AST\_\_BAD, then the + interpolated value is returned as AST\_\_BAD. + + If the lookup table entries increase or decrease monotonically + (ignoring any flat sections), then the inverse transformation may + also be performed. + } + \sstconstructor{ + \htmlref{astLutMap}{astLutMap} + } + \sstdiytopic{ + Inheritance + }{ + The LutMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + LutMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{LutEpsilon}{LutEpsilon}: The relative error of the values in the table. + + \sstitem + \htmlref{LutInterp}{LutInterp}: The interpolation method to use between table entries. + } + } + \sstdiytopic{ + Functions + }{ + The LutMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Mapping +}{ + Inter-relate two coordinate systems +}{ + \sstdescription{ + This class provides the basic facilities for transforming a set + of coordinates (representing \texttt{"} input\texttt{"} points) to give a new set + of coordinates (representing \texttt{"} output\texttt{"} points). It is used to + describe the relationship which exists between two different + coordinate systems and to implement operations which make use of + this (such as transforming coordinates and resampling grids of + data). However, the Mapping class does not have a constructor + function of its own, as it is simply a container class for a + family of specialised Mappings which implement particular types + of coordinate transformation. + } + \sstconstructor{ + None. + } + \sstdiytopic{ + Inheritance + }{ + The Mapping class inherits from the \htmlref{Object}{Object} class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Objects, every + Mapping also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Invert}{Invert}: Mapping inversion flag + + \sstitem + \htmlref{IsLinear}{IsLinear}: Is the Mapping linear? + + \sstitem + \htmlref{IsSimple}{IsSimple}: Has the Mapping been simplified? + + \sstitem + \htmlref{Nin}{Nin}: Number of input coordinates for a Mapping + + \sstitem + \htmlref{Nout}{Nout}: Number of output coordinates for a Mapping + + \sstitem + \htmlref{Report}{Report}: Report transformed coordinates? + + \sstitem + \htmlref{TranForward}{TranForward}: Forward transformation defined? + + \sstitem + \htmlref{TranInverse}{TranInverse}: Inverse transformation defined? + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Objects, the + following functions may also be applied to all Mappings: + + \sstitemlist{ + + \sstitem + \htmlref{astDecompose}{astDecompose}: Decompose a Mapping into two component Mappings + + \sstitem + \htmlref{astTranGrid}{astTranGrid}: Transform a grid of positions + + \sstitem + \htmlref{astInvert}{astInvert}: Invert a Mapping + + \sstitem + \htmlref{astLinearApprox}{astLinearApprox}: Calculate a linear approximation to a Mapping + + \sstitem + \htmlref{astMapBox}{astMapBox}: Find a bounding box for a Mapping + + \sstitem + \htmlref{astMapSplit}{astMapSplit}: Split a Mapping up into parallel component Mappings + + \sstitem + \htmlref{astQuadApprox}{astQuadApprox}: Calculate a quadratic approximation to a 2D Mapping + + \sstitem + \htmlref{astRate}{astRate}: Calculate the rate of change of a Mapping output + + \sstitem + \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}: Rebin a region of a data grid + + \sstitem + \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$}: Rebin a region of a sequence of data grids + + \sstitem + \htmlref{astResample$<$X$>$}{astResample$<$X$>$}: Resample a region of a data grid + + \sstitem + \htmlref{astRemoveRegions}{astRemoveRegions}: Remove any Regions from a Mapping + + \sstitem + \htmlref{astSimplify}{astSimplify}: Simplify a Mapping + + \sstitem + \htmlref{astTran1}{astTran1}: Transform 1-dimensional coordinates + + \sstitem + \htmlref{astTran2}{astTran2}: Transform 2-dimensional coordinates + + \sstitem + \htmlref{astTranN}{astTranN}: Transform N-dimensional coordinates + + \sstitem + \htmlref{astTranP}{astTranP}: Transform N-dimensional coordinates held in separate arrays + } + } +} +\sstroutine{ + MathMap +}{ + Transform coordinates using mathematical expressions +}{ + \sstdescription{ + A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward + and/or inverse transformation functions using arithmetic operations + and mathematical functions similar to those available in C. The + MathMap interprets these functions at run-time, whenever its forward + or inverse transformation is required. Because the functions are not + compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to + describe coordinate transformations in a transportable manner. A + MathMap therefore provides a flexible way of defining new types of + Mapping whose descriptions may be stored as part of a dataset and + interpreted by other programs. + } + \sstconstructor{ + \htmlref{astMathMap}{astMathMap} + } + \sstdiytopic{ + Inheritance + }{ + The MathMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + MathMap also has the following attributes: + \sstitemlist{ + + \sstitem + \htmlref{Seed}{Seed}: Random number seed + + \sstitem + \htmlref{SimpFI}{SimpFI}: Forward-inverse MathMap pairs simplify? + + \sstitem + \htmlref{SimpIF}{SimpIF}: Inverse-forward MathMap pairs simplify? + } + } + \sstdiytopic{ + Functions + }{ + The MathMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + MatrixMap +}{ + Map coordinates by multiplying by a matrix +}{ + \sstdescription{ + A MatrixMap is form of \htmlref{Mapping}{Mapping} which performs a general linear + transformation. Each set of input coordinates, regarded as a + column-vector, are pre-multiplied by a matrix (whose elements + are specified when the MatrixMap is created) to give a new + column-vector containing the output coordinates. If appropriate, + the inverse transformation may also be performed. + } + \sstconstructor{ + \htmlref{astMatrixMap}{astMatrixMap} + } + \sstdiytopic{ + Inheritance + }{ + The MatrixMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The MatrixMap class does not define any new attributes beyond + those which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The MatrixMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + NormMap +}{ + Normalise coordinates using a supplied Frame +}{ + \sstdescription{ + The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate + values using the + \htmlref{astNorm}{astNorm} function + of a supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap + are both equal to the number of axes in the supplied Frame. + + The forward and inverse transformation of a NormMap are both + defined but are identical (that is, they do not form a real inverse + pair in that the inverse transformation does not undo the + normalisation, instead it reapplies it). However, the + \htmlref{astSimplify}{astSimplify} + function will replace neighbouring pairs of forward and inverse + NormMaps by a single \htmlref{UnitMap}{UnitMap}. + } + \sstconstructor{ + \htmlref{astNormMap}{astNormMap} + } + \sstdiytopic{ + Inheritance + }{ + The NormMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The NormMap class does not define any new attributes beyond + those which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The NormMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + NullRegion +}{ + A boundless region within a Frame +}{ + \sstdescription{ + The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}. + If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion + represents a Region containing no points. If the Negated attribute of + a NullRegion is true, the NullRegion represents an infinite Region + (that is, all points in the coordinate system are inside the NullRegion). + } + \sstconstructor{ + \htmlref{astNullRegion}{astNullRegion} + } + \sstdiytopic{ + Inheritance + }{ + The NullRegion class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The NullRegion class does not define any new attributes beyond + those which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + The NullRegion class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + Object +}{ + Base class for all AST Objects +}{ + \sstdescription{ + This class is the base class from which all other classes in the + AST library are derived. It provides all the basic Object + behaviour and Object manipulation facilities required throughout + the library. There is no Object constructor, however, as Objects + on their own are not useful. + } + \sstconstructor{ + None. + } + \sstdiytopic{ + Inheritance + }{ + The Object base class does not inherit from any other class. + } + \sstdiytopic{ + Attributes + }{ + All Objects have the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Class}{Class}: Object class name + + \sstitem + \htmlref{ID}{ID}: Object identification string + + \sstitem + \htmlref{Ident}{Ident}: Permanent Object identification string + + \sstitem + \htmlref{Nobject}{Nobject}: Number of Objects in class + + \sstitem + \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes + + \sstitem + \htmlref{RefCount}{RefCount}: Count of active Object pointers + + \sstitem + \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes? + } + } + \sstdiytopic{ + Functions + }{ + The following functions may be applied to all Objects: + + \sstitemlist{ + + \sstitem + \htmlref{astAnnul}{astAnnul}: Annul a pointer to an Object + + \sstitem + \htmlref{astBegin}{astBegin}: Begin a new AST context + + \sstitem + \htmlref{astClear}{astClear}: Clear attribute values for an Object + + \sstitem + \htmlref{astClone}{astClone}: Clone a pointer to an Object + + \sstitem + \htmlref{astCopy}{astCopy}: Copy an Object + + \sstitem + \htmlref{astDelete}{astDelete}: Delete an Object + + \sstitem + \htmlref{astEnd}{astEnd}: End an AST context + + \sstitem + \htmlref{astEscapes}{astEscapes}: Control whether graphical escape sequences are removed + + \sstitem + \htmlref{astExempt}{astExempt}: Exempt an Object pointer from AST context handling + + \sstitem + \htmlref{astExport}{astExport}: Export an Object pointer to an outer context + + \sstitem + \htmlref{astGet$<$X$>$}{astGet$<$X$>$}: Get an attribute value for an Object + + \sstitem + \htmlref{astHasAttribute}{astHasAttribute}: Test if an Object has a named attribute + + \sstitem + \htmlref{astImport}{astImport}: Import an Object pointer to the current context + + \sstitem + \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$}: Test class membership + + \sstitem + \htmlref{astLock}{astLock}: Lock an Object for use by the calling thread + + \sstitem + \htmlref{astToString}{astToString}: Create an in-memory serialisation of an Object + + \sstitem + \htmlref{astSame}{astSame}: Do two AST pointers refer to the same Object? + + \sstitem + \htmlref{astSet}{astSet}: Set attribute values for an Object + + \sstitem + \htmlref{astSet$<$X$>$}{astSet$<$X$>$}: Set an attribute value for an Object + + \sstitem + \htmlref{astShow}{astShow}: Display a textual representation of an Object on standard + output + + \sstitem + \htmlref{astTest}{astTest}: Test if an attribute value is set for an Object + + \sstitem + \htmlref{astTune}{astTune}: Set or get an integer AST tuning parameter + + \sstitem + \htmlref{astTuneC}{astTuneC}: Set or get a character AST tuning parameter + + \sstitem + \htmlref{astUnlock}{astUnlock}: Unlock an Object for use by other threads + + \sstitem + \htmlref{astFromString}{astFromString}: Re-create an Object from an in-memory serialisation + + \sstitem + \htmlref{astVersion}{astVersion}: Return the verson of the AST library being used. + } + } +} +\sstroutine{ + PcdMap +}{ + Apply 2-dimensional pincushion/barrel distortion +}{ + \sstdescription{ + A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional + positions to correct for the radial distortion introduced by some + cameras and telescopes. This can take the form either of pincushion + or barrel distortion, and is characterized by a single distortion + coefficient. + + A PcdMap is specified by giving this distortion coefficient and the + coordinates of the centre of the radial distortion. The forward + transformation of a PcdMap applies the distortion: + + RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) + + where R is the undistorted radial distance from the distortion + centre (specified by attribute PcdCen), RD is the radial distance + from the same centre in the presence of distortion, and C is the + distortion coefficient (given by attribute \htmlref{Disco}{Disco}). + + The inverse transformation of a PcdMap removes the distortion + produced by the forward transformation. The expression used to derive + R from RD is an approximate inverse of the expression above. + } + \sstconstructor{ + \htmlref{astPcdMap}{astPcdMap} + } + \sstdiytopic{ + Inheritance + }{ + The PcdMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + PcdMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient + + \sstitem + \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion + } + } + \sstdiytopic{ + Functions + }{ + The PcdMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + PermMap +}{ + Coordinate permutation Mapping +}{ + \sstdescription{ + A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, + and possibly also changes the number of coordinates, between its + input and output. + + In addition to permuting the coordinate order, a PermMap may + also assign constant values to coordinates. This is useful when + the number of coordinates is being increased as it allows fixed + values to be assigned to any new ones. + } + \sstconstructor{ + \htmlref{astPermMap}{astPermMap} + } + \sstdiytopic{ + Inheritance + }{ + The PermMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The PermMap class does not define any new attributes beyond + those which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The PermMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Plot +}{ + Provide facilities for 2D graphical output +}{ + \sstdescription{ + This class provides facilities for producing 2D graphical output. + A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base + \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is + associated with a rectangular plotting area in the underlying + graphics system. This plotting area is where graphical output + appears. It is defined when the Plot is created. + + The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate + system, which is the coordinate system in which plotting + operations are specified. The results of each plotting operation + are automatically transformed into graphical coordinates so as + to appear in the plotting area (subject to any clipping which + may be in effect). + + Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates + may often be non-linear, or even discontinuous, most plotting + does not result in simple straight lines. The basic plotting + element is therefore not a straight line, but a geodesic curve + (see \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve} and \htmlref{astPolyCurve}{astPolyCurve}). A Plot also provides facilities for + drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines + (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with + optional coordinate grids (\htmlref{astGrid}{astGrid}). + A range of Plot attributes is available to allow precise control + over the appearance of graphical output produced by these + functions. + + You may select different physical coordinate systems in which to + plot (including the native graphical coordinate system itself) + by selecting different Frames as the current Frame of a Plot, + using its \htmlref{Current}{Current} attribute. You may also set up clipping (see + \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and + this may be done in any of the coordinate systems associated + with the Plot, not necessarily the one you are plotting in. + + Like any FrameSet, a Plot may also be used as a Frame. In this + case, it behaves like its current Frame, which describes the + physical coordinate system. + + When used as a Mapping, a Plot describes the inter-relation + between graphical coordinates (its base Frame) and physical + coordinates (its current Frame). It differs from a normal + FrameSet, however, in that an attempt to transform points which + lie in clipped areas of the Plot will result in bad coordinate + values (AST\_\_BAD). + } + \sstconstructor{ + \htmlref{astPlot}{astPlot} + } + \sstdiytopic{ + Inheritance + }{ + The Plot class inherits from the FrameSet class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all FrameSets, every + Plot also has the following attributes: + + \sstitemlist{ + + \sstitem + Abbrev: Abbreviate leading fields? + + \sstitem + \htmlref{Border}{Border}: Draw a border around valid regions of a Plot? + + \sstitem + \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary? + + \sstitem + \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR? + + \sstitem + \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element + + \sstitem + \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot? + + \sstitem + \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot? + + \sstitem + \htmlref{Escape}{Escape}: Allow changes of character attributes within strings? + + \sstitem + \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot + + \sstitem + \htmlref{Font(element)}{Font(element)}: Character font for a Plot element + + \sstitem + \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values + + \sstitem + \htmlref{Grf}{Grf}: Select the graphics interface to use. + + \sstitem + \htmlref{Grid}{Grid}: Draw grid lines for a Plot? + + \sstitem + \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink? + + \sstitem + \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot + + \sstitem + \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot? + + \sstitem + \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright? + + \sstitem + \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot + + \sstitem + \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values + + \sstitem + \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically? + + \sstitem + \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically? + + \sstitem + \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot + + \sstitem + \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot + + \sstitem + \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot + + \sstitem + \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot? + + \sstitem + \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot + + \sstitem + \htmlref{Size(element)}{Size(element)}: Character size for a Plot element + + \sstitem + \htmlref{Style(element)}{Style(element)}: Line style for a Plot element + + \sstitem + \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot? + + \sstitem + \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot + + \sstitem + \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot? + + \sstitem + \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title + + \sstitem + \htmlref{Tol}{Tol}: Plotting tolerance + + \sstitem + \htmlref{Width(element)}{Width(element)}: Line width for a Plot element + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all FrameSets, the + following functions may also be applied to all Plots: + + \sstitemlist{ + + \sstitem + \htmlref{astBBuf}{astBBuf}: Begin a new graphical buffering context + + \sstitem + \htmlref{astBorder}{astBorder}: Draw a border around valid regions of a Plot + + \sstitem + \htmlref{astBoundingBox}{astBoundingBox}: Returns a bounding box for previously drawn graphics + + \sstitem + \htmlref{astClip}{astClip}: Set up or remove clipping for a Plot + + \sstitem + \htmlref{astCurve}{astCurve}: Draw a geodesic curve + + \sstitem + \htmlref{astEBuf}{astEBuf}: End the current graphical buffering context + + \sstitem + \htmlref{astGenCurve}{astGenCurve}: Draw a generalized curve + + \sstitem + \htmlref{astGetGrfContext}{astGetGrfContext}: Get the graphics context for a Plot + + \sstitem + \htmlref{astGrfPop}{astGrfPop}: Retrieve previously saved graphics functions + + \sstitem + \htmlref{astGrfPush}{astGrfPush}: Save the current graphics functions + + \sstitem + \htmlref{astGrfSet}{astGrfSet}: Register a graphics routine for use by a Plot + + \sstitem + \htmlref{astGrid}{astGrid}: Draw a set of labelled coordinate axes + + \sstitem + \htmlref{astGridLine}{astGridLine}: Draw a grid line (or axis) for a Plot + + \sstitem + \htmlref{astMark}{astMark}: Draw a set of markers for a Plot + + \sstitem + \htmlref{astPolyCurve}{astPolyCurve}: Draw a series of connected geodesic curves + + \sstitem + \htmlref{astRegionOutline}{astRegionOutline}: Draw the outline of an AST \htmlref{Region}{Region} + + \sstitem + \htmlref{astText}{astText}: Draw a text string for a Plot + } + } + \sstdiytopic{ + Graphical Elements + }{ + The colour index, character font, character size, line style and + line width used for plotting can be set independently for + various elements of the graphical output produced by a Plot. + The different graphical elements are identified by appending the + strings listed below as subscripts to the Plot attributes + Colour(element), Font(element), Size(element), Style(element) + and Width(element). These strings are case-insensitive and + unambiguous abbreviations may be used. Elements of the graphical + output which relate to individual axes can be referred to either + independently (e.g. \texttt{"} (Grid1)\texttt{"} and \texttt{"} (Grid2)\texttt{"} ) or together (e.g. + \texttt{"} (Grid)\texttt{"} ): + + \sstitemlist{ + + \sstitem + Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using astGrid + + \sstitem + Axis1: Axis line drawn through tick marks on axis 1 using astGrid + + \sstitem + Axis2: Axis line drawn through tick marks on axis 2 using astGrid + + \sstitem + Border: The Plot border drawn using astBorder, astGrid or astRegionOutline + + \sstitem + Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve + + \sstitem + Grid: Grid lines drawn using astGridLine or astGrid + + \sstitem + Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid + + \sstitem + Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid + + \sstitem + Markers: Graphical markers (symbols) drawn using astMark + + \sstitem + NumLab: Numerical axis labels drawn using astGrid + + \sstitem + NumLab1: Numerical labels for axis 1 drawn using astGrid + + \sstitem + NumLab2: Numerical labels for axis 2 drawn using astGrid + + \sstitem + Strings: Text strings drawn using astText + + \sstitem + TextLab: Descriptive axis labels drawn using astGrid + + \sstitem + TextLab1: Descriptive label for axis 1 drawn using astGrid + + \sstitem + TextLab2: Descriptive label for axis 2 drawn using astGrid + + \sstitem + Ticks: Tick marks (both major and minor) drawn using astGrid + + \sstitem + Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid + + \sstitem + Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid + + \sstitem + \htmlref{Title}{Title}: The Plot title drawn using astGrid + } + } +} +\sstroutine{ + Plot3D +}{ + Provide facilities for 3D graphical output +}{ + \sstdescription{ + A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities + for producing 3D graphical output, including fully annotated 3D + coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional + \texttt{"} graphical\texttt{"} coordinate system. The axes of this coordinate system are + assumed to be right-handed (that is, if X appears horizontally to the + right and Y vertically upwards, then Z is out of the screen towards + the viewer), and are assumed to be equally scaled (that is, the same + units are used to measure positions on each of the 3 axes). The upper + and lower bounds of a volume within this graphical coordinate system + is specified when the Plot3D is created, and all subsequent graphics + are \texttt{"} drawn\texttt{"} in this volume. + + The Plot3D class does not itself include any ability to draw on a + graphics device. Instead it calls upon function in an externally + supplied module (the \texttt{"} grf3d\texttt{"} module) to do the required drawing. + A module should be written that implements the functions of the + grf3d interface using the facilities of a specific graphics system + This module should then be linked into the application so that the + Plot3D class can use its functions (see the description of the + \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface + defines a few simple functions for drawing primitives such as straight + lines, markers and character strings. These functions all accept + positions in the 3D graphics coordinate system (the base Frame of the + Plot3D), and so the grf3d module must also manage the projection of + these 3D coordinates onto the 2D viewing surface, including the choice + of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"} position, direction of viewing, etc. The AST + library includes a sample implementation of the grf3d interface + based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This + implementation also serves to document the grf3d interface itself and + should be consulted for details before writing a new implementation. + + The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"} 3-dimensional + coordinate system, which is the coordinate system in which plotting + operations are specified when invoking the methods of the Plot3D + class. The results of each plotting operation are automatically + transformed into 3D graphical coordinates before being plotted + using the facilities of the grf3d module linked into the application. + Note, at least one of the three axes of the current Frame must be + independent of the other two current Frame axes. + + You may select different physical coordinate systems in which to + plot (including the native graphical coordinate system itself) + by selecting different Frames as the current Frame of a Plot3D, + using its \htmlref{Current}{Current} attribute. + + Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this + case, it behaves like its current Frame, which describes the + physical coordinate system. + + When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation + between 3D graphical coordinates (its base Frame) and 3D physical + coordinates (its current Frame). + + Although the Plot3D class inherits from the Plot class, several of + the facilities of the Plot class are not available in the Plot3D + class, and an error will be reported if any attempt is made to use + them. Specifically, the Plot3D class does not support clipping + using the + \htmlref{astClip}{astClip} function. + Nor does it support the specification of graphics primitive functions + at run-time using the + \htmlref{astGrfSet}{astGrfSet}, \htmlref{astGrfPop}{astGrfPop}, \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGetGrfContext}{astGetGrfContext} functions. + } + \sstconstructor{ + \htmlref{astPlot3D}{astPlot3D} + } + \sstdiytopic{ + Inheritance + }{ + The Plot3D class inherits from the Plot class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Plots, every + Plot3D also has the following attributes: + + \sstitemlist{ + + \sstitem + Norm: Normal vector defining the 2D plane used for text and markers + + \sstitem + \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated. + + } + Some attributes of the Plot class refer to specific physical + coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic + Plot, the axis index must be 1 or 2, but for a Plot3D the axis index + can be 1, 2 or 3. + + Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, + \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation + for details. All other Plot attributes can be set for a specific + plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"} + or \texttt{"} \_YZ\texttt{"} to the end of the Plot attribute name. For instance, + \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"} refers to the \texttt{"} Grid\texttt{"} attribute for the plane spanning + the second (Y) and third (Z) axes of the 3-d plot. + } + \sstdiytopic{ + Functions + }{ + The Plot3D class does not define any new functions beyond those + which are applicable to all Plots. Note, however, that the + following methods inherited from the Plot class cannot be used with + a Plot3D and will report an error if called: + \sstitemlist{ + + \sstitem + \htmlref{astBoundingBox}{astBoundingBox}, astClip, \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve}, + astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, \htmlref{astGridLine}{astGridLine}, + \htmlref{astPolyCurve}{astPolyCurve}. + } + } +} +\sstroutine{ + PointList +}{ + A collection of points in a Frame +}{ + \sstdescription{ + The PointList class implements a \htmlref{Region}{Region} which represents a collection + of points in a \htmlref{Frame}{Frame}. + } + \sstconstructor{ + \htmlref{astPointList}{astPointList} + } + \sstdiytopic{ + Inheritance + }{ + The PointList class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Regions, every + PointList also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList + } + } + \sstdiytopic{ + Functions + }{ + The PointList class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + PolyMap +}{ + Map coordinates using polynomial functions +}{ + \sstdescription{ + A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial + transformation. Each output coordinate is a polynomial function of + all the input coordinates. The coefficients are specified separately + for each output coordinate. The forward and inverse transformations + are defined independantly by separate sets of coefficients. If no + inverse transformation is supplied, an iterative method can be used + to evaluate the inverse based only on the forward transformation. + } + \sstconstructor{ + \htmlref{astPolyMap}{astPolyMap} + } + \sstdiytopic{ + Inheritance + }{ + The PolyMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + PolyMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation? + + \sstitem + \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse + + \sstitem + \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Objects, the + following functions may also be applied to all Mappings: + + \sstitemlist{ + + \sstitem + \htmlref{astPolyTran}{astPolyTran}: Fit a PolyMap inverse or forward transformation + } + } +} +\sstroutine{ + Polygon +}{ + A polygonal region within a 2-dimensional Frame +}{ + \sstdescription{ + The Polygon class implements a polygonal area, defined by a + collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices + are connected together by geodesic curves within the encapsulated Frame. + For instance, if the encapsulated Frame is a simple Frame then the + geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then + the geodesics will be great circles. Note, the vertices must be + supplied in an order such that the inside of the polygon is to the + left of the boundary as the vertices are traversed. Supplying them + in the reverse order will effectively negate the polygon. + + Within a SkyFrame, neighbouring vertices are always joined using the + shortest path. Thus if an edge of 180 degrees or more in length is + required, it should be split into section each of which is less + than 180 degrees. The closed path joining all the vertices in order + will divide the celestial sphere into two disjoint regions. The + inside of the polygon is the region which is circled in an + anti-clockwise manner (when viewed from the inside of the celestial + sphere) when moving through the list of vertices in the order in + which they were supplied when the Polygon was created (i.e. the + inside is to the left of the boundary when moving through the + vertices in the order supplied). + } + \sstconstructor{ + \htmlref{astPolygon}{astPolygon} + } + \sstdiytopic{ + Inheritance + }{ + The Polygon class inherits from the \htmlref{Region}{Region} class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Regions, every + Polygon also has the following attributes: + \sstitemlist{ + + \sstitem + \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices? + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Regions, the + following functions may also be applied to all Polygons: + + \sstitemlist{ + + \sstitem + \htmlref{astDownsize}{astDownsize}: Reduce the number of vertices in a Polygon. + + \sstitem + \htmlref{astConvex$<$X$>$}{astConvex$<$X$>$}: Create a Polygon giving the convex hull of a pixel array + + \sstitem + \htmlref{astOutline$<$X$>$}{astOutline$<$X$>$}: Create a Polygon outlining values in a pixel array + } + } +} +\sstroutine{ + Prism +}{ + An extrusion of a region into higher dimensions +}{ + \sstdescription{ + A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region + into one or more orthogonal dimensions (specified by another Region). + If the Region to be extruded has N axes, and the Region defining the + extrusion has M axes, then the resulting Prism will have (M$+$N) axes. + A point is inside the Prism if the first N axis values correspond to + a point inside the Region being extruded, and the remaining M axis + values correspond to a point inside the Region defining the extrusion. + + As an example, a cylinder can be represented by extruding an existing + \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the + Interval would have a single axis and would specify the upper and + lower limits of the cylinder along its length. + } + \sstconstructor{ + \htmlref{astPrism}{astPrism} + } + \sstdiytopic{ + Inheritance + }{ + The Prism class inherits from the Region class. + } + \sstdiytopic{ + Attributes + }{ + The Prism class does not define any new attributes beyond those + which are applicable to all Regions. + } + \sstdiytopic{ + Functions + }{ + The Prism class does not define any new functions beyond those + which are applicable to all Regions. + } +} +\sstroutine{ + RateMap +}{ + Mapping which represents differentiation +}{ + \sstdescription{ + A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the + Jacobian matrix of another Mapping. The Mapping for which the + Jacobian is required is specified when the new RateMap is created, + and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. + + The number of inputs to a RateMap is the same as the number of inputs + to its encapsulated Mapping. The number of outputs from a RateMap + is always one. This one output equals the rate of change of a + specified output of the encapsulated Mapping with respect to a + specified input of the encapsulated Mapping (the input and output + to use are specified when the RateMap is created). + + A RateMap which has not been inverted does not define an inverse + transformation. If a RateMap has been inverted then it will define + an inverse transformation but not a forward transformation. + } + \sstconstructor{ + \htmlref{astRateMap}{astRateMap} + } + \sstdiytopic{ + Inheritance + }{ + The RateMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The RateMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The RateMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Region +}{ + Represents a region within a coordinate system +}{ + \sstdescription{ + This class provides the basic facilities for describing a region within + a specified coordinate system. However, the Region class does not + have a constructor function of its own, as it is simply a container + class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc, + which implement Regions with particular shapes. + + All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region + is created. This Frame describes the coordinate system in which the + Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"} below. + Constructors will also typically required one or more positions to be + supplied which define the location and extent of the region. These + positions must be supplied within the encapsulated Frame. + + The Region class inherits from the Frame class, and so a Region can be + supplied where-ever a Frame is expected. In these cases, supplying a + Region is equivalent to supplying a reference to its encapsulated Frame. + Thus all the methods of the Frame class can be used on the Region class. + For instance, the + \htmlref{astFormat}{astFormat} function + may be used on a Region to format an axis value. + + In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort + of Mapping. Transforming positions by supplying a Region to one of the + astTran$<$X$>$ functions + is the way to determine if a given position is inside or outside the + Region. When used as a Mapping, most classes of Frame are equivalent to + a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a + Region acts like a UnitMap only for input positions which are within the + area represented by the Region. Input positions which are outside the + area produce bad output values (i.e. the output values are equal to + AST\_\_BAD). This behaviour is the same for both the forward and the + inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"} + is not a true inverse of the forward transformation, since applying + the forward transformation to a point outside the Region, and then + applying the inverse transformation results, in a set of AST\_\_BAD axis + values rather than the original axis values. If required, the + \htmlref{astRemoveRegions}{astRemoveRegions} + function can be used to remove the \texttt{"} masking\texttt{"} effect of any Regions + contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by + replacing each Region with a UnitMap or equivalent Frame (depending + on the context in which the Region is used). + + If the coordinate system represented by the Region is changed (by + changing the values of one or more of the attribute which the Region + inherits from its encapsulated Frame), the area represented by + the Region is mapped into the new coordinate system. For instance, let\texttt{'} s + say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being + supplied to the constructor so that the Circle describes a circular + area on the sky in FK4 equatorial coordinates. Since Region inherits + from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute + will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then + changed from FK4 to FK5, the circular area represented by the Region + will automatically be mapped from the FK4 system into the FK5 system. + In general, changing the coordinate system in this way may result in the + region changing shape - for instance, a circle may change into an + ellipse if the transformation from the old to the new coordinate system + is linear but with different scales on each axis. Thus the specific + class of a Region cannot be used as a guarantee of the shape in any + particular coordinate system. If the + \htmlref{astSimplify}{astSimplify} function + is used on a Region, it will endeavour to return a new Region of + a sub-class which accurately describes the shape in the current + coordinate system of the Region (but this may not always be possible). + + It is possible to negate an existing Region so that it represents all + areas of the encapsulated Frame except for the area specified when + the Region was created. + } + \sstconstructor{ + None. + } + \sstdiytopic{ + Inheritance + }{ + The Region class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + Region also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system? + + \sstitem + \htmlref{Negated}{Negated}: Has the original region been negated? + + \sstitem + \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region? + + \sstitem + \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region + + \sstitem + \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest + + \sstitem + \htmlref{Bounded}{Bounded}: Is the Region bounded? + + } + Every Region also inherits any further attributes that belong + to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For + example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is + inherited by any Region which represents a SkyFrame.) + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Frames, the + following functions may also be applied to all Regions: + + \sstitemlist{ + + \sstitem + \htmlref{astGetRegionBounds}{astGetRegionBounds}: Get the bounds of a Region + + \sstitem + \htmlref{astGetRegionFrame}{astGetRegionFrame}: Get a copy of the Frame represent by a Region + + \sstitem + \htmlref{astGetRegionFrameSet}{astGetRegionFrameSet}: Get a copy of the Frameset encapsulated by a Region + + \sstitem + \htmlref{astGetRegionMesh}{astGetRegionMesh}: Get a mesh of points covering a Region + + \sstitem + \htmlref{astGetRegionPoints}{astGetRegionPoints}: Get the positions that define a Region + + \sstitem + \htmlref{astGetUnc}{astGetUnc}: Obtain uncertainty information from a Region + + \sstitem + \htmlref{astMapRegion}{astMapRegion}: Transform a Region into a new coordinate system + + \sstitem + \htmlref{astNegate}{astNegate}: Toggle the value of the Negated attribute + + \sstitem + \htmlref{astOverlap}{astOverlap}: Determines the nature of the overlap between two Regions + + \sstitem + \htmlref{astMask$<$X$>$}{astMask$<$X$>$}: Mask a region of a data grid + + \sstitem + \htmlref{astSetUnc}{astSetUnc}: Associate a new uncertainty with a Region + + \sstitem + \htmlref{astShowMesh}{astShowMesh}: Display a mesh of points on the surface of a Region + } + } +} +\sstroutine{ + SelectorMap +}{ + A Mapping that locates positions within one of a set of alternate + Regions +}{ + \sstdescription{ + A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains + a given input position. + + A SelectorMap encapsulates a number of Regions that all have the same + number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of + inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes + spanned by one of the encapsulated Region. All SelectorMaps have only + a single output. SelectorMaps do not define an inverse transformation. + + For each input position, the forward transformation of a SelectorMap + searches through the encapsulated Regions (in the order supplied when + the SelectorMap was created) until a Region is found which contains + the input position. The index associated with this Region is + returned as the SelectorMap output value (the index value is the + position of the Region within the list of Regions supplied when the + SelectorMap was created, starting at 1 for the first Region). If an + input position is not contained within any Region, a value of zero is + returned by the forward transformation. + + If a compound Mapping contains a SelectorMap in series with its own + inverse, the combination of the two adjacent SelectorMaps will be + replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using + \htmlref{astSimplify}{astSimplify}. + + In practice, SelectorMaps are often used in conjunction with SwitchMaps. + } + \sstconstructor{ + \htmlref{astSelectorMap}{astSelectorMap} + } + \sstdiytopic{ + Inheritance + }{ + The SelectorMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The SelectorMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The SelectorMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + ShiftMap +}{ + Add a constant value to each coordinate +}{ + \sstdescription{ + A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a + specified constant value. + } + \sstconstructor{ + \htmlref{astShiftMap}{astShiftMap} + } + \sstdiytopic{ + Inheritance + }{ + The ShiftMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The ShiftMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The ShiftMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + SkyAxis +}{ + Store celestial axis information +}{ + \sstdescription{ + The SkyAxis class is used to store information associated with a + particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST + library and has no constructor function. You should encounter it + only within textual output (e.g. from \htmlref{astWrite}{astWrite}). + } + \sstconstructor{ + None. + } + \sstdiytopic{ + Inheritance + }{ + The SkyAxis class inherits from the \htmlref{Axis}{Axis} class. + } +} +\sstroutine{ + SkyFrame +}{ + Celestial coordinate system description +}{ + \sstdescription{ + A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes + celestial longitude/latitude coordinate systems. The particular + celestial coordinate system to be represented is specified by + setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default + is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or + an \htmlref{Epoch}{Epoch}. + + For each of the supported celestial coordinate systems, a SkyFrame + can apply an optional shift of origin to create a coordinate system + representing offsets within the celestial coordinate system from some + specified reference point. This offset coordinate system can also be + rotated to define new longitude and latitude axes. See attributes + SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. + + All the coordinate values used by a SkyFrame are in + radians. These may be formatted in more conventional ways for + display by using \htmlref{astFormat}{astFormat}. + For a SkyFrame, the Unit attribute describes the formatted value of + a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a + formatted axis value contains colon-separated fields for hours, minutes + and seconds. On the other hand, the InternalUnit attribute for a + SkyFrame is always set to \texttt{"} rad\texttt{"} (i.e. radians), indicating that the + unformatted (i.e. floating point) axis values used by application code + are always in units of radians + } + \sstconstructor{ + \htmlref{astSkyFrame}{astSkyFrame} + } + \sstdiytopic{ + Inheritance + }{ + The SkyFrame class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + SkyFrame also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system? + + \sstitem + \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times? + + \sstitem + \htmlref{Equinox}{Equinox}: Epoch of the mean equinox + + \sstitem + IsLatAxis: Is the specified axis the latitude axis? + + \sstitem + IsLonAxis: Is the specified axis the longitude axis? + + \sstitem + \htmlref{LatAxis}{LatAxis}: Index of the latitude axis + + \sstitem + \htmlref{LonAxis}{LonAxis}: Index of the longitude axis + + \sstitem + \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]? + + \sstitem + \htmlref{Projection}{Projection}: Sky projection description. + + \sstitem + SkyRef: Position defining location of the offset coordinate system + + \sstitem + \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system + + \sstitem + SkyRefP: Position defining orientation of the offset coordinate system + + \sstitem + \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates + } + } + \sstdiytopic{ + Functions + }{ + In addition to those + functions + applicable to all Frames, the following + functions + may also be applied to all SkyFrames: + + \sstitemlist{ + + \sstitem + \htmlref{astSkyOffsetMap}{astSkyOffsetMap}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates + } + } +} +\sstroutine{ + SlaMap +}{ + Sequence of celestial coordinate conversions +}{ + \sstdescription{ + An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to + represent a sequence of conversions between standard celestial + (longitude, latitude) coordinate systems. + + When an SlaMap is first created, it simply performs a unit + (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd} + function, a series of coordinate conversion steps may then be + added, selected from those provided by the SLALIB Positional + Astronomy Library (Starlink User Note SUN/67). This allows + multi-step conversions between a variety of celestial coordinate + systems to be assembled out of the building blocks provided by + SLALIB. + + For details of the individual coordinate conversions available, + see the description of the astSlaAdd function. + } + \sstconstructor{ + \htmlref{astSlaMap}{astSlaMap} (also see astSlaAdd) + } + \sstdiytopic{ + Inheritance + }{ + The SlaMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The SlaMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Mappings, the + following function may also be applied to all SlaMaps: + + \sstitemlist{ + + \sstitem + \htmlref{astSlaAdd}{astSlaAdd}: Add a celestial coordinate conversion to an SlaMap + } + } +} +\sstroutine{ + SpecFluxFrame +}{ + Compound spectrum/flux Frame +}{ + \sstdescription{ + A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single + 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used + to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents + spectral position and the second axis represents flux. + } + \sstconstructor{ + \htmlref{astSpecFluxFrame}{astSpecFluxFrame} + } + \sstdiytopic{ + Inheritance + }{ + The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class. + } + \sstdiytopic{ + Attributes + }{ + The SpecFluxFrame class does not define any new attributes beyond + those which are applicable to all CmpFrames. However, the attributes + of the component Frames can be accessed as if they were attributes + of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise + the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"} attribute and forward access requests to the component + SpecFrame. An axis index can optionally be appended to the end of any + attribute name, in which case the request to access the attribute will + be forwarded to the primary Frame defining the specified axis. + } + \sstdiytopic{ + Functions + }{ + The SpecFluxFrame class does not define any new functions beyond those + which are applicable to all CmpFrames. + } +} +\sstroutine{ + SpecFrame +}{ + Spectral coordinate system description +}{ + \sstdescription{ + A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various coordinate systems used to describe positions within + an electro-magnetic spectrum. The particular coordinate system to be + used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the + default is wavelength) qualified, as necessary, by other attributes + such as the rest frequency, the standard of rest, the epoch of + observation, units, etc (see the description of the System attribute + for details). + + By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made + to represent offsets from a given spectral position, rather than absolute + spectral values. + } + \sstconstructor{ + \htmlref{astSpecFrame}{astSpecFrame} + } + \sstdiytopic{ + Inheritance + }{ + The SpecFrame class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + SpecFrame also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system? + + \sstitem + \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames + + \sstitem + \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000) + + \sstitem + \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000) + + \sstitem + \htmlref{RestFreq}{RestFreq}: Rest frequency + + \sstitem + \htmlref{SourceSys}{SourceSys}: Source velocity spectral system + + \sstitem + \htmlref{SourceVel}{SourceVel}: Source velocity + + \sstitem + \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame + + \sstitem + \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values + + \sstitem + \htmlref{StdOfRest}{StdOfRest}: Standard of rest + + } + Several of the Frame attributes inherited by the SpecFrame class + refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, + \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional, + it allows these attributes to be specified without an axis index. + So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Frames, the + following functions may also be applied to all SpecFrames: + + \sstitemlist{ + + \sstitem + \htmlref{astSetRefPos}{astSetRefPos}: Set reference position in any celestial system + + \sstitem + \htmlref{astGetRefPos}{astGetRefPos}: Get reference position in any celestial system + } + } +} +\sstroutine{ + SpecMap +}{ + Sequence of spectral coordinate conversions +}{ + \sstdescription{ + A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to + represent a sequence of conversions between standard spectral + coordinate systems. + + When an SpecMap is first created, it simply performs a unit + (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} + function, a series of coordinate conversion steps may then be + added. This allows multi-step conversions between a variety of + spectral coordinate systems to be assembled out of a set of building + blocks. + + Conversions are available to transform between standards of rest. + Such conversions need to know the source position as an RA and DEC. + This information can be supplied in the form of parameters for + the relevant conversions, in which case the SpecMap is 1-dimensional, + simply transforming the spectral axis values. This means that the + same source position will always be used by the SpecMap. However, this + may not be appropriate for an accurate description of a 3-D spectral + cube, where changes of spatial position can produce significant + changes in the Doppler shift introduced when transforming between + standards of rest. For this situation, a 3-dimensional SpecMap can + be created in which axes 2 and 3 correspond to the source RA and DEC + The SpecMap simply copies values for axes 2 and 3 from input to + output), but modifies axis 1 values (the spectral axis) appropriately. + + For details of the individual coordinate conversions available, + see the description of the astSpecAdd function. + } + \sstconstructor{ + \htmlref{astSpecMap}{astSpecMap} (also see astSpecAdd) + } + \sstdiytopic{ + Inheritance + }{ + The SpecMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The SpecMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Mappings, the + following function may also be applied to all SpecMaps: + + \sstitemlist{ + + \sstitem + \htmlref{astSpecAdd}{astSpecAdd}: Add a spectral coordinate conversion to an SpecMap + } + } +} +\sstroutine{ + SphMap +}{ + Map 3-d Cartesian to 2-d spherical coordinates +}{ + \sstdescription{ + A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a + 3-dimensional Cartesian coordinate system into a 2-dimensional + spherical coordinate system (longitude and latitude on a unit + sphere centred at the origin). It works by regarding the input + coordinates as position vectors and finding their intersection + with the sphere surface. The inverse transformation always + produces points which are a unit distance from the origin + (i.e. unit vectors). + } + \sstconstructor{ + \htmlref{astSphMap}{astSphMap} + } + \sstdiytopic{ + Inheritance + }{ + The SphMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + SphMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere? + + \sstitem + \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole + } + } + \sstdiytopic{ + Functions + }{ + The SphMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Stc +}{ + Represents an instance of the IVOA STC class +}{ + \sstdescription{ + The Stc class is an implementation of the IVOA STC class which forms + part of the IVOA Space-Time Coordinate Metadata system. See: + + http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + + The Stc class does not have a constructor function of its own, as it + is simply a container class for a family of specialised sub-classes + including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation} + and \htmlref{StcObsDataLocation}{StcObsDataLocation}. + } + \sstconstructor{ + astStc + } + \sstdiytopic{ + Inheritance + }{ + The Stc class inherits from the \htmlref{Region}{Region} class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Regions, every + Stc also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region. + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Regions, the + following functions may also be applied to all Stc\texttt{'} s: + + \sstitemlist{ + + \sstitem + \htmlref{astGetStcRegion}{astGetStcRegion}: Get a pointer to the encapsulated Region + + \sstitem + \htmlref{astGetStcCoord}{astGetStcCoord}: Get information about an AstroCoords element + + \sstitem + \htmlref{astGetStcNCoord}{astGetStcNCoord}: Returns the number of AstroCoords elements in an Stc + } + } +} +\sstroutine{ + StcCatalogEntryLocation +}{ + Correspond to the IVOA STCCatalogEntryLocation class +}{ + \sstdescription{ + The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of the datasets contained in some VO resource. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstconstructor{ + \htmlref{astStcCatalogEntryLocation}{astStcCatalogEntryLocation} + } + \sstdiytopic{ + Inheritance + }{ + The StcCatalogEntryLocation class inherits from the Stc class. + } + \sstdiytopic{ + Attributes + }{ + The StcCatalogEntryLocation class does not define any new attributes beyond + those which are applicable to all Stcs. + } + \sstdiytopic{ + Functions + }{ + The StcCatalogEntryLocation class does not define any new functions beyond those + which are applicable to all Stcs. + } +} +\sstroutine{ + StcObsDataLocation +}{ + Correspond to the IVOA ObsDataLocation class +}{ + \sstdescription{ + The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coordinate space occupied by a particular observational dataset. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + + An STC ObsDataLocation element specifies the extent of the + observation within a specified coordinate system, and also specifies + the observatory location within a second coordinate system. + + The AST StcObsDataLocation class inherits from Stc, and therefore + an StcObsDataLocation can be used directly as an Stc. When used + in this way, the StcObsDataLocation describes the location of the + observation (not the observatory). + + Eventually, this class will have a method for returning an Stc + describing the observatory location. However, AST currently does not + include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar + system positions. Therefore, the provision for returning observatory + location as an Stc is not yet available. However, for terrestrial + observations, the position of the observatory can still be recorded + using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated + within the Stc representing the observation location (this assumes + the observatory is located at sea level). + } + \sstconstructor{ + \htmlref{astStcObsDataLocation}{astStcObsDataLocation} + } + \sstdiytopic{ + Inheritance + }{ + The StcObsDataLocation class inherits from the Stc class. + } + \sstdiytopic{ + Attributes + }{ + The StcObsDataLocation class does not define any new attributes beyond + those which are applicable to all Stcs. + } + \sstdiytopic{ + Functions + }{ + The StcObsDataLocation class does not define any new functions beyond those + which are applicable to all Stcs. + } +} +\sstroutine{ + StcResourceProfile +}{ + Correspond to the IVOA STCResourceProfile class +}{ + \sstdescription{ + The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of the datasets contained in some VO resource. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstconstructor{ + \htmlref{astStcResourceProfile}{astStcResourceProfile} + } + \sstdiytopic{ + Inheritance + }{ + The StcResourceProfile class inherits from the Stc class. + } + \sstdiytopic{ + Attributes + }{ + The StcResourceProfile class does not define any new attributes beyond + those which are applicable to all Stcs. + } + \sstdiytopic{ + Functions + }{ + The StcResourceProfile class does not define any new functions beyond those + which are applicable to all Stcs. + } +} +\sstroutine{ + StcSearchLocation +}{ + Correspond to the IVOA SearchLocation class +}{ + \sstdescription{ + The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe + the coverage of a query. + + See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html + } + \sstconstructor{ + \htmlref{astStcSearchLocation}{astStcSearchLocation} + } + \sstdiytopic{ + Inheritance + }{ + The StcSearchLocation class inherits from the Stc class. + } + \sstdiytopic{ + Attributes + }{ + The StcSearchLocation class does not define any new attributes beyond + those which are applicable to all Stcs. + } + \sstdiytopic{ + Functions + }{ + The StcSearchLocation class does not define any new functions beyond those + which are applicable to all Stcs. + } +} +\sstroutine{ + StcsChan +}{ + I/O Channel using STC-S to represent Objects +}{ + \sstdescription{ + A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S + I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an + STC-S description of that Object, and reading from an StcsChan will + create a new Object from its STC-S description. + + When an STC-S description is read using + \htmlref{astRead}{astRead}, + the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC + AstroCoords (i.e. a single point of interest within the coordinate frame + described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC + AstrCoordsArea (i.e. an area or volume of interest within the coordinate + frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap} + containing the uninterpreted property values read form the STC-S + description, or 4) a KeyMap containing any combination of the first + 3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} + control which of the above is returned by + astRead. + + When an STC-S description is created from an AST Object using + astWrite, + the AST Object must be either a Region or a KeyMap. If it is a + Region, it is assumed to define the AstroCoordsArea or (if the + Region is a single point) the AstroCoords to write to the STC-S + description. If the Object is a KeyMap, it may contain an entry + with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the + AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} , + holding a Region (a PointList) to be used to create the + AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding + a KeyMap that contains uninterpreted property values to be used as + defaults for any STC-S properties that are not determined by the + other supplied Regions. In addition, a KeyMap supplied to + astWrite + may itself hold the default STC-S properties (rather than defaults + being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"} entry in the + supplied KeyMap). + + The + astRead and astWrite + functions work together so that any Object returned by + astRead can immediately be re-written using astWrite. + + Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting text. These functions + should perform any conversions needed between external character + encodings and the internal ASCII encoding. If no such functions + are supplied, a Channel will read from standard input and write + to standard output. + + Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + + Support for STC-S is currently based on the IVOA document \texttt{"} STC-S: + Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} , + version 1.30 (dated 5th December 2007), available at + http://www.ivoa.net/Documents/latest/STC-S.html. Note, this + document is a recommednation only and does not constitute an accepted + IVOA standard. + + The full text of version 1.30 is supported by the StcsChan class, + with the following exceptions and provisos: + + \sstitemlist{ + + \sstitem + When reading an STC-S phrase, case is ignored except when reading + units strings. + + \sstitem + There is no support for multiple intervals specified within a + TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval. + + \sstitem + If the ET timescale is specified, TT is used instead. + + \sstitem + If the TEB timescale is specified, TDB is used instead. + + \sstitem + The LOCAL timescale is not supported. + + \sstitem + The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a + reference position to be specified. Consequently, any $<$refpos$>$ + specified within the Time or Space sub-phrase of an STC-S document + is ignored. + + \sstitem + The Convex identifier for the space sub-phrase is not supported. + + \sstitem + The GEO\_C and GEO\_D space frames are not supported. + + \sstitem + The UNITSPHERE and SPHER3 space flavours are not supported. + + \sstitem + If any Error values are supplied in a space sub-phrase, then the + number of values supplied should equal the number of spatial axes, + and the values are assumed to specify an error box (i.e. error + circles, ellipses, etc, are not supported). + + \sstitem + The spectral and redshift sub-phrases do not support the + following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos, + EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, + NEPTUNE, PLUTO. + + \sstitem + Error values are supported but error ranges are not. + + \sstitem + Resolution, PixSize and Size values are ignored. + + \sstitem + Space velocity sub-phrases are ignored. + } + } + \sstconstructor{ + \htmlref{astStcsChan}{astStcsChan} + } + \sstdiytopic{ + Inheritance + }{ + The StcsChan class inherits from the Channel class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Channels, every + StcsChan also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S? + + \sstitem + \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S? + + \sstitem + \htmlref{StcsLength}{StcsLength}: Controls output buffer length + + \sstitem + \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S? + } + } + \sstdiytopic{ + Functions + }{ + The StcsChan class does not define any new functions beyond those + which are applicable to all Channels. + } +} +\sstroutine{ + SwitchMap +}{ + A Mapping that encapsulates a set of alternate Mappings +}{ + \sstdescription{ + A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate + Mappings, each of which is used to transform positions within a + particular region of the input or output coordinate system of the + SwitchMap. + + A SwitchMap can encapsulate any number of Mappings, but they must + all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the + same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself + inherits these same values for its Nin and Nout attributes. Each of + these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are + referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms + positions between the input and output coordinate space of the entire + SwitchMap, but only one Mapping will be used to transform any given + position. The selection of the appropriate route Mapping to use with + any given input position is made by another Mapping, called the + \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector + Mappings in addition to its route Mappings; one for use with the + SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector + Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation + (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping + must have the same number of inputs as the route Mappings, but + should have only one output. Likewise, the inverse selector Mapping + must have the same number of outputs as the route Mappings, but + should have only one input. + + When the SwitchMap is used to transform a position in the forward + direction (from input to output), each supplied input position is + first transformed by the forward transformation of the forward selector + Mapping. This produces a single output value for each input position + referred to as the selector value. The nearest integer to the selector + value is found, and is used to index the array of route Mappings (the + first supplied route Mapping has index 1, the second route Mapping has + index 2, etc). If the nearest integer to the selector value is less + than 1 or greater than the number of route Mappings, then the SwitchMap + output position is set to a value of AST\_\_BAD on every axis. Otherwise, + the forward transformation of the selected route Mapping is used to + transform the supplied input position to produce the SwitchMap output + position. + + When the SwitchMap is used to transform a position in the inverse + direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position + is first transformed by the inverse transformation of the inverse + selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} + position. Again, the nearest integer to the selector value is found, + and is used to index the array of route Mappings. If this selector + index value is within the bounds of the array of route Mappings, then + the inverse transformation of the selected route Mapping is used to + transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap + \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds + of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is + set to a value of AST\_\_BAD on every axis. + + In practice, appropriate selector Mappings should be chosen to + associate a different route Mapping with each region of coordinate + space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly + appropriate for this purpose. + + If a compound Mapping contains a SwitchMap in series with its own + inverse, the combination of the two adjacent SwitchMaps will be + replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using + \htmlref{astSimplify}{astSimplify}. + } + \sstconstructor{ + \htmlref{astSwitchMap}{astSwitchMap} + } + \sstdiytopic{ + Inheritance + }{ + The SwitchMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The SwitchMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The SwitchMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + Table +}{ + A 2-dimensional table of values +}{ + \sstdescription{ + The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional + table of values. The + astMapGet... and astMapPut... + methods provided by the KeyMap class should be used for storing and + retrieving values from individual cells within a Table. Each entry + in the KeyMap represents a single cell of the table and has an + associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the + upper-case name of a table column and \texttt{"} i\texttt{"} is the row index (the + first row is row 1). Keys of this form should always be used when + using KeyMap methods to access entries within a Table. + + Columns must be declared using the + \htmlref{astAddColumn}{astAddColumn} + method before values can be stored within them. This also fixes the + type and shape of the values that may be stored in any cell of the + column. Cells may contain scalar or vector values of any data type + supported by the KeyMap class. Multi-dimensional arrays may also be + stored, but these must be vectorised when storing and retrieving + them within a table cell. All cells within a single column must + have the same type and shape, as specified when the column is added + to the Table. + + Tables may have parameters that describe global properties of the + entire table. These are stored as entries in the parent KeyMap and + can be access using the get and set method of the KeyMap class. + However, parameters must be declared using the + \htmlref{astAddParameter}{astAddParameter} + method before being accessed. + + Note - since accessing entries within a KeyMap is a relatively slow + process, it is not recommended to use the Table class to store + very large tables. + } + \sstconstructor{ + \htmlref{astTable}{astTable} + } + \sstdiytopic{ + Inheritance + }{ + The Table class inherits from the KeyMap class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all KeyMaps, every + Table also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column + + \sstitem + \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column + + \sstitem + \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column + + \sstitem + \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column + + \sstitem + ColumnUnit(column): The unit string describing each value in a column + + \sstitem + \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table + + \sstitem + \htmlref{Nrow}{Nrow}: The number of rows currently in the Table + + \sstitem + \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table + } + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all KeyMaps, the + following functions may also be applied to all Tables: + + \sstitemlist{ + + \sstitem + \htmlref{astAddColumn}{astAddColumn}: Add a new column definition to a Table + + \sstitem + \htmlref{astAddParameter}{astAddParameter}: Add a new global parameter definition to a Table + + \sstitem + \htmlref{astColumnName}{astColumnName}: Return the name of the column with a given index + + \sstitem + \htmlref{astColumnShape}{astColumnShape}: Return the shape of the values in a named column + + \sstitem + \htmlref{astHasColumn}{astHasColumn}: Checks if a column exists in a Table + + \sstitem + \htmlref{astHasParameter}{astHasParameter}: Checks if a global parameter exists in a Table + + \sstitem + \htmlref{astParameterName}{astParameterName}: Return the name of the parameter with a given index + + \sstitem + \htmlref{astPurgeRows}{astPurgeRows}: Remove all empty rows from a Table + + \sstitem + \htmlref{astRemoveColumn}{astRemoveColumn}: Remove a column from a Table + + \sstitem + \htmlref{astRemoveParameter}{astRemoveParameter}: Remove a global parameter from a Table + + \sstitem + \htmlref{astRemoveRow}{astRemoveRow}: Remove a row from a Table + } + } +} +\sstroutine{ + TimeFrame +}{ + Time coordinate system description +}{ + \sstdescription{ + A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which + represents various coordinate systems used to describe positions in + time. + + A TimeFrame represents a moment in time as either an Modified Julian + Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, + as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be + specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame + representing time offsets from the specified zero point. + + Even though JD and MJD are defined as being in units of days, the + TimeFrame class allows other units to be used (via the Unit attribute) + on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 + hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs + can be described in units other than the usual years. Besselian epoch + are always represented in units of (tropical) years. + + The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that + is, the physical process used to define the rate of flow of time). + MJD, JD and Julian epoch can be used to represent a time in any + supported time scale. However, Besselian epoch may only be used with the + \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales + includes universal time and siderial time. Strictly, these represent + angles rather than time scales, but are included in the list since + they are in common use and are often thought of as time scales. + + When a time value is formatted it can be formated either as a simple + floating point value, or as a Gregorian date (see the Format + attribute). + } + \sstconstructor{ + \htmlref{astTimeFrame}{astTimeFrame} + } + \sstdiytopic{ + Inheritance + }{ + The TimeFrame class inherits from the Frame class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Frames, every + TimeFrame also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames + + \sstitem + \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours. + + \sstitem + \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values + + \sstitem + \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame + + } + Several of the Frame attributes inherited by the TimeFrame class + refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, + \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional, + it allows these attributes to be specified without an axis index. + So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Frames, the + following functions may also be applied to all TimeFrames: + + \sstitemlist{ + + \sstitem + \htmlref{astCurrentTime}{astCurrentTime}: Return the current system time + } + } +} +\sstroutine{ + TimeMap +}{ + Sequence of time coordinate conversions +}{ + \sstdescription{ + A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be + used to represent a sequence of conversions between standard time + coordinate systems. + + When a TimeMap is first created, it simply performs a unit + (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd} + function, a series of coordinate conversion steps may then be + added. This allows multi-step conversions between a variety of + time coordinate systems to be assembled out of a set of building + blocks. + + For details of the individual coordinate conversions available, + see the description of the astTimeAdd function. + } + \sstconstructor{ + \htmlref{astTimeMap}{astTimeMap} (also see astTimeAdd) + } + \sstdiytopic{ + Inheritance + }{ + The TimeMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The TimeMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + In addition to those functions applicable to all Mappings, the + following function may also be applied to all TimeMaps: + + \sstitemlist{ + + \sstitem + \htmlref{astTimeAdd}{astTimeAdd}: Add a time coordinate conversion to an TimeMap + } + } +} +\sstroutine{ + TranMap +}{ + Mapping with specified forward and inverse transformations +}{ + \sstdescription{ + A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of + a supplied Mapping with the inverse transformation of another + supplied Mapping, ignoring the un-used transformation in each + Mapping (indeed the un-used transformation need not exist). + + When the forward transformation of the TranMap is referred to, the + transformation actually used is the forward transformation of the + first Mapping supplied when the TranMap was constructed. Likewise, + when the inverse transformation of the TranMap is referred to, the + transformation actually used is the inverse transformation of the + second Mapping supplied when the TranMap was constructed. + } + \sstconstructor{ + \htmlref{astTranMap}{astTranMap} + } + \sstdiytopic{ + Inheritance + }{ + The TranMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The TranMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The TranMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + UnitMap +}{ + Unit (null) Mapping +}{ + \sstdescription{ + A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the + coordinates supplied to it. They are simply copied. This can be + useful if a Mapping is required (e.g. to pass to another + function) but you do not want it to have any effect. + The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and + are specified when it is created. + } + \sstconstructor{ + \htmlref{astUnitMap}{astUnitMap} + } + \sstdiytopic{ + Inheritance + }{ + The UnitMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The UnitMap class does not define any new attributes beyond + those which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The UnitMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + UnitNormMap +}{ + Convert a vector to a unit vector and its norm, relative to a specified centre +}{ + \sstdescription{ + The forward transformation of a UnitNormMap subtracts the specified centre + and then transforms the resulting vector to a unit vector and the vector norm. + The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs + are in the same order as the input; the final output is the norm. + + The inverse transformation of a UnitNormMap multiplies each component + of the provided vector by the provided norm and adds the specified centre. + The output contains one fewer coordinate than the input: the initial Nin inputs + are in the same order as the output; the final input is the norm. + + UnitNormMap enables radially symmetric transformations, as follows: + \sstitemlist{ + + \sstitem + apply a UnitNormMap to produce a unit vector and norm (radius) + + \sstitem + apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged + + \sstitem + apply the same UnitNormMap in the inverse direction to produce the result + } + } + \sstconstructor{ + \htmlref{astUnitNormMap}{astUnitNormMap} + } + \sstdiytopic{ + Inheritance + }{ + The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class. + } + \sstdiytopic{ + Attributes + }{ + The UnitNormMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The UnitNormMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + WcsMap +}{ + Implement a FITS-WCS sky projection +}{ + \sstdescription{ + This class is used to represent sky coordinate projections as + described in the FITS world coordinate system (FITS-WCS) paper II + \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"} by M. Calabretta + and E.W. Griesen. This paper defines a set of functions, or sky + projections, which transform longitude-latitude pairs representing + spherical celestial coordinates into corresponding pairs of Cartesian + coordinates (and vice versa). + + A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these + sky projections and applies them to a specified pair of coordinates. + All the projections in the FITS-WCS paper are supported, plus the now + deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which + is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, + the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection + plane\texttt{"} coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} . + These coordinates may, optionally, be embedded in a space with more + than two dimensions, the remaining coordinates being copied unchanged. + Note, however, that for consistency with other AST facilities, a + WcsMap handles coordinates that represent angles in radians (rather + than the degrees used by FITS-WCS). + + The type of FITS-WCS projection to be used and the coordinates + (axes) to which it applies are specified when a WcsMap is first + created. The projection type may subsequently be determined + using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts + may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. + + Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be + associated with each axis. These specify the precise form of the + projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is + the integer axis index (starting at 1), and m is an integer + \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection + parameters required by each projection, and their meanings, are + dependent upon the projection type (most projections either do not + use any projection parameters, or use parameters 1 and 2 associated + with the latitude axis). Before creating a WcsMap you should consult + the FITS-WCS paper for details of which projection parameters are + required, and which have defaults. When creating the WcsMap, you must + explicitly set values for all those required projection parameters + which do not have defaults defined in this paper. + } + \sstconstructor{ + \htmlref{astWcsMap}{astWcsMap} + } + \sstdiytopic{ + Inheritance + }{ + The WcsMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + WcsMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection + + \sstitem + \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection + + \sstitem + \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters + + \sstitem + PVMax: Maximum number of FITS-WCS projection parameters + + \sstitem + \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes + + \sstitem + \htmlref{WcsType}{WcsType}: FITS-WCS projection type + } + } + \sstdiytopic{ + Functions + }{ + The WcsMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + WinMap +}{ + Map one window on to another by scaling and shifting each axis +}{ + \sstdescription{ + A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular + window in one coordinate system into a similar window in another + coordinate system by scaling and shifting each axis (the window + edges being parallel to the coordinate axes). + + A WinMap is specified by giving the coordinates of two opposite + corners (A and B) of the window in both the input and output + coordinate systems. + } + \sstconstructor{ + \htmlref{astWinMap}{astWinMap} + } + \sstdiytopic{ + Inheritance + }{ + The WinMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + The WinMap class does not define any new attributes beyond those + which are applicable to all Mappings. + } + \sstdiytopic{ + Functions + }{ + The WinMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + XmlChan +}{ + I/O Channel using XML to represent Objects +}{ + \sstdescription{ + A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O + operations. Writing an \htmlref{Object}{Object} to an XmlChan (using + \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an + XML description of that Object, and reading from an XmlChan will + create a new Object from its XML description. + + Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} + and \texttt{"} sink\texttt{"} functions which connect it to an external data store + by reading and writing the resulting XML text. These functions + should perform any conversions needed between external character + encodings and the internal ASCII encoding. If no such functions + are supplied, a Channel will read from standard input and write + to standard output. + + Alternatively, an XmlChan can be told to read or write from + specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, + in which case no sink or source function need be supplied. + } + \sstconstructor{ + \htmlref{astXmlChan}{astXmlChan} + } + \sstdiytopic{ + Inheritance + }{ + The XmlChan class inherits from the Channel class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Channels, every + XmlChan also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML + + \sstitem + \htmlref{XmlLength}{XmlLength}: Controls output buffer length + + \sstitem + \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing + } + } + \sstdiytopic{ + Functions + }{ + The XmlChan class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\sstroutine{ + ZoomMap +}{ + Zoom coordinates about the origin +}{ + \sstdescription{ + The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"} + transformation by multiplying all coordinate values by the same + scale factor (the inverse transformation is performed by + dividing by this scale factor). The number of coordinate values + representing each point is unchanged. + } + \sstconstructor{ + \htmlref{astZoomMap}{astZoomMap} + } + \sstdiytopic{ + Inheritance + }{ + The ZoomMap class inherits from the Mapping class. + } + \sstdiytopic{ + Attributes + }{ + In addition to those attributes common to all Mappings, every + ZoomMap also has the following attributes: + + \sstitemlist{ + + \sstitem + \htmlref{Zoom}{Zoom}: ZoomMap scale factor + } + } + \sstdiytopic{ + Functions + }{ + The ZoomMap class does not define any new functions beyond those + which are applicable to all Mappings. + } +} +\normalsize + +\cleardoublepage +\section{\label{ss:commanddescriptions}UNIX Command Descriptions} +The commands described here are provided for use from the UNIX shell +to assist with developing software which uses AST. To use these +commands, you should ensure that the directory +``/star/bin''\footnote{Or the equivalent directory if AST is installed +in a non-standard location.} is on your PATH. +\small +\sstroutine{ + ast\_link +}{ + Link a program with the AST library +}{ + \sstdescription{ + This command should be used when building programs which use the AST + library, in order to generate the correct arguments to allow the compiler + to link your program. The arguments generated are written to standard + output but may be substituted into the compiler command line in the + standard UNIX way using backward quotes (see below). + + By default, it is assumed that you are building a stand-alone program + which does not produce graphical output. However, switches are provided + for linking other types of program. + } + \sstinvocation{ + cc program.c -L/star/lib `ast\_link [switches]` -o program + } + \sstexamples{ + \sstexamplesubsection{ + cc display.c -L/star/lib `ast\_link -pgplot` -o display + }{ + Compiles and links a C program called ``display\texttt{'} \texttt{'} which uses + the standard version of PGPLOT for graphical output. + } + \sstexamplesubsection{ + cc plotit.c -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit + }{ + Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'} + switch indicates that graphical output will be delivered through + a graphical interface which you have implemented yourself, which + corresponds to the interface required by the current version of AST. + Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library + reference. + } + \sstexamplesubsection{ + cc plotit.c -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit + }{ + Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'} + switch indicates that graphical output will be delivered through + a graphical interface which you have implemented yourself, which + corresponds to the interface required by version 2.0 of AST. + Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library + reference. + } + } + \sstdiytopic{ + Switches + }{ + The following switches may optionally be given to this command to + modify its behaviour: + + \sstitemlist{ + + \sstitem + ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. + + \sstitem + ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. + + \sstitem + ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages + produced by the AST library are delivered via the Starlink EMS (Error + Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default, + error messages are simply written to standard error. + + \sstitem + ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages + produced by the AST library are delivered via the DRAMA Ers (Error + Reporting Service) library. By default, error messages are simply + written to standard error. + + \sstitem + ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which + 2D graphics system is used to display output from the AST library. You + should use this option only if you have implemented an interface to a + new graphics system yourself and wish to provide your own arguments for + linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in + that it assumes that your graphics module implements the complete + interface required by the current version of AST. If future versions of + AST introduce new functions to the graphics interface, this switch will + cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you + that you need to implement new functions in your graphics module. To + avoid such errors, you can use one of the other, version-specific, + switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time + errors to be reported if any AST function is invoked which requires + facilities not in the implemented interface. + + \sstitem + ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. + It indicates that you want to link with your own graphics module + which implements the 2D graphics interface required by V2.0 of AST. + + \sstitem + ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own + graphics module which implements the 2D graphics interface required by + V3.2 of AST. + + \sstitem + ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own + graphics module which implements the 2D graphics interface required by + V5.6 of AST. + + \sstitem + ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how + error messages produced by the AST library should be delivered. You + should use this option only if you have implemented an interface to a + new error delivery system yourself and wish to provide your own + arguments for linking with it. + + \sstitem + ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, + but is retained in order to allow applications to be linked with a + graphics module which implements the 2D interface used by AST V2.0. It + is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. + + \sstitem + ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D + graphical output from the AST library is displayed via the + Starlink version of the PGPLOT graphics package (which uses GKS + for its output). By default, no 2D graphics package is linked and + this will result in an error at run time if AST routines are + invoked that attempt to generate graphical output. + + \sstitem + ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D + graphical output from the AST library is displayed via + the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics + package. By default, no 2D graphics package is linked and this will + result in an error at run time if AST routines are invoked that + attempt to generate graphical output. + + \sstitem + ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which + 3D graphics system is used to display output from the AST library. You + should use this option only if you have implemented an interface to a + new 3D graphics system yourself and wish to provide your own arguments + for linking with it. + + \sstitem + ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D + graphical output from the AST library is displayed via the + Starlink version of the PGPLOT graphics package (which uses GKS + for its output). By default, no 3D graphics package is linked and + this will result in an error at run time if AST routines are + invoked that attempt to generate graphical output. + + \sstitem + ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D + graphical output from the AST library is displayed via + the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics + package. By default, no 3D graphics package is linked and this will + result in an error at run time if AST routines are invoked that + attempt to generate graphical output. + } + } + \sstdiytopic{ + ERFA \& PAL + }{ + The AST distribution includes bundled copies of the ERFA and PAL + libraries. These will be used for fundamental positional astronomy + calculations unless the \texttt{"} --with-external\_pal\texttt{"} option was used when + AST was configured. If \texttt{"} --with-external\_pal\texttt{"} is used, this script + will include \texttt{"} -lpal\texttt{"} in the returned list of linking options, and + the user should then ensure that external copies of the PAL and + ERFA libraries are available (ERFA functions are used within PAL). + } +} +\sstroutine{ + ast\_link\_adam +}{ + Link an ADAM program with the AST library +}{ + \sstdescription{ + This command should only be used when building Starlink ADAM programs + which use the AST library, in order to generate the correct arguments + to allow the ADAM ``alink\texttt{'} \texttt{'} command to link the program. The arguments + generated are written to standard output but may be substituted into + the ``alink\texttt{'} \texttt{'} command line in the standard UNIX way using backward + quotes (see below). + + By default, it is assumed that you are building an ADAM program which + does not produce graphical output. However, switches are provided for + linking other types of program. This command should not be used when + building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'} command + instead. + } + \sstinvocation{ + alink program.o -L/star/lib `ast\_link\_adam [switches]` + } + \sstexamples{ + \sstexamplesubsection{ + alink display.o -L/star/lib `ast\_link\_adam -pgplot` + }{ + Links an ADAM program ``display\texttt{'} \texttt{'} which uses the standard + version of PGPLOT for graphical output. + } + \sstexamplesubsection{ + alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf` -lgrf + }{ + Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\texttt{'} \texttt{'} + switch indicates that graphical output will be delivered through + a graphical interface which you have implemented yourself, which + corresponds to the interface required by the current version of AST. + Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library + reference. + } + \sstexamplesubsection{ + alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf + }{ + Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\_v2.0\texttt{'} \texttt{'} + switch indicates that graphical output will be delivered through + a graphical interface which you have implemented yourself, which + corresponds to the interface required by version 2.0 of AST. Here, + this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library + reference. + } + } + \sstdiytopic{ + Switches + }{ + The following switches may optionally be given to this command to + modify its behaviour: + + \sstitemlist{ + + \sstitem + ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. + + \sstitem + ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. + + \sstitem + ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which + 2D graphics system is used to display output from the AST library. You + should use this option only if you have implemented an interface to a + new graphics system yourself and wish to provide your own arguments for + linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in + that it assumes that your graphics module implements the complete + interface required by the current version of AST. If future versions of + AST introduce new functions to the graphics interface, this switch will + cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you + that you need to implement new functions in your graphics module. To + avoid such errors, you can use one of the other, version-specific, + switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time + errors to be reported if any AST function is invoked which requires + facilities not in the implemented interface. + + \sstitem + ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. + It indicates that you want to link with your own graphics module which + implements the 2D graphics interface required by V2.0 of AST. + + \sstitem + ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics + module which implements the 2D graphics interface required by V3.2 of AST. + + \sstitem + ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics + module which implements the 2D graphics interface required by V5.6 of AST. + + \sstitem + ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how + error messages produced by the AST library should be delivered. You + should use this option only if you have implemented an interface to a + new error delivery system yourself and wish to provide your own + arguments for linking with it. By default, error messages are delivered + in the standard ADAM way via the EMS Error Message Service (Starlink + \htmlref{System}{System} Note SSN/4). + + \sstitem + ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, + but is retained in order to allow applications to be linked with a + graphics module which implements the interface used by AST V2.0. It is + equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. + + \sstitem + ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D + graphical output from the AST library is displayed via the + Starlink version of the PGPLOT graphics package (which uses GKS + for its output). By default, no graphics package is linked and + this will result in an error at run time if AST routines are + invoked that attempt to generate graphical output. + + \sstitem + ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D + graphical output from the AST library is displayed via the + standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics + package. By default, no graphics package is linked and this will + result in an error at run time if AST routines are invoked that + attempt to generate graphical output. + + \sstitem + ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which + 3D graphics system is used to display output from the AST library. You + should use this option only if you have implemented an interface to a + new 3D graphics system yourself and wish to provide your own arguments + for linking with it. + + \sstitem + ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D + graphical output from the AST library is displayed via the + Starlink version of the PGPLOT graphics package (which uses GKS + for its output). By default, no 3D graphics package is linked and + this will result in an error at run time if AST routines are + invoked that attempt to generate graphical output. + + \sstitem + ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D + graphical output from the AST library is displayed via + the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics + package. By default, no 3D graphics package is linked and this will + result in an error at run time if AST routines are invoked that + attempt to generate graphical output. + } + } + \sstdiytopic{ + SLALIB + }{ + The AST distribution includes a cut down subset of the C version of + the SLALIB library written by Pat Wallace. This subset contains only + the functions needed by the AST library. It is built as part of the + process of building AST and is distributed under GPL (and is thus + compatible with the AST license). Previous version of this script + allowed AST applications to be linked against external SLALIB + libraries (either Fortran or C) rather than the internal version. + The current version of this script does not provide this option, + and always uses the internal SLALIB library. However, for backward + compatibility, this script still allows the \texttt{"} -fsla\texttt{"} and \texttt{"} -csla\texttt{"} flags + (previously used for selecting which version of SLALIB to use) to be + specified, but they will be ignored. + } +} +\normalsize + +\cleardoublepage +\section{\label{ss:memoryfunctions}AST Memory Management and Utility Functions} +AST provides a memory management layer that can be used in place of +system functions such as \texttt{malloc}, \texttt{free}, \texttt{realloc}, +\emph{etc.} The AST replacements for these functions ( \texttt{\htmlref{astMalloc}{astMalloc}}, +\texttt{\htmlref{astFree}{astFree}} and \texttt{\htmlref{astRealloc}{astRealloc}}) add extra information to each +allocated memory block that allows AST to check the validity of supplied +pointers. For example, this extra information allows \texttt{astFree} to +detect if the supplied pointer has already been freed, and if so to issue +an appropriate error message. The existence of this extra information is +invisible to outside callers, and stored in a header block located just +before the returned memory block. + +In addition to the standard functions, AST provides other memory management +functions, such as: + +\begin{description} +\item [\texttt{\htmlref{astStore}{astStore}}] - stores data in dynamically allocated memory, allocating +the memory (or adjusting the size of previously allocated memory) to match +the amount of data to be stored. +\item [\texttt{\htmlref{astGrow}{astGrow}}] - allocates and expands memory to hold an adjustable-sized array. +\item [\texttt{\htmlref{astAppendString}{astAppendString}}] - allocates and expands memory to hold a +concatenated string. +\end{description} + +Theses are just a few of the available utilities functions in the AST +memory management layer. Prototypes for all AST memory management +functions are included in the header file ``\texttt{ast.h}''. + +An important restriction on these functions is that pointers created by +other memory management functions, such as the system version of \texttt{malloc} \emph{etc.}, should never supplied to an AST memory management +function. Only pointers created by AST should be used by these functions. + +In addition to memory management functions, AST provides various other +utility functions, such as a basic regular expression facility, and other +string manipulation functions. These are also documented in this appendix. + +The AST memory management layer is implemented on top of the usual \texttt{malloc}, {tt free} and \texttt{realloc} functions. By default these will be +the standard functions provided by <stdlib.h>. However, the facilities of +the STARMEM package (included in the Starlink Software Collection) can be +used to specify alternative functions to use. This requires that AST be +configured using the ``--with-starmem'' option when it is built. + +The STARMEM package provides a wrapper for the standard malloc +implementation that enables the user to switch malloc schemes at runtime +by setting the STARMEM\_MALLOC environment variable. Currently allowed +values for this variable are: + +\begin{description} +\item [SYSTEM] - standard system malloc/free - the default +\item [DL] - Doug Lea's malloc/free +\item [GC] - Hans-Boehm Garbage Collection +\end{description} + +\small +\sstroutine{ + astAppendString +}{ + Append a string to another string which grows dynamically +}{ + \sstdescription{ + This function appends one string to another dynamically + allocated string, extending the dynamic string as necessary to + accommodate the new characters (plus the final null). + } + \sstsynopsis{ + char $*$astAppendString( char $*$str1, int $*$nc, const char $*$str2 ) + } + \sstparameters{ + \sstsubsection{ + str1 + }{ + Pointer to the null-terminated dynamic string, whose memory + has been allocated using an AST memory allocation function. + If no space has yet been allocated for this string, a NULL + pointer may be given and fresh space will be allocated by this + function. + } + \sstsubsection{ + nc + }{ + Pointer to an integer containing the number of characters in + the dynamic string (excluding the final null). This is used + to save repeated searching of this string to determine its + length and it defines the point where the new string will be + appended. Its value is updated by this function to include + the extra characters appended. + + If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will + be ignored and zero will be used. + } + \sstsubsection{ + str2 + }{ + Pointer to a constant null-terminated string, a copy of which + is to be appended to \texttt{"} str1\texttt{"} . + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAppendString() + }{ + A possibly new pointer to the dynamic string with the new string + appended (its location in memory may have to change if it has to + be extended, in which case the original memory is automatically + freed by this function). When the string is no longer required, + its memory should be freed using \htmlref{astFree}{astFree}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If this function is invoked with the global error status set + or if it should fail for any reason, then the returned pointer + will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be + unchanged. + } + } +} +\sstroutine{ + astAppendStringf +}{ + Append a string to another string, allowing printf format specifiers +}{ + \sstdescription{ + This function appends one string to another dynamically + allocated string, extending the dynamic string as necessary to + accommodate the new characters (plus the final null). It is the + same as \htmlref{astAppendString}{astAppendString}, except that the \texttt{"} str2\texttt{"} string ay include + printf format specifiers. + } + \sstsynopsis{ + char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... ) + } + \sstparameters{ + \sstsubsection{ + str1 + }{ + Pointer to the null-terminated dynamic string, whose memory + has been allocated using an AST memory allocation function. + If no space has yet been allocated for this string, a NULL + pointer may be given and fresh space will be allocated by this + function. + } + \sstsubsection{ + nc + }{ + Pointer to an integer containing the number of characters in + the dynamic string (excluding the final null). This is used + to save repeated searching of this string to determine its + length and it defines the point where the new string will be + appended. Its value is updated by this function to include + the extra characters appended. + + If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will + be ignored and zero will be used. + } + \sstsubsection{ + str2 + }{ + Pointer to a constant null-terminated string, a copy of which + is to be appended to \texttt{"} str1\texttt{"} . It may contain format + specifications such as used with the C \texttt{"} printf\texttt{"} family of + functions. + } + \sstsubsection{ + ... + }{ + Additional optional arguments (as used by e.g. \texttt{"} printf\texttt{"} ) + which specify values which are to be substituted into the \texttt{"} str2\texttt{"} + string in place of any format specifications. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astAppendString() + }{ + A possibly new pointer to the dynamic string with the new string + appended (its location in memory may have to change if it has to + be extended, in which case the original memory is automatically + freed by this function). When the string is no longer required, + its memory should be freed using \htmlref{astFree}{astFree}. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If this function is invoked with the global error status set + or if it should fail for any reason, then the returned pointer + will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be + unchanged. + } + } +} +\sstroutine{ + astCalloc +}{ + Allocate and initialise memory +}{ + \sstdescription{ + This function allocates memory in a similar manner to the + standard C \texttt{"} calloc\texttt{"} function, but with improved security + (against memory leaks, etc.) and with error reporting. It also + fills the allocated memory with zeros. + + Like \htmlref{astMalloc}{astMalloc}, it allows zero-sized memory allocation + (without error), resulting in a NULL returned pointer value. + } + \sstsynopsis{ + void $*$astCalloc( size\_t nmemb, size\_t size ) + } + \sstparameters{ + \sstsubsection{ + nmemb + }{ + The number of array elements for which memory is to be allocated. + } + \sstsubsection{ + size + }{ + The size of each array element, in bytes. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astCalloc() + }{ + If successful, the function returns a pointer to the start of + the allocated memory region. If the size allocated is zero, this + will be a NULL pointer. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A pointer value of NULL is returned if this function is + invoked with the global error status set or if it fails for any + reason. + } + } +} +\sstroutine{ + astChr2Double +}{ + read a double value from a string +}{ + \sstdescription{ + This function reads a double from the supplied null-terminated string, + ignoring leading and trailing white space. AST\_\_BAD is ereturned + without error if the string is not a numerical value. + } + \sstsynopsis{ + double astChr2Double( const char $*$str ) + } + \sstparameters{ + \sstsubsection{ + str + }{ + Pointer to the string. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChr2Double() + }{ + The double value, or AST\_\_BAD. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of AST\_\_BAD is returned if this function is invoked with + the global error status set or if it should fail for any reason. + } + } +} +\sstroutine{ + astChrCase +}{ + Convert a string to upper or lower case +}{ + \sstdescription{ + This function converts a supplied string to upper or lower case, + storing the result in a supplied buffer. The \htmlref{astStringCase}{astStringCase} function + is similar, but stores the result in a dynamically allocated buffer. + } + \sstsynopsis{ + void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status ) + } + \sstparameters{ + \sstsubsection{ + in + }{ + Pointer to the null terminated string to be converted. If this + is NULL, the supplied contents of the \texttt{"} out\texttt{"} string are used as + the input string. + } + \sstsubsection{ + out + }{ + Pointer to the buffer to receive the converted string. The + length of this buffer is given by \texttt{"} blen\texttt{"} . If NULL is supplied + for \texttt{"} in\texttt{"} , then the supplied contents of \texttt{"} out\texttt{"} are converted and + written back into \texttt{"} out\texttt{"} over-writing the supplied contents. + } + \sstsubsection{ + upper + }{ + If non-zero, the string is converted to upper case. Otherwise it + is converted to lower case. + } + \sstsubsection{ + blen + }{ + The length of the output buffer. Ignored if \texttt{"} in\texttt{"} is NULL. No + more than \texttt{"} blen - 1\texttt{"} characters will be copied from \texttt{"} in\texttt{"} to + \texttt{"} out\texttt{"} , and a terminating null character will then be added. + } + } +} +\sstroutine{ + astChrLen +}{ + Determine the used length of a string +}{ + \sstdescription{ + This function returns the used length of a string. This excludes any + trailing white space or non-printable characters (such as the + trailing null character). + } + \sstsynopsis{ + size\_t astChrLen( const char $*$string ) + } + \sstparameters{ + \sstsubsection{ + string + }{ + Pointer to the string. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrLen() + }{ + The number of characters in the supplied string, not including the + trailing newline, and any trailing white-spaces or non-printable + characters. + } + } +} +\sstroutine{ + astChrMatch +}{ + Case insensitive string comparison +}{ + \sstdescription{ + This function compares two null terminated strings for equality, + discounting differences in case and any trailing white space in either + string. + } + \sstsynopsis{ + int astChrMatch( const char $*$str1, const char $*$str2 ) + } + \sstparameters{ + \sstsubsection{ + str1 + }{ + Pointer to the first string. + } + \sstsubsection{ + str2 + }{ + Pointer to the second string. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrMatch() + }{ + Non-zero if the two strings match, otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero is returned if this function is invoked with the + global error status set or if it should fail for any reason. + } + } +} +\sstroutine{ + astChrMatchN +}{ + Case insensitive string comparison of at most N characters +}{ + \sstdescription{ + This function compares two null terminated strings for equality, + discounting differences in case and any trailing white space in either + string. No more than \texttt{"} n\texttt{"} characters are compared. + } + \sstsynopsis{ + int astChrMatchN( const char $*$str1, const char $*$str2, size\_t n ) + } + \sstparameters{ + \sstsubsection{ + str1 + }{ + Pointer to the first string. + } + \sstsubsection{ + str2 + }{ + Pointer to the second string. + } + \sstsubsection{ + n + }{ + Maximum number of characters to compare. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrMatchN() + }{ + Non-zero if the two strings match, otherwise zero. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero is returned if this function is invoked with the + global error status set or if it should fail for any reason. + } + } +} +\sstroutine{ + astChrSplit +}{ + Extract words from a supplied string +}{ + \sstdescription{ + This function extracts all space-separated words form the supplied + string and returns them in an array of dynamically allocated strings. + } + \sstsynopsis{ + char $*$$*$astChrSplit\_( const char $*$str, int $*$n ) + } + \sstparameters{ + \sstsubsection{ + str + }{ + Pointer to the string to be split. + } + \sstsubsection{ + n + }{ + Address of an int in which to return the number of words returned. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrSplit() + }{ + A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. + Each element is a pointer to a dynamically allocated character + string containing a word extracted from the supplied string. Each + of these words will have no leading or trailing white space. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A NULL pointer is returned if this function is invoked with the + global error status set or if it should fail for any reason, or if + the supplied string contains no words. + } + } +} +\sstroutine{ + astChrSplitC +}{ + Split a string using a specified character delimiter +}{ + \sstdescription{ + This function extracts all sub-strings separated by a given + character from the supplied string and returns them in an array + of dynamically allocated strings. The delimiter character itself + is not included in the returned strings. + + Delimiter characters that are preceded by \texttt{"} $\backslash$\texttt{"} are not used as + delimiters but are included in the returned word instead (without + the \texttt{"} $\backslash$\texttt{"} ). + } + \sstsynopsis{ + char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n ) + } + \sstparameters{ + \sstsubsection{ + str + }{ + Pointer to the string to be split. + } + \sstsubsection{ + c + }{ + The delimiter character. + } + \sstsubsection{ + n + }{ + Address of an int in which to return the number of words returned. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrSplitC() + }{ + A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. + Each element is a pointer to a dynamically allocated character + string containing a word extracted from the supplied string. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A NULL pointer is returned if this function is invoked with the + global error status set or if it should fail for any reason, or if + the supplied string contains no words. + } + } +} +\sstroutine{ + astChrSplitRE +}{ + Extract sub-strings matching a specified regular expression +}{ + \sstdescription{ + This function compares the supplied string with the supplied + regular expression. If they match, each section of the test string + that corresponds to a parenthesised sub-string in the regular + expression is copied and stored in the returned array. + } + \sstsynopsis{ + char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n, + const char $*$$*$matchend ) + } + \sstparameters{ + \sstsubsection{ + str + }{ + Pointer to the string to be split. + } + \sstsubsection{ + regexp + }{ + The regular expression. See \texttt{"} Template Syntax:\texttt{"} in the \htmlref{astChrSub}{astChrSub} + prologue. Note, this function differs from astChrSub in that any + equals signs (=) in the regular expression are treated literally. + } + \sstsubsection{ + n + }{ + Address of an int in which to return the number of sub-strings + returned. + } + \sstsubsection{ + matchend + }{ + A pointer to a location at which to return a pointer to the + character that follows the last character within the supplied test + string that matched any parenthesises sub-section of \texttt{"} regexp\texttt{"} . A + NULL pointer is returned if no matches were found. A NULL pointer + may be supplied if the location of the last matching character is + not needed. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrSplitRE() + }{ + A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. + Each element is a pointer to a dynamically allocated character + string containing a sub-string extracted from the supplied string. + The array itself, and the strings within it, should all be freed + using \htmlref{astFree}{astFree} when no longer needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If a parenthesised sub-string in the regular expression is matched + by more than one sub-string within the test string, then only the + first is returned. To return multiple matches, the regular + expression should include multiple copies of the parenthesised + sub-string (for instance, separated by \texttt{"} .$+$?\texttt{"} if the intervening + string is immaterial). + + \sstitem + A NULL pointer is returned if this function is invoked with the + global error status set or if it should fail for any reason, or if + the supplied string contains no words. + } + } +} +\sstroutine{ + astChrSub +}{ + Performs substitutions on a supplied string +}{ + \sstdescription{ + This function checks a supplied test string to see if it matches a + supplied template. If it does, specified sub-sections of the test + string may optionally be replaced by supplied substitution strings. + The resulting string is returned. + } + \sstsynopsis{ + char $*$astChrSub( const char $*$test, const char $*$pattern, + const char $*$subs[], int nsub ) + } + \sstparameters{ + \sstsubsection{ + test + }{ + The string to be tested. + } + \sstsubsection{ + pattern + }{ + The template string. See \texttt{"} Template Syntax:\texttt{"} below. + } + \sstsubsection{ + subs + }{ + An array of strings that are to replace the sections of the test + string that match each parenthesised sub-string in \texttt{"} pattern\texttt{"} . The + first element of \texttt{"} subs\texttt{"} replaces the part of the test string that + matches the first parenthesised sub-string in the template, etc. + + If \texttt{"} nsub\texttt{"} is zero, then the \texttt{"} subs\texttt{"} pointer is ignored. In this + case, substitution strings may be specified by appended them to + the end of the \texttt{"} pattern\texttt{"} string, separated by \texttt{"} =\texttt{"} characters. + Note, if you need to include a literal \texttt{"} =\texttt{"} character in the + pattern, precede it by an escape \texttt{"} $\backslash$\texttt{"} character. + } + \sstsubsection{ + nsub + }{ + The number of substitution strings supplied in array \texttt{"} subs\texttt{"} . + } + } + \sstreturnedvalue{ + \sstsubsection{ + astChrSub() + }{ + A pointer to a dynamically allocated string holding the result + of the substitutions, or NULL if the test string does not match + the template string. This string should be freed using \htmlref{astFree}{astFree} + when no longer needed. If no substituions are specified then a + copy of the test string is returned if it matches the template. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A NULL pointer is returned if this function is invoked with the + global error status set or if it should fail for any reason, or if + the supplied test string does not match the template. + } + } + \sstdiytopic{ + Template Syntax + }{ + The template syntax is a minimal form of regular expression, The + quantifiers allowed are \texttt{"} $*$\texttt{"} , \texttt{"} ?\texttt{"} , \texttt{"} $+$\texttt{"} , \texttt{"} \{n\}\texttt{"} , \texttt{"} $*$?\texttt{"} and \texttt{"} $+$?\texttt{"} (the + last two are non-greedy - they match the minimum length possible + that still gives an overall match to the template). The only + constraints allowed are \texttt{"} $\wedge$\texttt{"} and \texttt{"} \$\texttt{"} . The following atoms are allowed: + + \sstitemlist{ + + \sstitem + [chars]: Matches any of the specified characters. + + \sstitem + [$\wedge$chars]: Matches anything but the specified characters. + + \sstitem + .: Matches any single character. + + \sstitem + x: Matches the character x so long as x has no other significance. + + \sstitem + $\backslash$x: Always matches the character x (except for [dDsSwW]). + + \sstitem + $\backslash$d: Matches a single digit. + + \sstitem + $\backslash$D: Matches anything but a single digit. + + \sstitem + $\backslash$w: Matches any alphanumeric character, and \texttt{"} \_\texttt{"} . + + \sstitem + $\backslash$W: Matches anything but alphanumeric characters, and \texttt{"} \_\texttt{"} . + + \sstitem + $\backslash$s: Matches white space. + + \sstitem + $\backslash$S: Matches anything but white space. + + } + Note, minus signs (\texttt{"} -\texttt{"} ) within brackets have no special significance, + so ranges of characters must be specified explicitly. + + Multiple template strings can be concatenated, using the \texttt{"} $|$\texttt{"} + character to separate them. The test string is compared against + each one in turn until a match is found. + + Parentheses are used within each template to identify sub-strings + that are to be replaced by the strings supplied in \texttt{"} sub\texttt{"} . + + If \texttt{"} nsub\texttt{"} is supplied as zero, then substitution strings may be + specified by appended them to the end of the \texttt{"} pattern\texttt{"} string, + separated by \texttt{"} =\texttt{"} characters. If \texttt{"} nsub\texttt{"} is not zero, then any + substitution strings appended to the end of \texttt{"} pattern\texttt{"} are ignored. + + Each element of \texttt{"} subs\texttt{"} + may contain a reference to a token of the + form \texttt{"} \$1\texttt{"} , \texttt{"} \$2\texttt{"} , etc. The \texttt{"} \$1\texttt{"} token will be replaced by the part + of the test string that matched the first parenthesised sub-string + in \texttt{"} pattern\texttt{"} . The \texttt{"} \$2\texttt{"} token will be replaced by the part of the + test string that matched the second parenthesised sub-string in + \texttt{"} pattern\texttt{"} , etc. + } +} +\sstroutine{ + astChrTrunc +}{ + Terminate a string to exclude trailing spaces +}{ + \sstdescription{ + This function pokes a null character into the supplied string to + remove any trailing spaces. + } + \sstsynopsis{ + void astChrTrunc( char $*$text ) + } + \sstparameters{ + \sstsubsection{ + text + }{ + The string to be truncated. + } + } +} +\sstroutine{ + astFree +}{ + Free previously allocated memory +}{ + \sstdescription{ + This function frees memory that has previouly been dynamically + allocated using one of the AST memory function. + } + \sstsynopsis{ + void $*$astFree( void $*$ptr ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to previously allocated memory. An error will result + if the memory has not previously been allocated by another + function in this module. However, a NULL pointer value is + accepted (without error) as indicating that no memory has yet + been allocated, so that no action is required. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFree() + }{ + Always returns a NULL pointer. + } + } +} +\sstroutine{ + astFreeDouble +}{ + Free previously double allocated memory +}{ + \sstdescription{ + This function frees memory that has previouly been dynamically + allocated using one of the AST memory function. It assumes that + the supplied pointer is a pointer to an array of pointers. Each + of these pointers is first freed, and then the supplied pointer + is freed. + + Note, this routine should not be used with arrays allocated + by \htmlref{astGrow}{astGrow} since astGrow over-allocates and so there may be + non-initialised pointers at the end of the array. + } + \sstsynopsis{ + void $*$astFreeDouble( void $*$ptr ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to previously allocated memory. An error will result + if the memory has not previously been allocated by another + function in this module. However, a NULL pointer value is + accepted (without error) as indicating that no memory has yet + been allocated, so that no action is required. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astFreeDouble() + }{ + Always returns a NULL pointer. + } + } +} +\sstroutine{ + astGrow +}{ + Allocate memory for an adjustable array +}{ + \sstdescription{ + This function allocates memory in which to store an array of + data whose eventual size is unknown. It should be invoked + whenever a new array size is determined and will appropriately + increase the amount of memory allocated when necessary. In + general, it will over-allocate in anticipation of future growth + so that the amount of memory does not need adjusting on every + invocation. + } + \sstsynopsis{ + void $*$astGrow( void $*$ptr, int n, size\_t size ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to previously allocated memory (or NULL if none has + yet been allocated). + } + \sstsubsection{ + n + }{ + Number of array elements to be stored (may be zero). + } + \sstsubsection{ + size + }{ + The size of each array element. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astGrow() + }{ + If the memory was allocated successfully, a pointer to the start + of the possibly new memory region is returned (this may be the + same as the original pointer). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + When new memory is allocated, the existing contents are preserved. + + \sstitem + This function does not free memory once it is allocated, so + the size allocated grows to accommodate the maximum size of the + array (or \texttt{"} high water mark\texttt{"} ). Other memory handling routines may + be used to free the memory (or alter its size) if necessary. + + \sstitem + If this function is invoked with the global error status set, + or if it fails for any reason, the original pointer value is + returned and the memory contents are unchanged. + } + } +} +\sstroutine{ + astIsDynamic +}{ + Returns a flag indicating if memory was allocated dynamically +}{ + \sstdescription{ + This function takes a pointer to a region of memory and tests if + the memory has previously been dynamically allocated using other + functions from this module. It does this by checking for the + presence of a \texttt{"} magic\texttt{"} number in the header which precedes the + allocated memory. If the magic number is not present (or the + pointer is invalid for any other reason), zero is returned. + Otherwise 1 is returned. + } + \sstsynopsis{ + int astIsDynamic\_( const void $*$ptr ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to test. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astIsDynamic() + }{ + Non-zero if the memory was allocated dynamically. Zero is returned + if the supplied pointer is NULL. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero is returned if this function is invoked with + the global error status set, or if it fails for any reason. + } + } +} +\sstroutine{ + astMalloc +}{ + Allocate memory +}{ + \sstdescription{ + This function allocates memory in a similar manner to the + standard C \texttt{"} malloc\texttt{"} function, but with improved security + (against memory leaks, etc.) and with error reporting. It also + allows zero-sized memory allocation (without error), resulting + in a NULL returned pointer value. + } + \sstsynopsis{ + void $*$astMalloc( size\_t size ) + } + \sstparameters{ + \sstsubsection{ + size + }{ + The size of the memory region required (may be zero). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMalloc() + }{ + If successful, the function returns a pointer to the start of + the allocated memory region. If the size allocated is zero, this + will be a NULL pointer. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A pointer value of NULL is returned if this function is + invoked with the global error status set or if it fails for any + reason. + } + } +} +\sstroutine{ + astMemCaching +}{ + Controls whether allocated but unused memory is cached in this module +}{ + \sstdescription{ + This function sets a flag indicating if allocated but unused memory + should be cached or not. It also returns the original value of the + flag. + + If caching is switched on or off as a result of this call, then the + current contents of the cache are discarded. + + Note, each thread has a separate cache. Calling this function + affects only the currently executing thread. + } + \sstsynopsis{ + int astMemCaching( int newval ) + } + \sstparameters{ + \sstsubsection{ + newval + }{ + The new value for the MemoryCaching tuning parameter (see + \htmlref{astTune}{astTune} in objectc.c). If AST\_\_TUNULL is supplied, the current + value is left unchanged. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astMemCaching() + }{ + The original value of the MemoryCaching tuning parameter. + } + } +} +\sstroutine{ + astRealloc +}{ + Change the size of a dynamically allocated region of memory +}{ + \sstdescription{ + This function changes the size of a dynamically allocated region + of memory, preserving its contents up to the minimum of the old + and new sizes. This may involve copying the contents to a new + location, so a new pointer is returned (and the old memory freed + if necessary). + + This function is similar to the standard C \texttt{"} realloc\texttt{"} function + except that it provides better security against programming + errors and also supports the allocation of zero-size memory + regions (indicated by a NULL pointer). + } + \sstsynopsis{ + void $*$astRealloc( void $*$ptr, size\_t size ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to previously allocated memory (or NULL if the + previous size of the allocated memory was zero). + } + \sstsubsection{ + size + }{ + New size required for the memory region. This may be zero, in + which case a NULL pointer is returned (no error results). It + should not be negative. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astRealloc() + }{ + If the memory was reallocated successfully, a pointer to the + start of the new memory region is returned (this may be the same + as the original pointer). If size was given as zero, a NULL + pointer is returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + If this function is invoked with the error status set, or if + it fails for any reason, the original pointer value is returned + and the memory contents are unchanged. Note that this behaviour + differs from that of the standard C \texttt{"} realloc\texttt{"} function which + returns NULL if it fails. + } + } +} +\sstroutine{ + astRemoveLeadingBlanks +}{ + Remove any leading white space from a string +}{ + \sstdescription{ + This function moves characters in the supplied string to the left + in order to remove any leading white space. + } + \sstsynopsis{ + void astRemoveLeadingBlanks( char $*$string ) + } + \sstparameters{ + \sstsubsection{ + string + }{ + Pointer to the string. + } + } +} +\sstroutine{ + astSizeOf +}{ + Determine the size of a dynamically allocated region of memory +}{ + \sstdescription{ + This function returns the size of a region of dynamically + allocated memory. + } + \sstsynopsis{ + size\_t astSizeOf( const void $*$ptr ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to dynamically allocated memory (or NULL if the size + of the allocated memory was zero). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astSizeOf() + }{ + The allocated size. This will be zero if a NULL pointer was + supplied (no error will result). + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A value of zero is returned if this function is invoked with + the global error status set, or if it fails for any reason. + } + } +} +\sstroutine{ + astStore +}{ + Store data in dynamically allocated memory +}{ + \sstdescription{ + This function stores data in dynamically allocated memory, + allocating the memory (or adjusting the size of previously + allocated memory) to match the amount of data to be stored. + } + \sstsynopsis{ + void $*$astStore( void $*$ptr, const void $*$data, size\_t size ) + } + \sstparameters{ + \sstsubsection{ + ptr + }{ + Pointer to previously allocated memory (or NULL if none has + yet been allocated). + } + \sstsubsection{ + data + }{ + Pointer to the start of the data to be stored. This may be + given as NULL if there are no data, in which case it will be + ignored and this function behaves like \htmlref{astRealloc}{astRealloc}, preserving + the existing memory contents. + } + \sstsubsection{ + size + }{ + The total size of the data to be stored and/or the size of + memory to be allocated. This may be zero, in which case the + data parameter is ignored, any previously-allocated memory is + freed and a NULL pointer is returned. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStore() + }{ + If the data were stored successfully, a pointer to the start of + the possibly new memory region is returned (this may be the same + as the original pointer). If size was given as zero, a NULL + pointer is returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + This is a convenience function for use when storing data of + arbitrary size in memory which is to be allocated + dynamically. It is appropriate when the size of the data will + not change frequently because the size of the memory region will + be adjusted to fit the data on every invocation. + + \sstitem + If this function is invoked with the error status set, or if + it fails for any reason, the original pointer value is returned + and the memory contents are unchanged. + } + } +} +\sstroutine{ + astString +}{ + Create a C string from an array of characters +}{ + \sstdescription{ + This function allocates memory to hold a C string and fills the + string with the sequence of characters supplied. It then + terminates the string with a null character and returns a + pointer to its start. The memory used for the string may later + be de-allocated using \htmlref{astFree}{astFree}. + + This function is intended for constructing null terminated C + strings from arrays of characters which are not null terminated, + such as when importing a character argument from a Fortran 77 + program. + } + \sstsynopsis{ + char $*$astString( const char $*$chars, int nchars ) + } + \sstparameters{ + \sstsubsection{ + chars + }{ + Pointer to the array of characters to be used to fill the string. + } + \sstsubsection{ + nchars + }{ + The number of characters in the array (zero or more). + } + } + \sstreturnedvalue{ + \sstsubsection{ + astString() + }{ + If successful, the function returns a pointer to the start of + the allocated string. If the number of characters is zero, a + zero-length string is still allocated and a pointer to it is + returned. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A pointer value of NULL is returned if this function is + invoked with the global error status set or if it fails for any + reason. + } + } +} +\sstroutine{ + astStringArray +}{ + Create an array of C strings from an array of characters +}{ + \sstdescription{ + This function turns an array of fixed-length character data into + a dynamicllay allocated array of null-terminated C strings with + an index array that may be used to access them. + + The array of character data supplied is assumed to hold \texttt{"} nel\texttt{"} + adjacent fixed-length strings (without terminating nulls), each + of length \texttt{"} len\texttt{"} characters. This function allocates memory and + creates a null-terminated copy of each of these strings. It also + creates an array of \texttt{"} nel\texttt{"} pointers which point at the start of + each of these new strings. A pointer to this index array is + returned. + + The memory used is allocated in a single block and should later + be de-allocated using \htmlref{astFree}{astFree}. + } + \sstsynopsis{ + char $*$$*$astStringArray( const char $*$chars, int nel, int len ) + } + \sstparameters{ + \sstsubsection{ + chars + }{ + Pointer to the array of input characters. The number of characters + in this array should be at least equal to (nel $*$ len). + } + \sstsubsection{ + nel + }{ + The number of fixed-length strings in the input character + array. This may be zero but should not be negative. + } + \sstsubsection{ + len + }{ + The number of characters in each fixed-length input + string. This may be zero but should not be negative. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStringArray() + }{ + A pointer to the start of the index array, which contains \texttt{"} nel\texttt{"} + pointers pointing at the start of each null-terminated output + string. + + The returned pointer should be passed to astFree to de-allocate + the memory used when it is no longer required. This will free + both the index array and the memory used by the strings it + points at. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A NULL pointer will also be returned if the value of \texttt{"} nel\texttt{"} is + zero, in which case no memory is allocated. + + \sstitem + A pointer value of NULL will also be returned if this function + is invoked with the global error status set or if it fails for + any reason. + } + } +} +\sstroutine{ + astStringCase +}{ + Convert a string to upper or lower case +}{ + \sstdescription{ + This function converts a supplied string to upper or lower case, + storing the result in dynamically allocated memory. The \htmlref{astChrCase}{astChrCase} + function is similar, but stores the result in a supplied buffer. + } + \sstsynopsis{ + char $*$astStringCase( const char string, int upper ) + } + \sstparameters{ + \sstsubsection{ + string + }{ + Pointer to the null terminated string to be converted. + } + \sstsubsection{ + upper + }{ + If non-zero, the string is converted to upper case. Otherwise it + is converted to lower case. + } + } + \sstreturnedvalue{ + \sstsubsection{ + astStringCase() + }{ + If successful, the function returns a pointer to the start of + the allocated string. The returned memory should be freed using + \htmlref{astFree}{astFree} when no longer needed. + } + } + \sstnotes{ + \sstitemlist{ + + \sstitem + A pointer value of NULL is returned if this function is + invoked with the global error status set or if it fails for any + reason. + } + } +} +\normalsize + +\newpage +\section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage} + +This appendix gives details of the \htmlref{FitsChan}{FitsChan} class +implementation of the conventions described in the FITS-WCS papers +available at +\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are +used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan +has the value ``FITS-WCS'' (whether set explicitly or defaulted). It +should always be possible for a \htmlref{FrameSet}{FrameSet} to be read +(using the +\htmlref{astRead}{astRead} +function) from a FitsChan containing a header which conforms to these +conventions. However, only those FrameSets which are compatible with the +FITS-WCS model can be \emph{written} to a FitsChan using the +\htmlref{astWrite}{astWrite} +function. For instance, if the current \htmlref{Frame}{Frame} of a +FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{MathMap} +then the FrameSet will no longer be compatible with the FITS-WCS model, +and so will not be written out successfully to a FitsChan. + +The following sub-sections describe the details of the implementation of +each of the first four FITS-WCS papers. Here, the term ``pixel axes'' is +used to refer to the FITS pixel coordinates (i.e. the centre of the +first image pixel has a value 1.0 on each pixel axis); the term ``IWC +axes'' is used to refer to the axes of the Intermediate World Coordinate +system; and the term ``WCS axes'' is used to refer to the axes of the final +physical coordinate system described by the CTYPE\emph{i} keywords. + +\subsection{Paper I - General Linear Coordinates} +When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} keyword +values within the FitsChan do not conform to the conventions described in +later papers, in which case the axes are assumed to be linear. When +writing a FrameSet to a FitsChan, these conventions are used for axes +which are described by a simple \htmlref{Frame}{Frame} (\emph{i.e.} not a +\htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}). + +\htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword +defined by FITS-WCS paper I. + +\begin{table}[htbp] +\begin{tabular}{|l|p{2.5in}|p{2.5in}|} +\hline +\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} +& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline + +\fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS +Frame - only written if different to NAXIS.} + +\fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS +\htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference +Point'' below).} + +\fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always +written (see ``Choice of Reference Point'' below).} + +\fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only +written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is +set to zero.} + +\fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only +written in FITS-AIPS and FITS-AIPS++ encodings.} + +\fitskey{CTYPE\emph{ia}}{Used to choose the class and attributes of the +WCS Frame, and to create the pixel to WCS Mapping (note, ``STOKES'' and +``COMPLEX'' axes are treated as unknown linear axes).}{Always written +(see ``Use and Choice of CTYPE keywords'' below).} + +\fitskey{CUNIT\emph{ia}}{Used to set the Units attributes +of the WCS Frame.}{Only written if the Units attribute of the WCS Frame +has been set explicitly. If so, the Units value for each axis is used as +the CUNIT value.} + +\fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS +Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to +zero.} + +\fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS +Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to +a non-zero value.} + +\fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes +are linear.} + +\fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.} + +\fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{Domain} attribute +of the WCS Frame.}{Only written if the Domain attribute of the WCS Frame +has been set explicitly. If so, the Domain value is used as the WCSNAME +value.} + +\fitskey{CRDER\emph{ia}}{Ignored.}{Not used.} + +\fitskey{CSYER\emph{ia}}{Ignored.}{Not used.} + +\hline +\end{tabular} +\vspace{3.mm} +\caption{Use of FITS-WCS Paper I keywords} +\label{tab:fitspaper1} +\end{table} + +\subsubsection{Requirements for a Successful Write Operation} +When writing a \htmlref{FrameSet}{FrameSet} in which the WCS +\htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan}, +success depends on the \htmlref{Mapping}{Mapping} from pixel coordinates +(the base Frame in the FrameSet) to the WCS Frame being linear. The write +operation will fail if this is not the case. + +\subsubsection{Use and Choice of CTYPE\emph{i} keywords} +When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the +Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from +the CNAME\emph{i} keywords, if present in the header. Otherwise they are set +from the CTYPE\emph{i} comments strings in the header, so long as each +axis has a unique non-blank comment. Otherwise, the Label attributes are +set to the CTYPE\emph{i} values. The above procedure is over-ridden if +the axis types conform to the conventions described in paper II or III, +as described below. + +When writing a FrameSet to a FitsChan, each CTYPE\emph{i} value is set to +the value of the Symbol attribute of the corresponding axis in the Frame +being written. If a value has been set explicitly for the axis Label +attribute, it is used as the axis comment (except that any existing +comments in the FitsChan take precedence if the keyword value has not +changed). The above procedure is over-ridden if the Frame is a +\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which +case the CTYPE\emph{i} value is derived from the \htmlref{System}{System} +attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping} +according to the conventions of papers II and III, as described below. + +\subsubsection{Choice of Reference Point} +When writing a \htmlref{FrameSet}{FrameSet} to a +\htmlref{FitsChan}{FitsChan}, the pixel coordinates of the +reference point for linear axes (i.e. the CRPIX\emph{j} values) are +chosen as follows: + +\begin{itemize} +\item If the FrameSet is being written to a FitsChan which previously +contained a set of axis descriptions with the same identifying letter, +then the previous CRVAL\emph{j}values are converted into the coordinate system +of the \htmlref{Frame}{Frame} being written (if possible). These values are then +transformed into the pixel Frame, and the closest integer pixel values +are used as the CRPIX keywords. +\item If the above step could not be performed for any reason, the +central pixel is used as the reference point. This requires the image +dimensions to be present in the FitsChan in the form of a set of +NAXIS\emph{j} keyword values. +\item If both the above two steps failed for any axis, then the pixel +reference position is set to a value of 1.0 on the pixel axis. +\end{itemize} + +The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding +CRVAL\emph{j}values. + +Again, the above procedure is over-ridden if the Frame is a +\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which +case the conventions of papers II and III are used as described below. + + +\subsubsection{Choice of Axis Ordering} +When reading a \htmlref{FrameSet}{FrameSet} from a +\htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current +\htmlref{Frame}{Frame} of the +resulting FrameSet corresponds to axis $i$ in the FITS header. + +When writing a FrameSet to a FitsChan, the axis ordering for the FITS +header is chosen to make the CD\emph{i\_j} or PC\emph{i\_j} matrix +predominately diagonal. This means that the axis numbering in the FITS +header will not necessarily be the same as that in the AST Frame. + +\subsubsection{Alternate Axis Descriptions} +When reading a \htmlref{FrameSet}{FrameSet} from a +\htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions, +each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added +to the final FrameSet, connected via an appropriate +\htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{Ident} attribute of the Frame is set to hold the single alphabetical +character which is used to identify the set of axis descriptions within +the FITS header (a single space is used for the primary axis descriptions). + +When writing a FrameSet to a FitsChan, it is assumed that the base Frame +represents pixel coordinates, and the current Frame represents the +primary axis descriptions. If there are any other Frames present in the +FrameSet, an attempt is made to create a complete set of ``alternate'' +set of keywords describing each additional Frame. The first character in +the Ident attribute of the Frame is used as the single character +descriptor to be appended to the keyword, with the proviso that a given +character can only be used once. If a second Frame is found with an Ident +attribute which has already been used, its Ident attribute is ignored and +the next free character is used instead. Note, failure to write a set of +alternate axis descriptions does not result in failure of the entire +write operation: the primary axis descriptions are still written, +together with any other alternate axis descriptions which can be produced +successfully. + +\subsection{Paper II - Celestial Coordinates} +These conventions are used when reading a \htmlref{FrameSet}{FrameSet} +from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i} +values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} +is a \htmlref{SkyFrame}{SkyFrame}. + +\htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword +whose meaning is defined or extended by FITS-WCS paper II. + +\begin{table}[htbp] +\begin{tabular}{|l|p{2.5in}|p{2.5in}|} +\hline +\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} +& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline + +\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types +listed in paper II are supported (note, ``CUBEFACE'' axes are treated as +unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar +HEALPix) are supported.}{Determined by the \htmlref{System}{System} attribute +of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the +\htmlref{WcsMap}{WcsMap} within the FrameSet.} + +\fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.} + +\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values +are stored as attributes of a WcsMap within this Mapping).}{Values are +obtained from the WcsMap in the pixel to WCS Mapping.} + +\fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also +stored as a \htmlref{PVi\_m}{PVi\_m} attribute for the longitude axis of the WcsMap.}{Only +written if not equal to the default value defined in paper II (see +``Choice of LONPOLE/LATPOLE'' below).} + +\fitskey{LATPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also +stored as a PV attribute for the longitude axis of the WcsMap.}{Only +written if not equal to the default value defined in paper II (see +``Choice of LONPOLE/LATPOLE'' below).} + +\fitskey{RADESYS\emph{a}}{Used to set the attributes of the SkyFrame. All +values supported except that ecliptic coordinates are currently always +assumed to be FK5.}{Always written. Determined by the System attribute of +the SkyFrame.} + +\fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute +of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of +the SkyFrame.} + +\fitskey{EPOCH}{Used to set the Equinox attribute of the SkyFrame.}{Only +written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute +of the SkyFrame.} + +\fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{Epoch} attribute of the +SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on +RADESYS and EQUINOX is used if used if DATE-OBS is not present +either.}{Determined by the Epoch attribute of the SkyFrame. Only written +if this attribute has been set to an explicit value (in which case +DATE-OBS is also written).} + +\hline +\end{tabular} +\vspace{3.mm} +\caption{Use of FITS-WCS Paper II keywords} +\label{tab:fitspaper2} +\end{table} + +\subsubsection{Requirements for a Successful Write Operation} +When writing a \htmlref{FrameSet}{FrameSet} in which the WCS +\htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a +\htmlref{FitsChan}{FitsChan}, success depends on the following conditions +being met: + +\begin{enumerate} +\item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame +in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}. +\item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear. +\item The Mapping after the WcsMap (\emph{i.e.} from native spherical to +celestial coordinates) is a spherical rotation for the +celestial axes, and linear for any other axes. +\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan, +and the longitude and latitude axes are separable. In this case the Mapping will +be described by a pair of 1-dimensional look-up tables, using the ``-TAB'' +algorithm described in FITS-WCS paper III. +\end{enumerate} + +If none of the above conditions hold, the write operation will be +unsuccessful. + +\subsubsection{Choice of LONPOLE/LATPOLE} +When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, +the choice of LONPOLE and LATPOLE values is determined as follows: + +\begin{enumerate} + +\item If the projection represented by the \htmlref{WcsMap}{WcsMap} is +azimuthal, then any values set for attributes ``PV\emph{i}\_3'' +and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis) +within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a +FrameSet from a FITS-WCS header +results in the original LONPOLE and LATPOLE values being stored within a +WcsMap within the FrameSet. Consequently, if a FrameSet is read from a +FITS-WCS header and it is subsequently written out to a new FITS-WCS +header, the original LONPOLE and LATPOLE values will usually be used in +the new header (the exception being if the WcsMap has been explicitly +modified before being written out again). Any extra rotation of the sky +is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is +possible only if the projection is azimuthal). + +\item If the projection represented by the WcsMap is azimuthal but no +values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' +attributes within the WcsMap, then the default LONPOLE and LATPOLE values +are used. This results in no LONPOLE or LATPOLE keywords being stored in +the header since default values are never stored. Any extra rotation of +the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this +is possible only if the projection is azimuthal). + +\item If the projection represented by the WcsMap is not azimuthal, +then the values of LONPOLE and LATPOLE are found by transforming the +coordinates of the celestial north pole (\emph{i.e} longitude zero, +latitude $+\pi/2$) into native spherical coordinates using the inverse of +the \htmlref{Mapping}{Mapping} which follows the WcsMap. + +\end{enumerate} + +\subsubsection{User Defined Fiducial Points} +When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters +PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis +``\emph{i}'') are used to indicate a user-defined fiducial point as +described in section 2.5 of paper II. This results in a shift of IWC +origin being applied \emph{before} the \htmlref{WcsMap}{WcsMap} which converts +IWC into +native spherical coordinates. The values of these projection parameters, +if supplied, are stored as the corresponding \htmlref{PVi\_m}{PVi\_m} attributes +of the WcsMap. + +When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap +determine the native coordinates of the fiducial point (the fixed +defaults for each projection described in paper II are used if the PV +attributes of the WcsMap have not been assigned a value). The +corresponding celestial coordinates are used as the CRVAL\emph{i} +keywords and the corresponding pixel coordinates as the CRPIX\emph{j} +keywords. + +\subsubsection{Common Non-Standard Features} +A collection of common non-standard features are supported when reading a +\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, in addition +to those embodied within the +available encodings of the FitsChan class. These are translated into the +equivalent standard features before being used to create a FrameSet. +Note, the reverse operation is never performed: it is not possible to +produce non-standard features when writing a FrameSet to a FitsChan +(other than those embodied in the available encodings of the FitsChan +class). The supported non-standard features include: + +\begin{itemize} +\item EQUINOX keywords with string values equal to a date preceded +by the letter B or J (\emph{e.g.} ``B1995.0''). + +\item EQUINOX or EPOCH keywords with value zero (these are converted to +B1950). + +\item The IRAF ``ZPX'' projection is represented by a +\htmlref{WcsMap}{WcsMap} with type of +AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn} +keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the +WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic +ZPN projection by including ``lngcor'' or ``latcor'' terms. These are +supported if they use half cross-terms, in either simple or Chebyshev +representation. + +\item The IRAF ``TNX'' projection is represented by a WcsMap with type of +AST\_\_TPN (a distorted TAN projection retained within the WcsMap class +from an early draft of the FITS-WCS paper II). Projection parameter values +are read from any WAT\emph{i\_nnn} keywords, and corresponding PV +attributes are set in the WcsMap. If the TNX projection cannot be +converted exactly into an AST\_\_TPN projection, ASTWARN keywords are +added to the FitsChan containing a warning message (but only if the +\htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently, +TNX projections that use half cross-terms, in either simple or Chebyshev +representation, are supported. + +\item ``QV'' parameters for TAN projections (as produced by +\xref{AUTOASTROM}{sun242}{} +\footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}} +are renamed to the equivalent ``PV'' parameters. + +\item TAN projections that have associated ``PV'' parameters on the +latitude axis are converted to the corresponding TPN (distorted TAN) +projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute +of the FitsChan class. + +\end{itemize} + +\subsection{Paper III - Spectral Coordinates} +These conventions are used when reading a \htmlref{FrameSet}{FrameSet} +from a \htmlref{FitsChan}{FitsChan} which includes appropriate +CTYPE\emph{i} values, and when writing a FrameSet in which +the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}. + +\htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword +whose meaning is defined or extended by FITS-WCS paper III. + +\begin{table}[htbp] +\begin{footnotesize} +\begin{tabular}{|l|p{2.5in}|p{2.5in}|} +\hline +\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} +& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline + +\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types +listed in paper III are supported algorithm (the ``-LOG'' algorithm may +also be applied to non-spectral linear axes; the ``-TAB'' algorithm +requires the \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the +SpecFrame and the nature of the pixel to SpecFrame +\htmlref{Mapping}{Mapping}.} + +\fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of +the SpecFrame (note, SpecFrames always have an ``active'' Units attribute +(see \htmlref{astSetActiveUnit}{astSetActiveUnit}).}{Always written.} + +\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values +are stored as attributes of a \htmlref{GrismMap}{GrismMap}).} +{Set from the attributes of the GrismMap, if present, and if set explicitly.} + +\fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{StdOfRest} +attribute of the SpecFrame (all systems are supported except CMBDIPOL).} +{Set from the StdOfRest attribute of the SpecFrame, but only if it has been +set explicitly.} + +\fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.} + +\fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and +\htmlref{ObsLat}{ObsLat} attributes of the Frame (the observers +height above sea level is ignored).}{Set from the ObsLon and ObsLat +attributes of the Frame, if they have been set explicitly (it is +assumed that the observer is at sea level).} + +\fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of +the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has +been set explicitly.} + +\fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the +SpecFrame +(all systems are supported except CMBDIPOL).} {Set from the SourceVRF +attribute of the SpecFrame.} + +\fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{SourceVel} +attribute of the SpecFrame (the SourceVRF attribute +is first set to the system indicated by the SSYSSRC keyword, and the +ZSOURCE value is then converted to an apparent radial velocity and stored +as the SourceVel attribute).} +{Set from the SourceVel attribute of +the SpecFrame, if it has been set explicitly (the SourceVel value is +first converted from apparent radial velocity to redshift).} + +\fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the +SpecFrame that define the standard of rest and the observers position.} + +\fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{RestFreq} +attribute of the SpecFrame.}{Set from the RestFreq attribute of the +SpecFrame, but only if the System attribute is not set to +``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set +explicitly.} + +\fitskey{RESTWAV\emph{a}}{Used to set the RestFreq +attribute of the SpecFrame (after conversion from wavelength to frequency).} +{Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the +System attribute is set to ``WAVE'', ``VOPT'', ``ZOPT'' or +``AWAV'', and only if RestFreq has been set explicitly.} + +\fitskey{CNAME\emph{ia}}{Used to set the Label attributes of +the WCS Frame keywords.}{Set from the Label attributes of the WCS Frame, +if they have been set explicitly.} +\hline +\end{tabular} +\end{footnotesize} +\vspace{3.mm} +\caption{Use of FITS-WCS Paper III keywords} +\label{tab:fitspaper3} +\end{table} + +\subsubsection{Requirements for a Successful Write Operation} +When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a +\htmlref{FitsChan}{FitsChan}, the write operation is successful only if +the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame +in the FrameSet) to the SpecFrame satisfies one of the following conditions: + +\begin{enumerate} +\item It is linear. +\item It is logarithmic. +\item It is linear if the SpecFrame were to be re-mapped into one of the +other spectral systems supported by FITS-WCS paper III. +\item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from +pixel coordinates to grism parameter) is linear, and the Mapping after the +GrismMap is either null or represents a change of spectral system from wavelength (air or +vacuum) to one of the supported spectral systems. +\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan. +\end{enumerate} + +If none of the above conditions hold, the write operation will be +unsuccessful. Note, if the FitsChan's TabOK attribute is set to a positive +non-zero value then any Mapping that does not meet any of the earlier conditions +will be written out as a look-up table, using the ``-TAB'' algorithm described +in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or +negative in the FitsChan, then the write operation will be unsuccessful unless +one of the eaerlier conditions is met.\footnote{If the -TAB algorithm is used, the +positive value of the TabOK attribute is used as the table version number +(the EXTVER header) in the associated FITS binary table.} + +\subsubsection{Common Non-Standard Features} +The following non-standard features are supported when reading spectral +axes from a \htmlref{FitsChan}{FitsChan}: + +\begin{itemize} +\item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes +(specified in early drafts of paper III) to the corresponding +``-X2P'' form. +\item Conversion of ``RESTFREQ'' to ``RESTFRQ'' +\end{itemize} + +\subsection{Paper IV - Coordinate Distortions} + +This paper proposes that an additional 4 character code be appended to +the end of the CTYPE\emph{i} keyword to specify the nature of any +distortion away from the basic algorithm described by the first 8 +characters of the CTYPE\emph{i} value. Currently AST ignores all such +codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} (except for the ``-SIP'' code +defined by the Spitzer Space Telescope project - see below). This means that +a FrameSet can still be read from such headers, but the \htmlref{Mapping}{Mapping} which gives +the WCS position associated with a given pixel position will reflect only +the basic algorithm and will not include the effects of the distortion. + +If such a FrameSet is then written out to a FitsChan, the resulting +CTYPE\emph{i} keywords will include no distortion code. + +\subsubsection{The ``-SIP'' distortion code} + +The Spitzer Space Telescope project +(\url{http://www.spitzer.caltech.edu/}) +has developed its own system for encoding 2-dimensional image distortion +within a FITS header, based on the proposals of paper IV. A description +of this system is available in +\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}. In this +system, the presence of distortion is indicated by appending the +distortion code ``-SIP'' to the CTYPE\emph{i} keyword values for the +celestial axes. The distortion takes the form of a polynomial function +which is applied to the pixel coordinates, after subtraction of the +CRPIX\emph{j} values. + +This system is a strictly 2 dimensional system. When reading a +\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which +includes the ``-SIP'' distortion code, AST assumes that it +is only applied to the first 2 WCS axes in a FITS header (i.e. +CTYPE1 and CTYPE2). If the ``-SIP'' distortion code is attached to other +axes, it will be ignored. The distortion itself is represented by a +\htmlref{PolyMap}{PolyMap} within the resulting FrameSet. + +If a FrameSet is read from a FitsChan which includes ``-SIP'' +distortion, and an attempt is then made to write this FrameSet out to a +FitsChan, the write operation will fail unless the distortion is +insignificant (\emph{i.e.} is so small that the tests for linearity built +into AST are passed). In this case, no distortion code will be appended to +the resulting CTYPE\emph{i} keyword values. + +\newpage +\section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes} + +\subsection{Changes Introduced in V1.1} + +The following describes the most significant changes which occurred in +the AST library between versions V1.0 and V1.1 (not the most recent +version): + +\begin{enumerate} + +\item A new ``How To\ldots'' section (\secref{ss:howto}) has been +added to this document. It contains simple recipies for performing +commonly-required operations using AST. + +\item A new \htmlref{astUnformat}{astUnformat} function has been provided to read formatted +coordinate values for the axes of a \htmlref{Frame}{Frame} +(\secref{ss:unformattingaxisvalues}). In essence, this function is the +inverse of \htmlref{astFormat}{astFormat}. It may be used to decode user-supplied formatted +values representing coordinates, turning them into numerical values +for processing. Celestial coordinates may also be read using this +function (\secref{ss:unformattingskyaxisvalues}) and free-format input +is supported. + +\item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting +celestial coordinate values now allows the degrees/hours field to be +omitted, so that celestial coordinates may be given in (\emph{e.g.}) +arc-minutes and/or arc-seconds +(\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours +field is no longer included by default. A new ``t'' format specifier +has been introduced (see the Format attribute) to allow minutes and/or +seconds of time to be specified if required. + +\item A new function \htmlref{astMapBox}{astMapBox} has been introduced. This allows you to +find the extent of a ``bounding box'' which just encloses another box +after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to +calculate the size which an image would have if it were transformed by +the Mapping. + +\item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced +(\secref{ss:intramaps}). This is a specialised form of Mapping which +encapsulates a privately-defined coordinate transformation function +(\emph{e.g.}\ written in C) so that it may be used like any other AST +Mapping. This allows you to create Mappings that perform any +conceivable coordinate transformation. + +\item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically +preserved whenever changes are made to any attributes which affect the +current Frame (either by setting or clearing their values). This is +accomplished by appropriately re-mapping the current Frame to account +for any change to the coordinate system which it represents +(\secref{ss:framesetintegrity}). + +\item The internal structure of a FrameSet is now automatically tidied +to eliminate redundant nodes whenever any of its Frames is removed or +re-mapped. Automatic simplification of any compound Mappings which +result may also occur. The effect of this change is to prevent the +accumulation of unnecessary structure in FrameSets which are +repeatedly modified. + +\item Some improvements have been made to the algorithms for +simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. + +\item The textual representation used for some Objects +(\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed +slightly, but remains compatible with earlier versions of AST. + +\item Interfaces to the internal functions and macros used by AST for +handling memory and error conditions are now provided \emph{via} the +``ast.h'' header file. This is for the benefit of those writing +(\emph{e.g.}) new graphics interfaces for AST. + +\item A problem has been fixed which could result when using \htmlref{astRead}{astRead} +to read FITS headers in which the CDELT value is zero. Previously, +this could produce a Mapping whose inverse transformation was not +defined and this could unnecessarily restrict the use to which it +could be put. The problem has been overcome by supplying a suitable +small CDELT value for FITS axes which have only a single pixel. + +\item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap} +to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of +a compound Mapping which is being simplified using astSimplify. + + +\item A problem has been fixed which could prevent tick marks being +drawn on a coordinate axis close to a singularity in the coordinate +system. +\end{enumerate} + +\subsection{Changes Introduced in V1.2} + +The following describes the most significant changes which occurred in +the AST library between versions V1.1 and V1.2 (not the most recent +version): + +\begin{enumerate} +\item A new function, \htmlref{astPolyCurve}{astPolyCurve}, has been introduced to allow more +efficient plotting of multiple geodesic curves +(\secref{ss:plottinggeodesics}). + +\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced +to perform resampling of gridded data such as images +(\emph{i.e.}\ re-gridding) under the control of a geometrical +transformation specified by a \htmlref{Mapping}{Mapping}. + +\item The command-line options ``$-$pgp'' and ``$-$pgplot'', which +were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and +``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option +``$-$pgp'' now causes linking with the Starlink version of PGPLOT +(which uses GKS to generate its output), while ``$-$pgplot'' links +with the standard (or ``native'') version of PGPLOT. + +\item The function \htmlref{astMapBox}{astMapBox} has been changed to execute more quickly, +although this has been achieved at the cost of some loss of robustness +when used with difficult Mappings. + +\item A new value of ``FITS-IRAF'' has been introduced for the +\htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an +interim solution to the problem of storing coordinate system +information in FITS headers, until the proposed new FITS-WCS standard +becomes stable. + +\item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by +reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame} +of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to +``GRID''. This reflects the fact that this Frame represents FITS data +grid coordinates (equivalent to FITS pixel coordinates---see +\secref{ss:domainconventions}). Previously, this Domain value was not +set. + +\item \htmlref{astFindFits}{astFindFits} now ignores trailing spaces in its keyword template. + +\item \htmlref{astPutFits}{astPutFits} now recognises ``D'' and ``d'' as valid exponent +characters in floating point numbers. + +\item The FitsChan class is now more tolerant of common minor +violations of the FITS standard. + +\item The FitsChan class now incorporates an improved test for the +linearity of Mappings, allowing more reliable conversion of AST data +into FITS (using ``foreign'' FITS encodings). + +\item Some further improvements have been made to the algorithms for +simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. + +\item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap} +class. This allows improved simplification of compound Mappings +(CmpMaps) involving SphMaps and typically improves performance when +handling FITS world coordinate information. + +\item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of +AST\_\_BAD automatically to all output coordinates. If certain output +coordinates do not depend on the affected input coordinate(s) because +the relevant matrix elements are zero, then they may now remain valid. + +\item A minor bug has been corrected which could cause certain +projections which involve half the celestial sphere to produce valid +coordinates for the other (unprojected) half of the sphere as well. + +\item A bug has been fixed which could occasionally cause \htmlref{astConvert}{astConvert} +to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was +possible when, in fact, it wasn't. +\end{enumerate} + +\subsection{Changes Introduced in V1.3} + +The following describes the most significant changes which occurred in +the AST library between versions V1.2 and V1.3 (not the most recent +version): + +\begin{enumerate} +\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to +provide efficient resampling of gridded data, such as spectra and +images, under the control of a geometrical transformation specified by +a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported. + +\item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised +form of Mapping which implements 2-dimensional pincushion or barrel +distortion. + +\item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too +many digits when formatting floating point values for inclusion in a +FITS header if the numerical value was in the range -0.00099999\ldots +to -0.0001. + +\item A bug has been fixed which could cause a FitsChan to lose the +comment associated with a string value in a FITS header. + +\item A FitsChan now reports an error if it reads a FITS header which +identifies a non-standard sky projection (previously, this was +accepted without error and a Cartesian projection used instead). + +\item A bug has been fixed which could prevent conversion between the +coordinate systems represented by two CmpFrames. This could only occur +if the CmpFrames contained a relatively large number of nested Frames. + +%\item A bug has been fixed which could cause a program to crash if +%FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet} +%had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The +%problem could only occur if the nested structure was loaded from a data +%c+ +%file (using \htmlref{astRead}{astRead}). +%c- +%f+ +%file (using AST\_READ). +%f- +% +\item Further improvements have been made to the simplification of +compound Mappings, including fixes for several bugs which could cause +indefinite looping or unwanted error messages. + +\item Some memory leaks have been fixed. + +\item A small number of documentation errors have been corrected. +\end{enumerate} + +\subsection{Changes Introduced in V1.4} + +The following describes the most significant changes which have occurred +in the AST library between versions V1.3 and V1.4 (not the most recent +version): + +\begin{enumerate} +\item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of +\htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a +flexible and transportable way using arithmetic operations and +mathematical functions similar to those available in C. + +\item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation functions +used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{astIntraReg}{astIntraReg}) now +require a ``this'' pointer as their first parameter. \textbf{Existing +implementations will not continue to work correctly with this version +of AST unless this parameter is added.} There is no need for existing +software to make use of this pointer, but it must be present. + +This change has been introduced so that transformation functions can gain +access to IntraMap attributes. + +\item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap +class. This allows the transformation functions used by IntraMaps to +adapt to produce the required transformation on a per-IntraMap basis +(\secref{ss:intraflag}). + +\item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the +length of major and minor tick marks on coordinate axes, may now be +subscripted using an axis number. This allows tick marks of different +lengths to be used on each axis. It also allows tick marks to be +suppressed on one axis only by setting the length to zero. + +\item The value of the Plot attribute NumLab, which controls the +plotting of numerical labels on coordinate axes, no longer has any +effect on whether labelling of a coordinate grid is interior or +exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute). + +\item The \htmlref{FitsChan}{FitsChan} class now provides some support for the +IRAF-specific ``ZPX'' sky projection, which is converted transparently +into the equivalent FITS ``ZPN'' projection (see the description of the +\htmlref{Encoding}{Encoding} attribute for details). + +\item The FitsChan class now recognises the coordinate system ``ICRS'' +(International Celestial Reference \htmlref{System}{System}) as equivalent to +``FK5''. This is an interim measure and full support for the +(exceedingly small) difference between ICRS and FK5 will be added at a +future release. + +Note that ``ICRS'' is not yet recognised as a coordinate system by other +classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the +importation of foreign data. + +\item A bug in the FitsChan class has been fixed which could result in +longitude values being incorrect by 180 degrees when using cylindrical +sky projections, such as the FITS ``CAR'' projection. + +\item A bug in the FitsChan class has been fixed which could result in +the FITS sky projection parameters ProjP(0) to ProjP(9) being +incorrectly named PROJP1 to PROJP10 when written out as FITS cards. + +\item A bug in the FitsChan class has been fixed which could cause +confusion between the FITS-IRAF and FITS-WCS encoding schemes if both +a CD matrix and a PC matrix are erroneously present in a FITS header. + +\item Some minor memory leaks have been fixed. + +\item A small number of documentation errors have been corrected. +\end{enumerate} + +\subsection{Changes Introduced in V1.5} + +The following describes the most significant changes which have +occurred in the AST library between versions V1.4 and V1.5 (not the most +recent version): + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft +FITS WCS standard, described in the two papers ``Representation of world +coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th +November, 1999), and ``Representation of celestial coordinates in FITS'' +(M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are +available at +\url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}. + +The FITS-WCS encoding now uses these updated conventions. The main +changes are: + +\begin{itemize} +\item Rotation and scaling of pixel axes is now represented by a matrix +of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and +\texttt{CDELTj} keywords. +\item \htmlref{Projection}{Projection} parameters are now associated with particular axes and +are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm} +keywords. +\item The tangent plane projection (``TAN'') can now include optional +polynomial correction terms. +\item An entire set of keywords must be supplied for each set of secondary +axis descriptions, and each such keyword must finish with a single +character indicating which set it belongs to. This means that keywords +which previously occupied eight characters have been shorten to seven to +leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}. +\end{itemize} + +\item Two new encodings have been added to the FitsChan class: +\begin{description} + +\item [FITS-PC] This encoding uses the conventions of the now superseded +FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords +\texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation. +These are the conventions which were used by the FITS-WCS encoding prior +to version 1.5 of AST. This encoding is provided to allow existing data +which use these conventions to be read. It should not in general be used +to create new data. + +\item [FITS-AIPS] This encoding is based on the conventions described in the +document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen +(revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu +/fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and +\texttt{CDELTi} keywords to describe axis rotation and scaling. + +\end{description} + +\item The FitsChan class now provides some support for the IRAF-specific +``TNX'' sky projection, which is converted transparently into the +equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding} +attribute for details). + +\item FrameSets originally read from a DSS encoded FITS header can now be +written out using the FITS-WCS encoding (a TAN projection with correction +terms will be used) in addition to the DSS encoding. The reverse is also +possible: FrameSets originally read from a FITS-WCS encoded FITS header +and which use a TAN projection can now be written out using the DSS +encoding. + +\item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet} +conforms to the FITS-WCS model has been improved so that FrameSets +including more complex mixtures of parallel and serial Mappings +can be written out using the FITS-WCS encoding. + +\item The FitsChan class has been changed so that long strings included in +the description of an \htmlref{Object}{Object} can be saved and restored without truncation +when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles, +mathematical expressions, \emph{etc.} were truncated if they exceeded the +capacity of a single FITS header card. They are now split over several +header cards so that they can be restored without truncation. Note, this +facility is only available when using NATIVE encoding. + +\item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which +can be used to select potentially dangerous conditions under which +warnings should be issued. These conditions include (for instance) +unsupported features within non-standard projections, missing keywords +for which default values will be used, \emph{etc}. + +\item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the +FITS-WCS encoding in the FitsChan class: +\begin{itemize} +\item Projection parameters are now associated with a particular axis and +are specified using a new set of attributes called PVj\_m. Here, ``j'' is +the index of an axis of WcsMap, and ``m'' is the index of the projection +parameter. +\item The old attributes ProjP(0) to ProjP(9) are still available but are +now deprecated in favour of the new PVj\_m attributes. They are interpreted +as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of +the latitude axis. +\item The GLS projection projection has been renamed as SFL, but the +AST\_\_GLS type has been retained as an alias for AST\_\_SFL. +\end{itemize} + +\end{enumerate} + +\subsection{Changes Introduced in V1.6} + +The following describes the most significant changes which have +occurred in the AST library between versions V1.5 and V1.6: + +\begin{enumerate} + +\item The C interface to several methods (\htmlref{astTranN}{astTranN}, \htmlref{astMark}{astMark} and +\htmlref{astPolyCurve}{astPolyCurve}) have been changed to make them easier to call from C++. +Parameters which previously had type ``double (*)[]'' have been changed +to the simpler ``double *''. Using the old types may result in non-fatal +compiler warnings, but should not change the behaviour of the methods. + +\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups +of tick marks to be skipped when using very small gaps. + +\item A bug has been fixed in the Plot class which could cause axes to be +labeled outside the visible window, resulting in no axes being visible. + +\item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the +WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of +the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding +Frames in the returned FrameSet. When writing a FrameSet to a FITS header +the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the +header. + +\item The FITS-WCS encoding used by the FitsChan class now attempts to +retain the identification letter associated with multiple axis +descriptions. When reading a FrameSet from a FITS header, the identification +letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a +FrameSet to a FITS header, the identification letter is read from the +Ident attribute of each Frame. The letter to associate with each Frame +can be changed by assigning a new value to the Frame's Ident attribute. + +\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the +FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to +``Unknown'' if the CTYPE keywords in the supplied header refers to an +unknown celestial coordinate system. Previously, a Frame was used instead +of a SkyFrame. + +\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the +FitsChan class no longer report an error if the FITS header contains no +CTYPE keywords. It is assumed that a missing CTYPE keyword implies that +the world coordinate system is linear and identically equal to +``intermediate world coordinates''. + +\item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute +of the FitsChan class. This value causes warnings to be issued if CTYPE +keywords are missing from foreign encodings. + +\item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan +class. This is a read-only, space separated list of all the known condition +names which can be specified in the Warnings attribute. + +\item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in +a FrameSet read using a foreign encoding. The Title is based on the Domain +name of the Frame. If the Frame has no Domain name, the default Title +supplied by the Frame class is retained. + +\item The FitsChan class uses the comments associated with CTYPE +keywords as axis labels when reading a foreign encoding. This behaviour +has been modified so that the default labels provided by the Frame class +are retained (instead of using the CTYPE comments) if any of the CTYPE +comments are identical. + +\item A new ``interpolation'' scheme identified by the symbolic constant +AST\_\_BLOCKAVE has been added to the AST\_RESAMPLE$<$X$>$ set of +functions. The new scheme calculates each output pixel value by finding +the mean of the input pixels in a box centred on the output pixel. + +\item The SkyFrame class can now be used to represent an arbitrary spherical +coordinate system by setting its System attribute to ``Unknown''. + +\item The indices of the latitude and longitude axes of a SkyFrame can +now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The +effects of any axis permutation is taken into account. + +\item A new attribute called Ident has been added to the \htmlref{Object}{Object} class. +This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID) +its value is transferred to the new Object when a copy is made. + +\item A bug has been fixed which could prevent complex CmpFrames +behaving correctly (for instance, resulting in the failure of attempts +to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself). + +\end{enumerate} + +\subsection{Changes Introduced in V1.7} + +The following describes the most significant changes which have +occurred in the AST library between versions V1.6 and V1.7: + +\begin{enumerate} + +\item The \htmlref{Frame}{Frame} class has a new method called +\htmlref{astAngle}{astAngle} +which returns the angle subtended by two points at a third point within a +2 or 3 dimensional Frame. + +\item The Frame class has a new method called +\htmlref{astOffset2}{astOffset2} +which calculates a position which is offset away from a given starting +point by a specified distance along a geodesic curve which passes +through the starting point at a given position angle. It can only be used +with 2-dimensional Frames. + +\item The Frame class has a new method called +\htmlref{astAxDistance}{astAxDistance} +which returns the increment between two supplied axis values. For +axes belonging to SkyFrames, the returned value is normalized into +the range $\pm\pi$. + +\item The Frame class has a new method called +\htmlref{astAxOffset}{astAxOffset} +which returns an axis value a given increment away from a specified axis +value. For axes belonging to SkyFrames, the returned value is normalized into +the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude +axes). + +\item The \htmlref{Plot}{Plot} class has a new method called +\htmlref{astGenCurve}{astGenCurve} +which allows generalised user-defined curves to be drawn. The curve is +defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve +into the corresponding position in the current Frame of the Plot. The new +method then maps these current Frame position into graphics coordinates, +taking care of any non-linearities or discontinuities in the mapping. + +\item The Plot class has a new method called +\htmlref{astGrfSet}{astGrfSet} +which allows the underlying primitive graphics functions to be selected +at run-time. Previously, the functions used by the Plot class to produce +graphics could only be selected at link-time, using the options of the +\htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride +the functions established at link-time, by specifying alternative +primitive graphics routines. In addition, the two new Plot methods +\htmlref{astGrfPush}{astGrfPush} and \htmlref{astGrfPop}{astGrfPop} +allow the current graphics routines to be saved and restore on a +first-in-last-out stack, allowing temporary changes to be made to the set +of registered graphics routines. + +\item The DrawAxes attribute of the Plot class can now be specified +independantly for each axis, by appending the axis index to the +end of the attribute name. + +\item A bug has been fixed in the Plot class which could result in axis +labels being drawn on inappropriate edges of the plotting box when using +``interior'' labelling. + +\item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps +to be corrupted after transforming any points. + +\item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause +inappropriate ordering of headers within a FitsChan when writing or +reading objects using NATIVE encodings. + +\item A bug has been fixed in the FitsChan class which could cause the +celestial longitude of a pixel to be estimated incorrectly by 180 degrees +if the reference point is at either the north or the south pole. + +\end{enumerate} + + +\subsection{Changes Introduced in V1.8-2} + +The following describes the most significant changes which have +occurred in the AST library between versions V1.7 and V1.8-2: + +\begin{enumerate} + +\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows + longitude values to be displayed in the range $-\pi$ to $+\pi$, instead + of the usual range zero to $2.\pi$. + +\item Some new +functions (\htmlref{astAngle}{astAngle}, \htmlref{astAxAngle}{astAxAngle}, \htmlref{astResolve}{astResolve}, \htmlref{astOffset2}{astOffset2}, \htmlref{astAxOffset}{astAxOffset}, +\htmlref{astAxDistance}{astAxDistance}) +have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space +to be performed without needing to know the underlying geometry +of the co-ordinate system (for instance, whether it is Cartesian or +spherical). + +Note, version 1.8-1 contained many of these facilities, but +some have been changed in version 1.8-2. Particularly, positions angles +are now referred to the second Frame axis for \emph{all} classes of Frames +(including SkyFrames), and the +astBear function has been replaced by astAxAngle. + +\end{enumerate} + +\subsection{Changes Introduced in V1.8-3} + +The following describes the most significant changes which +occurred in the AST library between versions V1.8-2 and V1.8-3: + +\begin{enumerate} + +\item A new method called \htmlref{astDecompose}{astDecompose} has been added to the \htmlref{Mapping}{Mapping} class +which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and +\htmlref{CmpFrame}{CmpFrame} objects. + +\item Functions within proj.c and wcstrig.c have been renamed to avoid name +clashes with functions in more recent versions of Mark Calabretta's wcslib +library. + +\end{enumerate} + +\subsection{Changes Introduced in V1.8-4} + +The following describes the most significant changes which +occurred in the AST library between versions V1.8-3 and V1.8-4: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be +used to select the default reference frame and equinox to be used if +a FitsChan with foreign encoding contains no indication of the +reference frame or equinox. + +\item A bug has been fixed in the FitsChan class which could prevent +\htmlref{astWrite}{astWrite} from creating a set of FITS headers from an otherwise valid +\htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding. + +\item A bug has been fixed in the FitsChan class which could cause +\htmlref{astRead}{astRead} to mis-interpret the FITS CROTA keyword when using FITS-AIPS +encoding. + +\end{enumerate} + +\subsection{Changes Introduced in V1.8-5} + +The following describes the most significant changes which +occurred in the AST library between versions V1.8-4 and V1.8-5: + +\begin{enumerate} + +\item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2, +Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2. +These allow graphical attributes (colour, width, etc) to be set for each +axis individually. Previously, graphical attributes could only be set for +both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs, +TextLabs and Ticks. + +\end{enumerate} + + +\subsection{Changes Introduced in V1.8-7} + +The following describes the most significant changes which +occurred in the AST library between versions V1.8-5 and V1.8-7: + +\begin{enumerate} + +\item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class +which controls the way CAR projections are handled when reading a +\htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR +projection to represent a simple linear transformation between pixel +coordinates and celestial sky coordinates. This is not consistent with +the definition of the CAR projection in the draft FITS-WCS standard, which +requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native +spherical coordinates to celestial spherical coordinates, thus making the +Mapping non-linear. Setting CarLin to 1 forces +\htmlref{astRead}{astRead} +to ignore the FITS-WCS standard and treat any CAR projections as simple +linear Mappings from pixel coordinates to celestial coordinates. + +\item A bug has been fixed which could result in axis Format attributes +set by the user being ignored under certain circumstances. + +\item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class +has been fixed. This bug could result in extra ticks marks being displayed at +inappropriate positions. This bug manifested itself, for instance, if the +Mapping represented by the Plot was a simple Cartesian to Polar Mapping. +In this example, the bug caused tick marks to be drawn at negative radius +values. + +\item A bug has been fixed which could prevent attribute settings from +being read correctly by +\htmlref{astSet}{astSet}, +etc., on certain platforms (MacOS, for instance). + +\end{enumerate} + +\subsection{Changes Introduced in V1.8-8} + +The following describes the most significant changes which +occurred in the AST library between versions V1.8-7 and V1.8-8: + +\begin{enumerate} + +\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause +problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS +information stored in the form of Digitised Digitised Sky Survey (DSS) +keywords. These problems only occurred for DSS fields in the southern +hemisphere, and resulted in pixel positions being mapped to sky positions +close to the corresponding \emph{northern} hemispshere field. + +\item A new method called +\htmlref{astBoundingBox}{astBoundingBox} +has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of +the previous graphical output produced by a Plot method. + +\item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class +which suppresses the graphical output normally produced by Plot methods. +All the calculations needed to produce the normal output are still +performed however, and so the bounding box returned by the new +astBoundingBox +method is still usable. + +\item Bugs have been fixed related to the appearance of graphical output +produced by the Plot class. These bugs were to do with the way in which +graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.) +interacted with the corresponding generic element (e.g. +\texttt{Colour(axes)}, etc.). + +\end{enumerate} + + +\subsection{Changes Introduced in V1.8-13} + +The following describes the most significant changes which occurred +in the AST library between versions V1.8-8 and V1.8-13: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords +are only produced by \htmlref{astWrite}{astWrite} when necessary. For zenithal projections such as +TAN, the LONPOLE keyword can always take its default value and so is +not included in the FITS header produced by astWrite. +Previously, the unnecessary production of a LONPOLE keyword could prevent +FrameSets being written out using encodings which do not support the +LONPOLE keyword (such as FITS-IRAF). + +\item The FitsChan class has been modified to retain leading and trailing +spaces within COMMENT cards. + +\item The FitsChan class has been modified to only use CTYPE comments as +axis labels if all non-celestial axes have unique non-blank comments +(otherwise the CTYPE keyword values are used as labels). + +\item The FitsChan class has been modified so that it does not append a +trailing ``Z'' character to the end of DATE-OBS keyword values. + +\item The FitsChan class has been modified to use latest list of FITS-WCS +projections, as described in the FITS-WCS paper II, ``Representations of +celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23 +April 2002). Support has been retained for the polynomial correction +terms which previous drafts have allowed to be associated with TAN +projections. + +\item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN +(which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN +projection type now represents a simple TAN projection and has no +associated projection parameters. In addition, the usage of projection +parameters has been brought into line with the the FITS-WCS paper II. + +\item The WcsMap class has been modified so that a ``get'' operation on a +projection parameter attribute will return the default value defined in the +FITS-WCS paper II if no value has been set for the attribute. Previously, a +value of AST\_\_BAD was returned in such a situation. + +\item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which +allow a ``plottable range'' to be specified for each Frame axis. The grid +produced by the \htmlref{astGrid}{astGrid} method will not extend beyond these limits. + +\end{enumerate} + +\subsection{Changes Introduced in V2.0} + +Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by +applications linked with earlier versions of AST. This applies to Frame +descriptions created using: +\begin{itemize} +\item the \htmlref{Channel}{Channel} class +\item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used +\item the \htmlref{astShow}{astShow} function +\end{itemize} + +Applications must be re-linked with AST V2.0 in order to be able to read +Frame descriptions created by AST v2.0. + +The following describes the most significant changes which have +occurred in the AST library between versions V1.8-13 and V2.0 (the +current version): + +\begin{enumerate} + +\item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame} +class has been changed from ``CMP'' to a string formed by concatenating +the Domain attributes of the two component Frames, separated by a minus +sign. If both component Domains are blank, then the old default of +``CMP'' is retained for the CmpFrame Domain. + +\item The implementation of the +\htmlref{astWrite}{astWrite} function +within the FitsChan class has been modified. It will now attempt to +produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the +number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the +\htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This +has always been possible with NATIVE encoding, but has not previously +been possible for foreign encodings. The WCSAXES keyword is used to store +the number of WCS axes in the FITS header. + +\item Another change to the +astWrite function +within the FitsChan class is that the ordering of ``foreign'' axes +(\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix +as diagonal as possible - any element of axis transposition is removed by +this re-ordering as recommended in FITS-WCS paper I. Previously the +ordering was determined by the order of the axes in the Current Frame of +the supplied FrameSet. This change does not affect NATIVE encoding. + +\item Support for spectral coordinate systems has been introduced +throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}. +The SpecFrame is a 1-dimensional Frame which can be used to describe +positions within an electromagnetic spectrum in various systems +(wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred +to various standards of rest (topocentric, geocentric, heliocentric +LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral +axis values between these various systems and standards of rest. Note, +FitsChans which have a foreign encoding (\emph{i.e.} any encoding other +than NATIVE) are not yet able to read or write these new classes. + +\item Facilities have been added to the Frame class which allow +differences in axis units to be taken into account when finding a Mapping +between two Frames. In previous versions of AST, the Unit attribute was a +purely descriptive item intended only for human readers - changing the +value of Unit made no difference to the behaviour of the Frame. As of +version 2.0, the Unit attribute can influence the nature of the Mappings +between Frames. For instance, if the +astFindrame or \htmlref{astConvert}{astConvert} +method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m'' +and another Axis with Unit set to ``km'', then the method will return a +\htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes. +These facilities assume that units are specified following the rules +included in FITS-WCS paper I (\emph{Representation of World +Coordinates in FITS}, Greisen \& Calabretta). + +In order to minimise the risk of breaking existing software, the default +behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.} +to retain the previous behaviour). However, the new Frame method +\htmlref{astSetActiveUnit}{astSetActiveUnit} +may be used to ``activate'' (or deactivate) the new facilities within a +specific Frame. Note, the new SpecFrame class is different to the simple +Frame class in that the new facilities for handling units are always active +within a SpecFrame. + +\item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been +moved to the parent Frame class. This enables all sub-classes of Frame +(such as the new SpecFrame class) to share these attributes, and to provide +suitable options for each class. + +\item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows +control over the alignment process performed by the methods +\htmlref{astFindFrame}{astFindFrame} and astConvert. + + +\item The CmpFrame class has been modified so that attributes of a +component Frame can be accessed without needing to extract the Frame first. +To do this, append an axis index to the end of the attribute name. For +instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order), +then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the +``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute +of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently +``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the +CmpFrame will refer to the System attribute of the SpecFrame, whereas the +``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the +System attribute of the SkyFrame (the ``System'' attribute without an axis +specifier will refer to the System attribute of the CmpFrame as a whole, +since System is an attribute of all Frames, and a CmpFrame is a Frame and +so has its own System value which is independant of the System attributes +of its component Frames). + +\item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit +overlapping axis labels, and the abbreviation of redundant leading fields +within sexagesimal axis labels, have been improved to avoid some anomolous +behaviour in previous versions. + +\item The curve drawing algorithm used by the Plot class has been +modified to reduce the chance of it ``missing'' small curve sections, +such as may be produced if a grid line cuts across the plot very close to +a corner. Previously, these missed sections could sometimes result in +axis labels being omitted. + +\item A new function +(\htmlref{astVersion}{astVersion}) +has been added to return the version of the AST library in use. + +\item Bugs have been fixed in the Plot class which caused serious problems +when plotting high precision data. These problems could range from the +omission of some tick marks to complete failure to produce a plot. + +\end{enumerate} + +Programs which are statically linked will need to be re-linked in +order to take advantage of these new facilities. + + +\subsection{Changes Introduced in V3.0} + +The following describes the most significant changes which +occurred in the AST library between versions V2.0 and V3.0: + +\begin{enumerate} + +\item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring +the FITS-WCS encoding into line with the current versions of the FITS-WCS +papers (see +\url{http://www.atnf.csiro.au/people/mcalabre/WCS/}): + +\begin{itemize} + +\item The rotation and scaling of the pixel axes may now be specified using +either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute +called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which +set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS +header. + +\item The FITS-WCS encoding now supports most of the conventions +described in FITS-WCS paper III for the description of spectral +coordinates. The exceptions are that the SSYSOBS keyword is not +supported, and WCS stored in tabular form (as indicated by the ``-TAB'' +algorithm code) is not supported. + + +\item User-specified fiducial points for WCS projections are now +supported by FitsChans which use FITS-WCS encoding. This use keywords +PVi\_0, PVi\_1 and PVi\_2 for the longitude axis. + +\item When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3 +and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE +and LATPOLE keywords which may be present. When writing a FITS-WCS header, +both forms are written out. + +\item The number of WCS axes is stored in the WCSAXES keyword if its value +would be different to that of the NAXIS keyword. + +\item Helio-ecliptic coordinates are now supported by FitsChans which use +FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The +resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all +the usual facilities, such as conversion to other celestial systems, are +available. + +\item The FITS-WCS encoding now supports most of the conventions +described in FITS-WCS paper III for the description of spectral +coordinates. The exceptions are that the SSYSOBS keyword is not +supported, and WCS stored in tabular form (as indicated by the ``-TAB'' +algorithm code) is not supported. + +\item When reading a FITS-WCS header, a FitsChan will now ignore any +distortion codes which are present in CTYPE keywords. Here, a ``distortion +code'' is the final group of four characters in a CTYPE value of the +form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception +to this is that the ``-SIP'' distortion code (as used by the Spitzer +Space Telescope project - see +\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is +interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent +the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes +can only be read, not written. A FrameSet which uses a PolyMap will not +in general be able to be written out to a FitsChan using any foreign +encoding (although NATIVE encoding can of course be used). + +\item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values +``BadVal'' (which gives warnings about conversion errors when reading +FITS keyword values), ``Distortion'' (which gives warnings about +unsupported distortion codes within CTYPE values), and ``BadMat'' (which +gives a warning if the rotation/scaling matrix cannot be inverted). + +\item When writing a FrameSet to a FitsChan which uses a non-Native +encoding, the comment associated with any card already in the FitsChan +will be retained if the keyword value being written is the same as the +keyword value already in the FitsChan. + +\item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN +projection with polynomial distortion terms) can now be written to a +FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard +``-TAN'' code is used within the CTYPE values, and the distortion +coefficients are encoded in keywords of the form `` QVi\_ma'', which are +directly analogous to the standard ``PVi\_ma'' projection parameter keywords. +Thus a FITS reader which does not recognise the QV keywords will still +be able to read the header, but the distortion will be ignored. + +\item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value +of the Encoding attribute. + +\item A new appendix has been added to SUN/210 and SUN/211 giving details +of the implementation provided by the FitsChan class of the +conventions contained in the first four FITS-WCS papers. +\end{itemize} + +\item The SkyFrame class now supports two new coordinate systems ``ICRS'' +and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames +has been changed from ``FK5'' to ``ICRS''. + +\item The +\htmlref{astRate}{astRate} +function has been added which allows an estimate to be made of the rate of +change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs. + +\item All attribute names for Frames of any class may now include an optional +axis specifier. This includes those attributes which describe a property +of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be +specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases +such as this, where the attribute describes a property of the whole +Frame, axis specifiers will usually be ignored. The exception is that a +\htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the +attribute name relates to the primary Frame containing the specified +axis, rather than to the CmpFrame as a whole. + +\item A new subclass of Mapping, the PolyMap, has been added which +performs a general N-dimensional polynomial mapping. + +\item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which +models the spectral dispersion produced by a grating, prism or grism. + +\item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds +constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap} +with unit scaling on all axes). + +\item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice +and placement of numerical axis labels. + +\item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the +longitude value to be returned when a Cartesian position corresponding to +either the north or south pole is transformed into spherical coordinates. + +\item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output +celestial coordinates which have a latitude of plus or minus 90 degrees. + +\item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been +changed so that they now return the fixed native coordinates of the +projection reference point, rather than the native coordinates of the +user-defined fiducial point. + +\item Notation has been changed in both the WcsMap and FitsChan classes to +reflect the convention used in the FITS-WCS papers that index ``i'' refers +to a world coordinate axis, and index ``j'' refers to a pixel axis. + +\item Changes have been made to several Mapping classes in order to allow +the +\htmlref{astSimplify}{astSimplify} +function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not +possible. + +\item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions +between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates. + +\item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the +refractive index of air as given in the current version of FITS-WCS paper +III. Also, the forward and inverse transformations between frequency and +air-wavelength have been made more compatible by using an iterative +procedure to calculate the inverse. + +\end{enumerate} + +\subsection{Changes Introduced in V3.1} + +The following describes the most significant changes which have +occurred in the AST library between versions V3.0 and V3.1 (the +current version): + +\begin{enumerate} +\item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which +reads and writes AST objects in the form of XML. +\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect +graphical attributes to be used for various parts of the plot if either +axis has no tick marks (i.e. if both major and minor tick marks have zero +length). +\end{enumerate} + +Programs which are statically linked will need to be re-linked in +order to take advantage of these new facilities. + + +\subsection{Changes Introduced in V3.2} + +The following describes the most significant changes which have +occurred in the AST library between versions V3.1 and V3.2: + +\begin{enumerate} + +\item A new +function \htmlref{astPutCards}{astPutCards} +has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header +cards to be stored in a FitsChan in a single call, providing an alternative to +the existing +astPutCards function. + +\item Some signficant changes have been made to the simplification of Mappings + which should resultin a greater degree of simplication taking place.Some + bugs have also been fixed which could result in an infinite loop being + entered when attempting to simplify certain Mappings. + +\item The FitsChan class now translates the spectral algorithm codes +``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to +the corresponding ``-X2P'' form when reading a spectral axis description +from a set of FITS header cards. + +\item A bug has been fixed in the FitsChan class which could cause +keywords associated with alternate axis descriptions to be mis-interpreted. + +\item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance +of sub-strings within text strings such as axis labels, titles, \emph{etc}, +by producing super-scripts, sub-scripts, changing the font colour, size, +\emph{etc}. See attribute \htmlref{Escape}{Escape}. + +\item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been +changed from 0.001 to 0.01. This should not usually cause any significant +visible change to the plot, but should make the plotting faster. You may +need to set a lower value for Tol if you are producing a particularly +large plot. + +\item The algorithm for finding the default value for the Gap attribute +has been changed. This attribute specifies the gap between major axis +values in an annotated grid drawn by the Plot class. The change in +algorithm may cause the default value to be different to previous versions +in cirtain circumstances. + +\item Some bugs have been fixed in the Plot class which could cause the +system to hang for a long time while drawing certain all-sky grids +(notable some of the FITS Quad-cube projections). + +\item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition +of the ``g'' option. this option is similar to the older ``l'' option in that +it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as +delimiters between the sexagesimal fields of the celestial position. The +difference is that the ``g'' option includes graphics escape sequences +in the returned formatted string which result in the field delimiter +characters being drawn as super-scripts when plotted as numerical axis values +by a Plot. + +\item The Plot class has been extended to include facilities for producing +logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel. + +\item New functions astGCap and astGScales have been added to the interface +defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so +that the \verb+-mygrf+ switch loads dummy versions of the new grf +functions. This means that applications should continue to build without +any change. However, the facilities for interpreting escape sequences +within strings drawn by the Plot class will not be available unless the +new grf functions are implemented. If you choose to implement them, you +should modify your linking procedure to use the \verb+-grf+ switch in +place of the older \verb+-mygrf+ switch. See the description of the ast\_link +command for details of the new switches. Also note that the astGQch +function, whilst included in verb+grf.h+ in pervious versions of AST, was +not actually called. As of this version of AST, calls are made to the +astGQch function, and so any bugs in the implementation of astGQch may +cause spurious behaviour when plotting text strings. + +\item A new 'static' method called \htmlref{astEscapes}{astEscapes} has been added which is used +to control and enquire whether astGetC and \htmlref{astFormat}{astFormat} will strip any graphical +escape sequences which may be present out of the returned value. + +\item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It +allows XML written by the XmlChan class to include an explicit namespace +prefix on each element. + +\item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It +specifies the format in which AST objects should be written. + +\item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap +takes its forward transformation from an existing Mapping, and its inverse +transformation from another existing Mapping. + +\item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to +include erroneous axis numbers when referring to missing parameter values. + +\end{enumerate} + +\subsection{Changes Introduced in V3.3} + +The following describes the most significant changes which have +occurred in the AST library between versions V3.2 and V3.3: + +\begin{enumerate} + +\item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the +origin +of celestial coordinates to be moved to any specified point. See the new +attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. + +\item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra +Frames representing cartesian projection plane coordinates (``intermediate +world coordinates'' in the parlance of FITS-WCS) to be created when +reading +WCS information from a foreign FITS header. This option is controlled by +a new attribute called \htmlref{Iwc}{Iwc}. + +\item The FitsChan class which been modified to interpret FITS-WCS CAR +projection headers correctly if the longitude reference pixel (CRPIX) is +very large. + +\item The FITS-AIPS++ encoding in the FitsChan class now recognised +spectral axes if they conform to the AIPS convention in which the +spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB" +where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD, +HEL or OBS. Such spectral axes can be both read and written. + +\item The FitsChan class now has a FITS-AIPS++ encoding which represents +WCS information using FITS header cards recognised by the AIPS++ project. +Support for spectral axes is identical to the FITS-AIPS encoding. + +\item The organisation of the AST distribution and the commands for +building it have been changed. Whereas AST used to be built and installed +with \verb+./mk build; ./mk install+, it now builds using the more standard +idiom \verb+./configure; make; make install+. The installation location is +controlled by the \verb+--prefix+ argument to ./configure (as is usual +for other packages which use this scheme). Note that the INSTALL environment +variable now has a \emph{different} meaning to that which it had +before, and it should generally be \emph{unset}. Also, there is no need to +set the SYSTEM variable. + +\item Shared libraries are now installed in the same directory as the +static libraries. In addition, links to sharable libraries are installed +with names which include version information, and ``libtool libraries'' +are also installed (see +\url{http://www.gnu.org/software/libtool/manual.html}). + +\item The \verb+ast_dev+ script has been removed. Instead, the location of +the AST include files should be specified using the -I option when +compiling. + + +\end{enumerate} + + +\subsection{Changes Introduced in V3.4} + +The following describes the most significant changes which have +occurred in the AST library between versions V3.3 and V3.4: + +\begin{enumerate} + +\item The \htmlref{Mapping}{Mapping} class has a new method +(\htmlref{astLinearApprox}{astLinearApprox}) +which calculates the co-efficients of a linear approximation to a Mapping. + +\item The Format attribute for simple Frames and SkyFrames has been extended. +It has always been possible, in both classes, to specify a precision by +including a dot in the Format value followed by an integer (\emph{e.g.} +``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}). +The precision can now also be specified using an asterisk in place of the +integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the +precision to be derived on the basis of the Digits attribute value. + +\item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the +Digits attribute is chosen to be the smallest value which results in no +pair of adjacent labels being identical. For instance, if an annotated +grid is being drawn describing a SkyFrame, and the Format(1) value is set +to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as +superscripts), and the Digits(1) value is unset, then the seconds field +will have a number of decimal places which results in no pair of labels +being identical. + +\item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a +sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes +associated with dual sideband spectral data. + +\item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS'' +projection code, converting them to the corresponding modern ``-SFL'' code, +provided that the celestial axes are not rotated. + +\item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows +the reading and writing of FITS headers using the conventions of the CLASS +package - see +\url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}). + +\end{enumerate} + + +\subsection{Changes Introduced in V3.5} + +The following describes the most significant changes which have +occurred in the AST library between versions V3.4 and V3.5: + +\begin{enumerate} + +\item AST now provides facilities for representing regions of various +shapes within a coordinate system. The \htmlref{Region}{Region} class provides general +facilities which are independent of the specific shape of region being +used. Various sub-classes of Region are also now available which provide +means of creating Regions of specific shape. Facilities provided by the +Region class include testing points to see if they are inside the +Region, testing two Regions for overlap, transforming Regions from one +coordinate system to another \emph{etc}. + +\item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which +can be used to describe various systems for describing ovserved value at a +single fixed spectral position. + +\item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which +can be used to describe a 2-d frame spanned by a spectral position axis +and and an observed value axis. + +\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates +a previously created Mapping. The inputs of the RateMap correspond to the +inputs of the encapsulated Mapping. All RateMaps have just a single +output which correspond to the rate of change of a specified output of +the encapsulated Mapping with respect to a specified input. + +\item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}. +This system is an equatorial system based on the mean dynamical equator and +equinox at J2000, and differs slightly from an FK5(J2000) system. + +\item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to +store a collection of vector or scalar values or Objects, indexed by a +character string rather than an integer. + +\item The parameter list for the +\htmlref{astRate}{astRate} +method of the Mapping class has been modified. It no longer returns a second +derivative estimate. Existing code which uses this method will need to be +changed. + +\item Methods +(astSetFits<X>) +have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named +keywords to be changed or added. + +\end{enumerate} + + +\subsection{Changes Introduced in V3.6} + +The following describes the most significant changes which +occurred in the AST library between versions V3.5 and V3.6: + +\begin{enumerate} + +\item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame} +starts with a percent character (``\verb+%+''), then axis values are +now formatted and unformatted as a decimal radians value, using the +Format syntax of a simple \htmlref{Frame}{Frame}. + +\item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the +clipping performed by AST at the plot boundary. + +\item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a +PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys +are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}. +The new PolyMap class always writes new styles keys but can read either +old or new style keys. Consequently, PolyMap dumps written by this +version of AST cannot be read by older versions of AST. + +\item A mimimal cut down subset of the C version of SLALIB is now +included with the AST distribution and built as part of building AST. +This means that it is no longer necessary to have SLALIB installed +separately at your site. The SLALIB code included with AST is distrubuted +under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to +link with this internal slalib subset. However, the ``-csla'' option can +still be used to force linking with an external full C SLALIB library. +A new option ``-fsla'' has been introduced which forces linking with the +external full Fortran SLALIB library. + +\end{enumerate} + +\subsection{Changes Introduced in V3.7} + +The following describes the most significant changes which +occurred in the AST library between versions V3.6 and V3.7: + +\begin{enumerate} + +\item Support for time coordinate systems has been introduced +throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}. +The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe +moments in time (either absolute or relative) in various systems (MJD, +Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC, +UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time +values between these various systems and time scales. Note, +FitsChans which have a foreign encoding (\emph{i.e.} any encoding other +than NATIVE) are not able to read or write these new classes. + +\end{enumerate} + + +\subsection{Changes Introduced in V4.0} + +The following describes the most significant changes which +occurred in the AST library between versions V3.7 and V4.0: + +\begin{enumerate} + +\item Experimental support for reading IVOA Space-Time-Coordinates (STC-X) +descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included +for a subset of V1.20 of the draft STC specification. + +\item A new set of methods (AST\_REBIN<X>/astRebin<X>) has been added to +the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing +AST\_RESAMPLE<X>/astResample<X> methods. + +\end{enumerate} + + +\subsection{Changes Introduced in V4.1} + +The following describes the most significant changes which +occurred in the AST library between versions V4.0 and V4.1: + +\begin{enumerate} + +\item A new control flag has been added to the AST\_RESAMPLE<X>/astResample<X> +functions which produces approximate flux conservation. + +\item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to +ast.h. These specify kernels for astResample and astRebin +based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the +first order Bessel function of the first kind). + +\item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding +to horizon (azimuth/elevation) coordinates. + +\item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and +``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values. + +\item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify +the geodetic longitude and latitude of the observer. + +\item The ClockLon and ClockLat attributes have been removed from the +\htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been +removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and +ObsLat attributes of the parent Frame class instead. However, the old +attribute names can be used as synonyms for ObsLat and ObsLon. Also, +dumps created using the old scheme can be read succesfully by AST V4.1 +and converted to the new form. + +\item A new +function \htmlref{astMapSplit}{astMapSplit} +has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component +Mappings which, when combined in parallel, are equivalent to the original +Mapping. + +\item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from +``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame +to represent offsets from some origin position, you must now set the +SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in +addition to assigning the required origin position to the SkyRef attribute. + +\end{enumerate} + +\subsection{Changes Introduced in V4.2} + +The following describes the most significant changes which +occurred in the AST library between versions V4.1 and V4.2: + +\begin{enumerate} + +\item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the +option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the +DSBSpecFrame to represent the offset from the local oscillator frequency, +rather than either of the two sidebands. + +\item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS +keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric +apparent velocity of the standard of rest). FitsChan also strips out VELOSYS +keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding. + +\item The FitsChan class has a new method called +\htmlref{astRetainFits}{astRetainFits} +that indicates that the current card in the FitsChan should not be +stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan. +Unless this method is used, all cards that were involved in the creation +of the AST Object will be stripped from the FitsChan afte a read operation. + +\item A problem with unaligned memory access that could cause bus errors on +Solaris has been fixed. + +\item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base +Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the +Object. Note, this is the size of the internal in-memory representation of +the Object, not the size of the textual representation produced by +writing the Object out through a \htmlref{Channel}{Channel}. + +\item A new function +\htmlref{astTune}{astTune} +has been added which can be used to get and set global AST tuning +parameters. At the moment there are only two such parameter, both of +which are concerned with memory management within AST. + +\item A new method called +\htmlref{astTranGrid}{astTranGrid} +has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular +grid of points covering a rectangular region within the input space of a +Mapping, and then transforms this set of points into the output space of the +Mapping, using a piecewise-continuous linear approximation to the Mapping +if appropriate in order to achive higher speed. + +\item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A +SwitchMap represents several alternate Mappings, each of which is used to +transforms input positions within a different region of the input +coordinate space. + +\item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A +SelectorMap tests each input position to see if it falls within one of +several Regions. If it does, the index of the \htmlref{Region}{Region} containing the +input position is returned as the Mapping output. + +\item The behaviour of the +\htmlref{astConvert}{astConvert} +method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been +modified. If no conversion between positions in the Frame and CmpFrame +can be found, an attempt is now made to find a conversion between the +Frame and one of two component Frames contained within the CmpFrame. Thus +is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a +SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad +values for the extra axes (i.e. for the SpecFrame axis in the above example). + +\item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the +\verb+-fsla+ and \verb+-csla+ options, and always link against the +minimal cut-down version of SLALIB distributed as part of AST. + +\end{enumerate} + +\subsection{Changes Introduced in V4.3} + +The following describes the most significant changes which occurred in the +AST library between versions V4.2 and V4.3: + +\begin{enumerate} + +\item The +astGetFitsS +function now strips trailing white space from the returned string, if the +original string contains 8 or fewer characters + +\item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified +whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the +source) should be accessed as an apparent radial velocity or a redshift. +Note, any existing software that assumes that SourceVel always represents +a velocity in km/s should be changed to allow for the possibility of +SourceVel representing a redshift value. + +\end{enumerate} + + +\subsection{Changes Introduced in V4.4} + +The following describes the most significant changes which occurred in +the AST library between versions V4.3 and V4.4: + +\begin{enumerate} + +\item The +\htmlref{astFindFrame}{astFindFrame} +function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more +specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame} +or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as +the ``template'' when calling +astFindFrame, +and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the +current Frame is a CmpFrame), then the component Frames within the CmpFrame +will be searched for an instance of the supplied template Frame, and, if +found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the +required axes from the CmpFrame) will be returned by +astFindFrame. +Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template +Frame must be set so that they cover a range that includes the number of axes +in the target CmpFrame. + +\item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes +now allow the MaxAxes and MinAxes attributes to be set freely to any value. +In previous versions of AST, any attempt to change the value of MinAxes +or MaxAxes was ignored, resulting in them always taking the default values. + +\item The DSBSpecFrame class has a new attribute called AlignSB that +specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when +aligning two DSBSpecFrames using +\htmlref{astConvert}{astConvert}. + +\item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to +store a value for the difference between the UT1 and UTC timescales at +the epoch referred to by the Frame. + +\item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and +\htmlref{ObsLon}{ObsLon} has been increased. + +\item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This +attribute is used to control how two SkyFrames are aligned by +astConvert. +If the template and target SkyFrames both have a non-zero value for +AlignOffset, then alignment occurs between the offset coordinate systems +(that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). + +\item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be +used to force exterior (rather than interior) tick marks to be produced. +By default, exterior ticks are only produced if this would result in +more than 3 tick marks being drawn. + +\item The TimeFrame class now supports conversion between angle based +timescales such as UT1 and atomic based timescales such as UTC. + +\end{enumerate} + +\subsection{Changes Introduced in V4.5} + +The following describes the most significant changes that +occurred in the AST library between versions V4.4 and V4.5: + +\begin{enumerate} + + + +\item All FITS-CLASS headers are now created with a frequency axis. If the +\htmlref{FrameSet}{FrameSet} supplied to +\htmlref{astWrite}{astWrite} +contains a velocity axis (or any other form +of spectral axis) it will be converted to an equivalent frequency axis +before being used to create the FITS-CLASS header. + +\item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed +from the velocity of the source to the velocity of the reference channel. + +\item Addition of a new method call +\htmlref{astPurgeWCS}{astPurgeWCS} +to the \htmlref{FitsChan}{FitsChan} +class. This method removes all WCS-related header cards from a FitsChan. + +\item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used +to comminicate context information between an application and any +graphics functions registered with the Plot class via the +\htmlref{astGrfSet}{astGrfSet} function. +\item Functions registered with the Plot class using +astGrfSet +now take a new additional integer parameter, ``grfcon''. The Plot class +sets this parameter to the value of the Plot's GrfContext attribute before +calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING +CODE THAT USES +astGrfSet +TO BE MODIFIED TO INCLUDE THE NEW PARAMETER. +\item The +astRebinSeq functions +now have an extra parameter that is used to record the total number of input +data values added into the output array. This is necessary to correct a +flaw in the calculation of output variances based on the spread of input +values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO +INCLUDE THE NEW PARAMETER (CALLED "NUSED"). +\item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection. +\item A new flag ``AST\_\_VARWGT'' can be supplied to +astRebinSeq. +This causes the input data values to be weighted using the reciprocals of +the input variances (if supplied). + +\item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that +returns the normalised value of the Unit attribute for an axis. Here, +``normalisation'' means cancelling redundant units, etc. So for instance, a +Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''. + +\item A new +function \htmlref{astShowMesh}{astShowMesh} +has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering +the surface of a Region by writing out a table of axis values to standard +output. + +\item The Plot class now honours the value of the LabelUp attribute even if +numerical labels are placed around the edge of the Plot. Previously +LabelUp was only used if the labels were drawn within the interior of +the plot. The LabelUp attribute controls whether numerical labels are +drawn horizontally or parallel to the axis they describe. + +\item A bug has been fixed that could segmentation violations when setting +attribute values. + +\end{enumerate} + +\subsection{Changes Introduced in V4.6} + +The following describes the most significant changes which have +occurred in the AST library between versions V4.5 and V4.6: + +\begin{enumerate} + +\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset +from UTC to Local Time is specified by a new TimeFrame attribute called +\htmlref{LTOffset}{LTOffset}. + +\item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows +the creation of 3-dimensional annotated coordinate grids. + +\item A correction for diurnal aberration is now included when +converting between AZEL and other celestial coordinate systems. The +correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the +geodetic latitude of the observer). + +\item A bug has been fixed which caused the DUT1 attribute to be ignored +by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other +celestial coordinate systems. + +\end{enumerate} + +\subsection{Changes Introduced in V5.0} + +The following describes the most significant changes which +occurred in the AST library between versions V4.6 and V5.0: + +\begin{enumerate} + + +\item The AST library is now thread-safe (assuming that the POSIX pthreads +library is available when AST is built). Many of the macros defined in +the ast.h header file have changed. It is therefore necessary to +re-compile all source code that includes ast.h. + +\item New methods \htmlref{astLock}{astLock} and \htmlref{astUnlock}{astUnlock} allow an AST \htmlref{Object}{Object} to be locked +for exclusive use by a thread. + +\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset +from UTC to Local Time is specified by a new TimeFrame attribute called +\htmlref{LTOffset}{LTOffset}. + +\item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls +whether or not to report an error if unexpected data items are found +within an AST Object description read from an external data source. Note, +the default behaviour is now not to report such errors. This differs from +previous versions of AST which always reported an error is unexpected +input items were encountered. + +\end{enumerate} + +\subsection{Changes Introduced in V5.1} + +The following describes the most significant changes which occurred in the +AST library between versions V5.0 and V5.1: + +\begin{enumerate} + +\item The \htmlref{astUnlock}{astUnlock} function now has an extra parameter that controls whether +or not an error is reported if the \htmlref{Object}{Object} is currently locked by another +thread. + +\item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can +be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval} +could be used for this purpose. + +\item The values of the AST\_\_THREADSAFE macro (defined in ast.h) have +been changed from ``yes'' and ``no'' to ``1'' and ``0''. + +\item Improvements have been made to the way that Prisms are simplified +when +\htmlref{astSimplify}{astSimplify} +is called. The changes mean that more types of Prism will now simplify +into a simpler class of Region. + +\item The \htmlref{PointList}{PointList} class has a new method, +astPoints, +that copies the axis values from the PointList into a supplied array. + +\item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that +gives the number of points stored in the PointList. + +\item The handling of warnings within different classes of \htmlref{Channel}{Channel} has +been rationalised. The XmlStrict attribute and +astXmlWarnings +function have been removed. The same functionality is now available via +the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new +attribute called \htmlref{ReportLevel}{ReportLevel}, and the new +\htmlref{astWarnings}{astWarnings} +function. This new function can be used on any class of Channel. Teh +\htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as +header cards within the FitsChan, but it also now stores warnings in the +parent Channel structure, from where they can be retrieved using the +astWarnings +function. + +\item A new function called +astIntercept +has been added to the \htmlref{Frame}{Frame} class. This function finds the point of +intersection beteeen two geodesic curves. + +\item A bug in the type-checking of Objects passed as arguments to constructor +functions has been fixed. This bug could lead to applications crashing or +showing strange behaviour if an inappropriate class of Object was +supplied as an argument to a constructor. + +\item The +\htmlref{astPickAxes}{astPickAxes} +function will now return a Region, if possible, when applied to a Region. If +this is not possible, a Frame will be returned as before. + +\item The choice of default tick-mark for time axes has been improved, to avoid +previous issues which could result in no suitable gap being found, or +inappropriate tick marks when using formatted dates. + +\item A new function called +\htmlref{astTestFits}{astTestFits} +has been added to the FitsChan class. This function tests a FitsChan to +see if it contains a defined value for specified FITS keyword. + +\item The AST\_\_UNDEF<X> parameters used to flag undefined FITS keyword values +have been removed. Use the new +astTestFits +function instead. + +\item The astIsUndef<X> functions used to test FITS keyword values +have been removed. Use the new astTestFits function instead. + +\end{enumerate} + +\subsection{Changes Introduced in V5.2} + +The following describes the most significant changes which +occurred in the AST library between versions V5.1 and V5.2: + +\begin{enumerate} + +\item A new method called +\htmlref{astSetFitsCM}{astSetFitsCM} +has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a +FitsChan (that is, a card with no keyword name or equals sign). + +\item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It +records the geodetic altitude of the observer, in metres. It defaults to +zero. It is used when converting times to or from the TDB timescale, or +converting spectral positions to or from the topocentric rest frame, or +converting sky positions to or from horizon coordinates. The FitsChan +class will include its effect when creating a set of values for the +OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a +set of OBSGEO-X/Y/Z keyword values from a FITS header. + +\item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap} +conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument - +the observer's geodetic altitude. + +\item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the +IVOA STC definition of a Polygon. Specifically, the inside of a polygon +is now the area to the left of each edge as the vertices are traversed in +an anti-clockwise manner, as seen from the inside of the celestial sphere. +Previously, AST used the anti-clockwise convention, but viewed from the +outside of the celestial sphere instead of the inside. Any Polygon saved +using previous versions of AST will be identified and negated automatically +when read by AST V5.2. + +\item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows +conversion of suitable AST Objects to and from IVOA STC-S format. + +\item A new method called +\htmlref{astRemoveRegions}{astRemoveRegions} +has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound) +Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either +removes them, or replaces them with UnitMaps (or equivalent Frames). It +can be used to remove the masking effects of Regions from a compound +Mapping or Frame. + +\item A new method called +\htmlref{astDownsize}{astDownsize} +has been added to the Polygon class. It produces a new Polygon that +contains a subset of the vertices in the supplied Polygon. The subset is +chosen to retain the main features of the supplied Polygion, in so far +as that is possible, within specified constraints. + +\item A new constructor called +astOutline +has been added to the Polygon class. Given a 2D data array, it identifies +the boundary of a region within the array that holds pixels with +specified values. It then creates a new Polygon to describe this boundary +to a specified accuracy. + +\item A new set of methods, called +astMapGetElem<X> +has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector +valued entry to be returned. + +\item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It +controls whether the +astMapGet... +family of functions report an error if an entry with the requested key does +not exist in the KeyMap. + +\end{enumerate} + +\subsection{Changes Introduced in V5.3} + +The following describes the most significant changes which +occurred in the AST library between versions V5.2 and V5.3: + +\begin{enumerate} + +\item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the +\htmlref{astFindFrame}{astFindFrame} and \htmlref{astConvert}{astConvert} +functions have been changed. The changes mean that a Frame can now be +aligned with an instance of a sub-class of Frame, so long as the number +of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic +2-dimensional Frame with Domain ``SKY'' will now align succesfully with +a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a +\htmlref{UnitMap}{UnitMap}. + +\item The arrays that supply input values for astMapPut1<X> are now +declared ``const''. + +\item Added method +\htmlref{astMatchAxes}{astMatchAxes} +to the Frame class. This method allows corresponding axes within two +Frames to be identified. + +\item The +\htmlref{astAddFrame}{astAddFrame} +method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}. +\end{enumerate} + +\subsection{Changes Introduced in V5.3-1} + +The following describes the most significant changes which have +occurred in the AST library between versions V5.3 and V5.3-1: + +\begin{enumerate} + +\item The utility functions provided by the AST memory management layer +are now documented in an appendix. + +\item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A +new method called +\htmlref{astMapPutU}{astMapPutU} +will store an entry with undefined value in a keymap. Methods that +retrieve values from a KeyMap +(astMapGet0<X>, etc.) +ignore entries with undefined values when searching for an entry with a given +key. + +\item The KeyMap class has a new method called +\htmlref{astMapCopy}{astMapCopy} +that copies entries from one KeyMap to another KeyMap. + +\item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If +non-zero, +an error is reported if an attempt is made to add any new entries +to a KeyMap (the value associated with any old entry may still be changed +without error). The default is +zero. + +\item The \htmlref{Object}{Object} class has a new method called \htmlref{astHasAttribute}{astHasAttribute}/AST\_HASATTRIBUTE +that returns a boolean value indicating if a specified Object has a named +attribute. + +\item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called +IsLatAxis and IsLonAxis that can be used to determine the nature of a +specified SkyFrame axis. + +\item A bug has been fixed in the +astRebin(Seq) +methods that could cause flux to be lost from the edges of the supplied array. + +\item A bug has been fixed in the +astRebin(Seq) +methods that caused the first user supplied parameter to be interpreted as the +full width of the spreading kernel, rather than the half-width. + +\item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except +that units strings are still case sensitive). + +\item A new \htmlref{Mapping}{Mapping} method, +\htmlref{astQuadApprox}{astQuadApprox}, +produces a quadratic least-squares fit to a 2D Mapping. + +\item A new Mapping method, +\htmlref{astSkyOffsetMap}{astSkyOffsetMap}, +produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame +coordinates. + +\item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation +in the text created by +\htmlref{astWrite}{astWrite}. +The StcsIndent and XmlIndent attributes have been removed. + +\item All classes of Channel now use the string ``<bad>'' to represent the +floating point value AST\_\_BAD, rather than the literal formatted value +(typically ``-1.79769313486232e+308'' ). + +\item The KeyMap class now uses the string ``<bad>'' to represent the +floating point value AST\_\_BAD, rather than the literal formatted value +(typically ``-1.79769313486232e+308'' ). + +\item The KeyMap class has a new method called +astMapPutElem<X> +that allows a value to be put into a single element of a vector entry in +a KeyMap. The vector entry is extended automatically to hold the new +element if required. + +\item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator +frequency is less than the absoliute value of the intermediate frequency. + +\end{enumerate} + + +\subsection{Changes Introduced in V5.3-2} + +The following describes the most significant changes which +occurred in the AST library between versions V5.3-1 and V5.3-2: + +\begin{enumerate} + +\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength +axes to be assigned the units ``m/s'' when reading WCS information from a +FITS header. + +\item The +\htmlref{astSet}{astSet} function +now allows literal commas to be included in string attribute values. String +attribute values that include a literal comma should be enclosed in quotation +marks. + +\item A bug in FitsChan has been fixed that caused ``-SIN'' projection +codes within FITS-WCS headers to be mis-interpreted, resulting in no +\htmlref{FrameSet}{FrameSet} being read by \htmlref{astRead}{astRead}. + +\item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls +the order in which keys are returned by the +\htmlref{astMapKey}{astMapKey} +function. Keys can be sorted alphabetically or by age, or left unsorted. + +\item Access to KeyMaps holding thousands of entries is now significantly +faster. + +\item KeyMaps can now hold word (i.e. +short integer) +values. + +\end{enumerate} + + +\subsection{Changes Introduced in V5.4-0} + +The following describes the most significant changes which +occurred in the AST library between versions V5.3-2 and V5.4-0: + +\begin{enumerate} + +\item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing +of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper +III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}. +See the documentation for TabOK for more information. + +\item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in +which each entry represents a cell in a two-dimensional table. + +\item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a +Table that has an associated FitsChan holding headers appropriate to a +FITS binary table. + +\item KeyMaps can now hold byte values. These are held in variables +of type +"unsigned char". + +\item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to +make the handling of keys case insensitive. + +\item a memory leak associated with the use of the +astMapPutElem<X> +functions has been fixed. + +\item A new method called +\htmlref{astMapRename}{astMapRename} +has been added to rename existing entry in a KeyMap. +\end{enumerate} + +\subsection{Changes Introduced in V5.5-0} + +The following describes the most significant changes which +occurred in the AST library between versions V5.4-0 and V5.5-0: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather +than a boolean value. If TabOK is set to a non-zero positive integer +before invoking the +\htmlref{astWrite}{astWrite} +method, its value is used as the version number for any table that is +created as a consequence of the write operation. This is the value stored +in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the +binary table header. In previous versions of AST, the value used for these +headers could not be controlled and was fixed at 1. If TabOK is set to a +negative or zero value, the -TAB algorithm will not be supported by +either the +astWrite or \htmlref{astRead}{astRead} +methods. + +\end{enumerate} + + + +\subsection{Changes Introduced in V5.6-0} + +The following describes the most significant changes which +occurred in the AST library between versions V5.5-0 and V5.6-0: + +\begin{enumerate} + +\item +New functions \htmlref{astBBuf}{astBBuf} and \htmlref{astEBuf}{astEBuf} +have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical +output produced by other Plot methods. + +\item New functions astGBBuf and astGEBuf have been added to the interface +defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so +that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf +functions. This means that applications that use the \verb+-grf_v3.2+ +switch should continue to build without any change. However, the new public +functions astBBuf and astEBuf +will report an error unless the new grf functions are implemented. If you +choose to implement them, you should modify your linking procedure to +use the \verb+-grf+ (or \verb+-grf_v5.6+ ) switch in place of the older +\verb+-grf_v3.2+ switch. See the description of the ast\_link command for +details of these switches. + +\item New method +\htmlref{astGetRegionMesh}{astGetRegionMesh} +returns a set of positions covering the boundary, or volume, of a supplied +\htmlref{Region}{Region}. + +\end{enumerate} + + +\subsection{ChangesIntroduced in V5.6-1} + +The following describes the most significant changes which +occurred in the AST library between versions V5.6-0 and V5.6-1: + +\begin{enumerate} + +\item Tables can now have any number of parameters describing the global +properties of the \htmlref{Table}{Table}. + +\item Frames now interpret the unit string ``A'' as meaning ``Ampere'' +rather than ``Angstrom'', as specified by FITS-WCS paper I. + +\item A bug has been fixed in the +\htmlref{astFindFrame}{astFindFrame} +method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match +a target frame of a less specialised class. For example, this bug would +allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer +happens. + +\end{enumerate} + +\subsection{Changes Introduced in V5.7-0} + +The following describes the most significant changes which +occurred in the AST library between versions V5.6-1 and V5.7-0: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has +been extended to include reading TNX headers that use a Chebyshev +representation for the distortion polynomial. + +\item The FitsChan class support for the IRAF-specific ``ZPX'' projection has +been extended to include reading ZPX headers that use simple or Chebyshev +representation for the distortion polynomial. + +\item A bug has been fixed in the FitsChan class that caused headers +including the Spitzer ``-SIP'' distortion code to be read incorrectly if no +inverse polynomial was specified in the header. + +\item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It +can be used to indicate that FITS headers that specify a TAN projection +should be interpreted according to the ``distorted TAN'' convention +included in an early draft of FITS-WCS paper II. Such headers are created +by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}). + +\item The \htmlref{PolyMap}{PolyMap} class now provides a method called +\htmlref{astPolyTran}{astPolyTran} +that adds an inverse transformation to a PolyMap by sampling the forward +transformation on a regular grid, and then fitting a polynomial function +from the resulting output values to the grid of input values. + +\end{enumerate} + +\subsection{Changes Introduced in V5.7-1} + +The following describes the most significant changes which +occurred in the AST library between versions V5.7-0 and V5.7-1: + +\begin{enumerate} + +\item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified +text files, without the need to provide source and sink functions when +the Channel is created. The files to use are specified by the new +attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}. + +\item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS +keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header. + +\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the +-SIP (Spitzer) distortion code within the CTYPE values, but which does +not provide an inverse polynomial correction, the FitsChan class will now +use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the +inverse polynomial correction. + +\end{enumerate} + + +\subsection{Changes Introduced in V5.7-2} + +The following describes the most significant changes which +occurred in the AST library between versions V5.7-1 and V5.7-2: + +\begin{enumerate} + +\item The \htmlref{Object}{Object} class has a new function \htmlref{astToString}{astToString} (C only), which creates +an in-memory textual serialisation of a given AST Object. A corresponding +new function called \htmlref{astFromString}{astFromString} re-creates the Object from its +serialisation. + +\item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to +evaluate the inverse the inverse transformation if no inverse +transformation is defined when the PolyMap is created. + +\item The \htmlref{FitsChan}{FitsChan} class has a new method +\htmlref{astWriteFits}{astWriteFits} +which writes out all cards currently in the FitsChan to the associated +external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the +sink function supplied when the FitsChan was created), and then empties +the FitsChan. + +\item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which +holds the number of keywords for which values are held in a FitsChan. + +\item The FitsChan +astGetFits<X> +methods can now be used to returned the value of the current card. + +\item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which +holds the data type of the keyword value for the current card. + +\item The FitsChan class has a new method +\htmlref{astReadFits}{astReadFits} +which forces the FitsChan to reads cards from the associated external +source and appends them to the end of the FitsChan. + +\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the +-SIP (Spitzer) distortion code within the CTYPE values, but which does +not provide an inverse polynomial correction, and for which the PolyTran +method of the PolyMap class fails to create an accurate estimate of the +inverse polynomial correction, then an iterative method will be used to +evaluate the inverse correction for each point transformed. + +\end{enumerate} + +\subsection{Changes Introduced in V6.0} + +The following describes the most significant changes which +occurred in the AST library between versions V5.7-2 and V6.0: + +\begin{enumerate} + +\item This version of AST is the first that can be used with the Python +AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}. + +\item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the +non-standard ``TPV'' projection code within a CTYPE keyword value. This +code is used by SCAMP (see www.astromatic.net/software/scamp) to +represent a distorted TAN projection. + +\item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as +incorrectly rotated numerical axis labels) if the graphics coordinates have +unequal scales on the X and Y axes. + +- The graphics escape sequences used to produce graphical sky axis labels +can now be changed using the new +function \htmlref{astTuneC}{astTuneC}. + +\end{enumerate} + +\subsection{Changes Introduced in V6.0-1} + +The following describes the most significant changes which +occurred in the AST library between versions V6.0 and V6.0-1: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion +code within FITS headers that describe non-celestial axes, as well as +celestial axes. + +\item A bug has been fixed that could cause inappropriate equinox values to +be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set. + +\item The versioning string for AST has changed from +``$<major>.<minor>-<release>$'' to ``$<major>.<minor>.<release>$''. + +\end{enumerate} + +\subsection{Changes Introduced in V7.0.0} + +The following describes the most significant changes which +occurred in the AST library between versions V6.0-1 and V7.0.0: + +\begin{enumerate} + +\item Fundamental positional astronomy calculations are now performed +using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{} +otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB +library re-written in C). Copies of these libraries are bundled with AST +and so do not need to be obtained or built separately, although external +copies of SOFA and PAL can be used if necessary by including the +``\texttt{--with-external\_pal}'' option when configuring AST. + +\end{enumerate} + +\subsection{Changes Introduced in V7.0.1} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.0 and V7.0.1: + +\begin{enumerate} + +\item The levmar and wcslib code distributed within AST is now stored in the +main AST library (libast.so) rather than in separate libraries. + +\end{enumerate} + +\subsection{Changes Introduced in V7.0.2} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.1 and V7.0.2: + +\begin{enumerate} + +\item The libast\_pal library is no longer built if the +``--with-external\_pal'' option is used when AST is configured. + +\end{enumerate} + +\subsection{Changes Introduced in V7.0.3} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.2 and V7.0.3: + +\begin{enumerate} + +\item A bug has been fixed which could cause an incorrect axis to be used when +accessing axis attributes within CmpFrames. This could happen if axes +within the \htmlref{CmpFrame}{CmpFrame} have been permuted. + +\item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two +values of the SkyRef and/or SkyRefP attributes to be reversed. + +\item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border +around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately. +Previously, component Regions nested deeply inside a CmpRegion may have +been completely or partially ignored. + +\item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation +violation if the MinTick attribute was set to zero. + +\item The astResampleX set of methods now includes astResampleK and +astResampleUK that handles 64 bit integer data. + +\end{enumerate} + + +\subsection{Changes Introduced in V7.0.4} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.3 and V7.0.4: + + +\begin{enumerate} + +\item The previously private grf3d.h header file is now installed into +prefix/include. + +\end{enumerate} + + +\subsection{Changes Introduced in V7.0.5} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.4 and V7.0.5: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO +convention for representing distorted TAN projections, based on the use +of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial. + +\end{enumerate} + + +\subsection{Changes Introduced in V7.0.6} + +The following describes the most significant changes which +occurred in the AST library between versions V7.0.5 and V7.0.6: + +\begin{enumerate} + +\item A bug has been fixed in astRebinSeq<X> which could result in +incorrect normalisation of the final binned data and variance values. + +\item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1 +and CNPIX2 now default to zero if absent. Previously an error was reported. + +\end{enumerate} + + +\subsection{Changes Introduced in V7.1.0} + +The following describes the most significant changes which occurred in the +AST library between versions V7.0.6 and V7.1.0: + +\begin{enumerate} + +\item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve +flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied +when calling +astRebinSeq<X>. +Without this flag, each output value is a weighted mean of the neighbouring +input values. + +\item A new flag AST\_\_NONORM can be used with astRebinSeq<X> to indicate that +normalisation of the output arrays is not required. In this case no +weights array need be supplied. + +\item A bug has been fixed in +\htmlref{astAddFrame}{astAddFrame} method +that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet} +when the AST\_\_ALLFRAMES flag is supplied for the +"iframe" parameter. + +\item The +\htmlref{astRate}{astRate} method +has been re-written to make it faster and more reliable. + +\end{enumerate} + +\subsection{Changes Introduced in V7.1.1} + +The following describes the most significant changes which +occurred in the AST library between versions V7.1.0 and V7.1.1: + +\begin{enumerate} + +\item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute +\htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions +are now created - one for the offset coordinates and one for the absolute +coordinates. If such a header is subsequently read back into AST, the +original offset SkyFrame is recreated. + +\item A bug has been fixed in FitsChan that caused inappropriate CTYPE values +to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the +current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a +SkyFrame with \htmlref{System}{System}=Unknown). + +\end{enumerate} + +\subsection{Changes Introduced in V7.2.0} + +The following describes the most significant changes which +occurred in the AST library between versions V7.1.1 and V7.2.0: + +\begin{enumerate} + +\item A new method call +\htmlref{astMapDefined}{astMapDefined} +has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has +a defined value in a given KeyMap. + +\end{enumerate} + +\subsection{Changes Introduced in V7.3.0} + +The following describes the most significant changes which +occurred in the AST library between versions V7.2.0 and V7.3.0: + +\begin{enumerate} + +\item The interface for the astRebinSeq<X> family of functions has +been changed in order to allow a greater number of pixels to be pasted +into the output array. The "nused" parameter is now a pointer to a +"int64\_t" variable, instead of an "int". APPLICATION CODE SHOULD BE +CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC +BEHAVIOUR. + +\item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be +associated with multiple Mappings, any one of which can be used to +connect the Frame to the other Frames in the FrameSet. The choice of +which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the +FrameSet class. + +\item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident} +attribute are now left unchanged by the +c \htmlref{astSimplify}{astSimplify} function. +f AST\_SIMPLIFY routine. + +\end{enumerate} + +\subsection{Changes Introduced in V7.3.1} + +The following describes the most significant changes which +occurred in the AST library between versions V7.3.0 and V7.3.1: + +\begin{enumerate} + +\item Fix a bug that could cauise a segmentation violation when reading +certain FITS headers that use a TNX projection. + +\end{enumerate} + +\subsection{Changes Introduced in V7.3.2} + +The following describes the most significant changes which +occurred in the AST library between versions V7.3.1 and V7.3.2: + +\begin{enumerate} + +\item Fix support for reading FITS header that use a GLS projection. +Previously, an incorrect transformation was used for such projections if +any CRVAL or CROTA value was non-zero. + +\item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and +``KeyAgeDown'' that retain the position of an existing entry if its value +is changed. See the \htmlref{SortBy}{SortBy} attribute. + +\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords +for sky axes to be treated as radians rather than degrees when reading a +FITS header, if the corresponding CTYPE values included no projection code. + +\end{enumerate} + +\subsection{Changes Introduced in V7.3.3} + +The following describes the most significant changes which +occurred in the AST library between versions V7.3.2 and V7.3.3: + +\begin{enumerate} + +\item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold +the keyword name and comment of the current card. + +\item When using the FitsChan class to read FITS-WCS headers that include +polynomial distortion in the SIP format, any inverse transformation specified +in the header is now ignored and a new inverse is created to replace it based +on the supplied forward transformation. Previously, an inverse was created +only if the header did not include an inverse. The accuracy of the inverse +transformation has also been improved, although it may now be slower to +evaluate in some circumstances. + +\end{enumerate} + +\subsection{Changes Introduced in V7.3.4} + +The following describes the most significant changes which +occurred in the AST library between versions V7.3.3 and V7.3.4: + +\begin{enumerate} + +\item By default, the simplification of Polygons no longer checks that the +edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices}, +can be set to zero in order to re-instate this check. + +\item The \htmlref{Polygon}{Polygon} class has a new mathod, +astConvex, +that returns a Polygon representing the shortest polygon (i.e. convex +hull) enclosing a specified set of pixel values within a supplied array. + +\end{enumerate} + +\subsection{Changes Introduced in V8.0.0} + +The following describes the most significant changes which +occurred in the AST library between versions V7.3.4 and V8.0.0: + +\begin{enumerate} + +\item AST is now distributed under the Lesser GPL licence. + +\item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack +package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform +least squares fitting of N-dimensional polynomials. + +\item Use of the IAU SOFA library has been replaced by ERFA library, which is +a re-badged copy of SOFA distributed under a less restrictive license. A +copy of ERFA is included within AST. + +\end{enumerate} + +\subsection{Changes Introduced in V8.0.1} + +The following describes the most significant changes which +occurred in the AST library between versions V8.0.0 and V8.0.1: + +\begin{enumerate} + +\item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the + \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}. +\item The order of WCS axes within new FITS-WCS headers created by \htmlref{astWrite}{astWrite} + can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}. +\item Supported added for FITS XPH (polar HEALPIX) projection. +\item The macro used to invoke the \htmlref{astAppendString}{astAppendString} utility function has + changed to allow printf-style converstions to be included in the + supplied text. Any code that uses this macro must be re-compiled. +\item The astRebin and astRebinSeq family of functions now include support + for arrays with char (byte) and unsigned char (unsigned byte) data types. + +\end{enumerate} + +\subsection{Changes Introduced in V8.0.2} +The following describes the most significant changes which +occurred in the AST library between versions V8.0.1 and V8.0.2: + +\begin{enumerate} +\item For security reasons, the change introduced to \htmlref{astAppendString}{astAppendString} in + V8.0.1 has been moved to a new function called \htmlref{astAppendStringf}{astAppendStringf}, and + astAppendString itself has been reverted to its V8.0.0 version. + Any software that has been built against V8.0.1 will need to be + re-compiled and re-linked against V8.0.2. +\end{enumerate} + + +\subsection{Changes Introduced in V8.0.3} +The following describes the most significant changes which +occurred in the AST library between versions V8.0.2 and V8.0.3: + +\begin{enumerate} + +\item Methods +astRebin, astRebinSeq, astResample and \htmlref{astTranGrid}{astTranGrid} +now report an error if an array is specified that has more pixels than +can be counted by a 32 bit integer. +\item The hypertext documentation is now generated using Tex4HT rather +than latex2html. The format of the hypertext docs has changed significantly. +\item Another bug fix associated with reading CAR projections from +FITS-WCS headers. +\item Constructor options strings of the form ``\texttt{..., "\%s", text );}'' +can now be supplied. This avoids a security issue associated with the +alternative form ``\texttt{..., text );}''. +\end{enumerate} + +\subsection{Changes Introduced in V8.0.4} +The following describes the most significant changes which +occurred in the AST library between versions V8.0.3 and V8.0.4: + +\begin{enumerate} + +\item The behaviour of the +\htmlref{astAddFrame}{astAddFrame} method has been changed slightly. Previously, astAddFrame +modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and +\htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes +to the current Frame of the modified FrameSet also affected the supplied +Frame object. Now, deep copies of the Mapping and Frame objects (rather +than references) are stored within the modified FrameSet. This means that +subsequent changes to the modified FrameSet will now have no effect on +the supplied Frame. + +\item The choice of default tick-mark gaps for time axes has been +improved, to avoid a previous issue which could result in no suitable gap +being found. + +- A new method called +\htmlref{astRegionOutline}{astRegionOutline} +has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST +\htmlref{Region}{Region}. + +\item A bug has been fixed that could cause astSimplfy to enter an infinite loop. + +\item Some improvements have been made to the Mapping simplification process +that allow more Mappings to be simplified. + +\item The Frame class has a new read-only attribute called InternalUnit, +which gives the units used for the unformatted (i.e. floating-point) axis +values used internally by application code. For most Frames, the +InternalUnit value is just the same as the Unit value (i.e. formatted and +unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class +always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of +Unit, indicating that floating-point SkyFrame axis values are always in units +of radians. + +\item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies +the relative error of the values in the table. It is used to decide if +the LutMap can be simplified to a straight line. + +\end{enumerate} + + +\subsection{Changes Introduced in V8.0.5} +The following describes the most significant changes which +occurred in the AST library between versions V8.0.4 and V8.0.5: + +\begin{enumerate} + +\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies +the smallest significant distance within the SkyFrame. It is used to +decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit +transformation. The default value is 0.001 arc-seconds. + +\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal +characters within FITS keyword names (i.e. characters not allowed by the +FITS standard) being detected. This bug could under some circumstances +cause a subsequent segmentation violation to occur. + +\item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS +keyword name is encountered that contains any illegal characters. See +attribute ``\htmlref{Warnings}{Warnings}'' and +function ``\htmlref{astWarnings}{astWarnings}''. + +\end{enumerate} + +\subsection{Changes Introduced in V8.1.0} +The following describes the most significant changes which +occurred in the AST library between versions V8.0.5 and V8.1.0: + +\begin{enumerate} + +\item The configure script has a new option ``--without-fortran'' that allows +AST to be built in situations where no Fortran compiler is available. The +resulting library has no Fortran interface and so cannot be used within +Fortran applications. Also, the link scripts do not attempt to include the +fortran runtime libraries. + +\end{enumerate} + +\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes +Introduced in V8.2} +The following describes the most significant changes which +occurred in the AST library between versions V8.1.0 and V8.2.0: + +\begin{enumerate} + +\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts +a vector to a unit vector relative to a specified centre, plus length. A +UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates +represent a unit vector parallel to the supplied input vector, and the +(N+1)'th output coordinate is the length of the input vector. + +\item The restriction that Mappings are immutable has been extended to all +Mapping classes. This means that attributes representing parameters of +a Mapping's forward or inverse transformation cannot be changed after +the Mapping has been created. In order to minimise the risk to existing +software, this rule does not apply to Mappings that have not yet been +included in other objects such as CmpMaps or FrameSets, or which have not +yet been cloned. In other words, an error is reported if an attempt is +made to change the nature of a Mapping's transformation, but only if the +reference count of the Mapping is greater than one. The Mapping classes +affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}. + +\end{enumerate} + + +\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes +Introduced in V8.3} +The following describes the most significant changes which have +occurred in the AST library between versions V8.2.0 and V8.3.0 (the +current version): + +\begin{enumerate} + +\item A new method called \htmlref{astAxNorm}{astAxNorm} +has been added to the \htmlref{Frame}{Frame} class that normalises an array of axis +values. When used with SkyFrames, it allows longitude values to be +normalised into the shortest range. + + +\item A bug has been fixed in the \htmlref{astGetRegionBounds}{astGetRegionBounds} method that could +cause the wrong bounds to be returned for regions spanning a longitude = +zero singularity. + +\end{enumerate} + + +% Programs which are statically linked will need to be re-linked in +% order to take advantage of these new facilities. + +\end{document} |