\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 () { /* Enclose the parts which use AST between the astBegin and astEnd macros. */ astBegin; astEnd; } \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 ... if ( !astOK ) { } else if ( wcsinfo == AST__NULL ) { } else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { } else { } \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 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 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 ) { break; } else { } } \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 $$): \begin{description} \item[CRPIX]\mbox{}\\ hold the pixel coordinates at a reference point \item[CRVAL]\mbox{}\\ hold the corresponding WCS coordinates at the reference point \item[CTYPE]\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\_]\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. */
/* 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 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". */ /* 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 ); /* 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 #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 ... 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" ) ) { } \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 ) { } \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 ) { } \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 ) { } \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 \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) (, 2) --> (, 10) (2, 4) --> (10, 20) (3, 6) --> (15, 30) (4, ) --> (20, ) (5, 10) --> (25, 50) (, ) --> (, ) (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 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 ) { } else { } } \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 ) { } else { } } \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) --> (, 2, 3) (6, 4) --> (, 4, 6) (9, 6) --> (, 6, 9) (12, 8) --> (, 8, 12) (15, 10) --> (, 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 ) { } else { } \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 ) { } else { } \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 ) { } else { } \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 $}{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 ... 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" ) ) { } else { } \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 #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 ); } \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 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 ) { } \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" ) ) { } else { } \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 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} <_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"/> <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/> \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} <_attribute name="Naxes" value="1"/> <_attribute name="Domain" quoted="true" value="SCREEN"/> <_attribute name="Unit" quoted="true" value="cm"/> \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 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 . 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) 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/astRebin) has been added to the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing AST\_RESAMPLE/astResample 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/astResample 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 parameters used to flag undefined FITS keyword values have been removed. Use the new astTestFits function instead. \item The astIsUndef 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 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 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, 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 ``'' 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 ``'' 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 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 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 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 ``$.-$'' to ``$..$''. \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 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. 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 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 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}