diff options
Diffstat (limited to 'ast/sun211.tex')
-rw-r--r-- | ast/sun211.tex | 52927 |
1 files changed, 0 insertions, 52927 deletions
diff --git a/ast/sun211.tex b/ast/sun211.tex deleted file mode 100644 index 9618cab..0000000 --- a/ast/sun211.tex +++ /dev/null @@ -1,52927 +0,0 @@ -\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.4} -\stardocmanual {Programmer's Guide\\(C Version)} -\startitlepic{ - \includegraphics[width=0.25\textwidth]{sun211_figures/fronta}~~~~~\hfill - \includegraphics[width=0.25\textwidth]{sun211_figures/frontb}~~~~~\hfill - \includegraphics[width=0.25\textwidth]{sun211_figures/frontc} -} -\stardocabstract { -The AST library provides a comprehensive range of facilities for -attaching world coordinate systems to astronomical data, for -retrieving and interpreting that information in a variety of formats, -including FITS-WCS, and for generating graphical output based on it. - -This programmer's manual should be of interest to anyone writing -astronomical applications which need to manipulate coordinate system -data, especially celestial or spectral coordinate systems. AST is portable and -environment-independent. -} -% ? End of document identification -% ----------------------------------------------------------------------------- -% ? Document specific \providecommand or \newenvironment commands. - -\providecommand{\appref}[1]{Appendix~\ref{#1}} -\providecommand{\secref}[1]{\S\ref{#1}} - -\providecommand{\fitskey}[3]{{#1}&{#2}&{#3}\\} - -% Use {\tt ... } as \texttt{...} does not work if there are new lines in #1 -\providecommand{\sstsynopsis}[1]{\sstdiytopic{Synopsis}{\tt #1}} - -% Format the constructor section. -\providecommand{\sstconstructor}[1]{\sstdiytopic{Constructor Function}{#1}} - -% ? End of document specific commands -% ----------------------------------------------------------------------------- -% \htmlref{Title}{Title} Page. -% =========== -\begin{document} -\scfrontmatter - -\begin{center} -\emph{This is the C version of this document.\\ - For the Fortran version, please see \xref{SUN/210}{sun210}{}.} -\end{center} - -% Main text of document. -\vspace{7mm} -\section{Introduction} - -Welcome to the AST library. If you are writing software for astronomy -and need to use celestial coordinates (\emph{e.g.}\ RA and Dec), spectral -coordinates (\emph{e.g.}\ wavelength, frequency, \emph{etc.}), or -other coordinate system information, then this library should be of -interest. It provides solutions for most of the problems you will meet -and allows you to write robust and flexible software. It is able to read -and write WCS information in a variety of formats, including -\htmladdnormallink{FITS-WCS}{http://fits.gsfc.nasa.gov/fits_wcs.html}. - -%\subsection{TBW---What is a World Coordinate \htmlref{System}{System}?} - -\subsection{What Problems Does AST Tackle?} - -Here are some of the main problems you may face when handling world -coordinate system (WCS) information and the solutions that AST -provides: - -\begin{description} -\item[1. The Variety of Coordinate Systems]\mbox{}\\ -Astronomers use a wide range of differing coordinate systems to describe -positions within a variety of physical domains. For instance, there are a -large number of celestial coordinate systems in use within astronomy to -describe positions on the sky. Understanding these, and knowing how to -convert coordinates between them, can require considerable expertise. It -can also be difficult to decide which of them your software should support. -The same applies to coordinate systems describing other domains, such as -position within an electro-magnetic spectrum. - -\textbf{Solution.} AST has built-in knowledge of many coordinate systems -and allows you to convert freely between them without specialist -knowledge. This avoids the need to embed details of specific -coordinate systems in your software. You also benefit automatically -when new coordinate systems are added to AST. - -\item[2. Storing and Retrieving WCS Information]\mbox{}\\ -Storing coordinate system information in astronomical datasets and -retrieving it later can present a considerable challenge. Typically, -it requires knowledge of rather complex conventions -(\emph{e.g.}\ FITS) which are low-level, often mis-interpreted and may -be subject to change. Exchanging information with other software -systems is further complicated by the number of different conventions -in use. - -\textbf{Solution.} AST combines a unifying high-level description of WCS -information with the ability to save and restore this using a variety -of formats. Details of the formats, which include FITS, are handled -internally by AST. This frees you from the need to understand them or -embed the details in your software. Again, you benefit automatically -when new formats are added to AST. - -\item[3. Generating Graphical Output]\mbox{}\\ -Producing graphical displays involving curvilinear coordinate systems, -such as celestial coordinate grids, can be complicated. Particular -difficulties arise when handling large areas of sky, the polar regions -and discontinuous (\emph{e.g.}\ segmented) sky projections. Even just -numbering and labelling curvilinear axes is rarely straightforward. - -\textbf{Solution.} AST provides plotting facilities especially designed -for use with curvilinear coordinate systems. These include the -plotting of axes and complete labelled coordinate grids. A large -number of options are provided for tailoring the output to your -specific needs. Three dimensional coordinate grids can also be produced. - -\item[4. Aligning Data from Different Sources]\mbox{}\\ -One of the main uses of coordinate systems is to facilitate the -inter-comparison of data from different sources. A typical use might -be to plot (say) radio contours over an optical image. In practice, -however, different celestial coordinate systems may have been used, -making accurate alignment far from simple. - -\textbf{Solution} AST provides a one-step method of aligning datasets, -searching for all possible intermediate coordinate systems. This -makes it simple to directly inter-relate the pixel coordinates of -different datasets. - -\item[5. Handling Different Types of Coordinate \htmlref{System}{System}]\mbox{}\\ -Not all coordinate systems used in astronomy are celestial ones, so if -you are writing general-purpose software such as (say) a display tool, -you may also need to handle axes representing wavelength, distance, -time or whatever else comes along. Obviously, you would prefer not to -handle each one as a special case. - -\textbf{Solution} AST uses the same flexible high-level model to -describe all types of coordinate system. This allows you to write -software that handles different kinds of coordinate axis without -introducing special cases. -\end{description} - -\subsection{Other Design Objectives} - -As well as its scientific objectives, the AST library's design -includes a number of technical criteria intended to make it applicable -to as wide a range of projects as possible. The main considerations -are described here: - -\begin{enumerate} -\item {\bf{Minimum Software Dependencies.}} -The AST library depends on no other other software\footnote{It comes with -bundled copies of the ERFA and -\xref{Starlink PAL libraries}{sun268}{} which are built -at the same time as the other AST internal libraries. Alternatively, external -PAL and ERFA libraries may be used by specifying the ``\texttt{--with-external\_pal}'' option when configuring AST}. - -\item {\bf{Environment Independence.}} -AST is designed so that it can operate in a variety of ``programming -environments'' and is not tied to any particular one. To allow this, -it uses simple, flexible interfaces to obtain the following services: - -\begin{itemize} -\item {\bf{Data Storage.}} Data I/O operations are based on text -and/or FITS headers. This makes it easy to interface to a wide variety -of astronomical data formats in a machine-independent way. - -\item {\bf{Graphics.}} Graphical output is produced \emph{via} a -simple generic graphics interface, which may easily be re-implemented -over different graphics systems. AST provides a default implementation -based on the widely-used PGPLOT graphics system -(\xref{SUN/15}{sun15}{}). - -\item {\bf{Error Handling.}} Error messages are written to standard -error by default, but go through a simple generic interface similar to -that used for graphics (above). This permits error message delivery -\emph{via} other routes when necessary (\emph{e.g.} in a graphical -interface). -\end{itemize} - -\item {\bf{Multiple Language Support.}} -AST has been designed to be called from more than one language. -Both C and Fortran interfaces are available (see -\xref{SUN/210}{sun210}{} for the Fortran version) -and use from C$++$ is also straightforward if the C interface is -included using: - -\begin{small} -\begin{terminalv} -extern "C" { -#include "ast.h" -} -\end{terminalv} -\end{small} - -A JNI interface (known as ``JNIAST'' - see -\url{http://www.starlink.ac.uk/jniast/}) has also been developed by Starlink -which allows AST to be used from Java. - -\item {\bf{\htmlref{Object}{Object} Oriented Design.}} -AST uses ``object oriented'' techniques internally in order to provide -a flexible and easily-extended programming model. A fairly -traditional calling interface is provided, however, so that the -library's facilities are easily accessible to programmers using -C and Fortran. - -\item {\bf{Portability.}} -AST is implemented entirely in ANSI standard C and, when called -\emph{via} its C interface, makes no explicit use of any -machine-dependent facilities. - -The Fortran interface is, unavoidably, machine dependent. However, the -potential for problems has been minimised by encapsulating the -interface layer in a compact set of C macros which facilitate its -transfer to other platforms. No Fortran compiler is needed to build -the library. - -Currently, AST is supported by Starlink on PC~Linux, Sun~Solaris and -Tru64~Unix (formerly DEC~UNIX) platforms. -\end{enumerate} - -\subsection{What Does ``AST'' Stand For?} - -The library name ``AST'' stands for ``ASTrometry Library''. The name -arose when it was thought that knowledge of ``astrometry'' -(\emph{i.e.}\ celestial coordinate systems) would form the bulk of the -library. In fact, it turns out that astrometry forms only a minor -component, but the name AST has stuck. - -\cleardoublepage -\section{Overview of AST Concepts} - -This section presents a brief overview of AST concepts. It is intended -as a basic orientation course before you move on to the more technical -considerations in subsequent sections. - -\subsection{\label{ss:mappingoverview}Relationships Between Coordinate Systems} - -The relationships between coordinate systems are represented in AST by -Objects called Mappings. A \htmlref{Mapping}{Mapping} does not represent a coordinate -system itself, but merely the process by which you move from one -coordinate system to another related one. - - A convenient picture of a Mapping is as a ``black box'' - (Figure~\ref{fig:mapping}) into which you can feed sets of - coordinates. - \begin{figure}[bhtp] - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/mapping} - \caption{A Mapping viewed as a ``black box'' for transforming coordinates.} - \label{fig:mapping} - \end{center} - \end{figure} - -For each set you feed in, the Mapping returns a corresponding set of -transformed coordinates. Since each set of coordinates represents a -point in a coordinate space, the Mapping acts to inter-relate -corresponding positions in the two spaces, although what these spaces -represent is unspecified. Notice that a Mapping need not have the -same number of input and output coordinates. That is, the two -coordinate spaces which it inter-relates need not have the same number -of dimensions. - -In many cases, the transformation can, in principle, be performed in -either direction: either from the \emph{input} coordinate space to the -\emph{output}, or \emph{vice versa}. The first of these is termed the -\emph{forward} transformation and the other the \emph{inverse} -transformation. - - -\textbf{Further reading:} For a more complete discussion of Mappings, -see~\secref{ss:mappings}. - -\subsection{\label{ss:mappingselection}Mappings Available} - -The basic concept of a \htmlref{Mapping}{Mapping} (\secref{ss:mappingoverview}) is rather -generic and obviously it is necessary to have specific Mappings that -implement specific relationships between coordinate systems. AST -provides a range of these, to perform transformations such as the -following and, where appropriate, their inverses: - -\begin{itemize} -\item Conversions between various celestial coordinate systems (the -\htmlref{SlaMap}{SlaMap}). - -\item Conversions between various spectral coordinate systems (the -\htmlref{SpecMap}{SpecMap} and \htmlref{GrismMap}{GrismMap}). - -\item Conversions between various time systems (the \htmlref{TimeMap}{TimeMap}). - -\item Conversion between 2-dimensional spherical celestial coordinates -(longitude and latitude) and a 3-dimensional vectorial positions (the \htmlref{SphMap}{SphMap}). - -\item Various projections of the celestial sphere on to 2-dimensional -coordinate spaces---\emph{i.e.}\ map projections (the \htmlref{DssMap}{DssMap} and \htmlref{WcsMap}{WcsMap}). - -\item Permutation, introduction and elimination of coordinates (the -\htmlref{PermMap}{PermMap}). - -\item Various linear coordinate transformations (the \htmlref{MatrixMap}{MatrixMap}, \htmlref{WinMap}{WinMap}, -\htmlref{ShiftMap}{ShiftMap} and \htmlref{ZoomMap}{ZoomMap}). - -\item General N-dimensional polynomial transformations (the \htmlref{PolyMap}{PolyMap}). - -\item Lookup tables (the \htmlref{LutMap}{LutMap}). - -\item General-purpose transformations expressed using arithmetic -operations and functions similar to those available in C (the -\htmlref{MathMap}{MathMap}). - -\item Transformations for internal use within a program, based on -private transformation functions which you write yourself in C (the -\htmlref{IntraMap}{IntraMap}). -\end{itemize} - -\textbf{Further reading:} For a more complete description of each of the -Mappings mentioned above, see its entry in -\appref{ss:classdescriptions}. In addition, see the discussion of the -PermMap in \secref{ss:permmapexample}, the \htmlref{UnitMap}{UnitMap} in -\secref{ss:unitmapexample} and the IntraMap in -\secref{ss:intramaps}. The ZoomMap is used as an example throughout -\secref{ss:primer}. - -\subsection{\label{ss:cmpmapoverview}Compound Mappings} - -The Mappings described in \secref{ss:mappingselection} provide a set -of basic building blocks from which more complex Mappings may be -constructed. The key to doing this is a type of \htmlref{Mapping}{Mapping} called a -\htmlref{CmpMap}{CmpMap}, or compound Mapping. A CmpMap's role is, in principle, very -simple: it allows any other pair of Mappings to be joined together -into a single entity which behaves as if it were a single Mapping. A -CmpMap is therefore a container for another pair of Mappings. - - A pair of Mappings may be combined using a CmpMap in either of two - ways. The first of these, \emph{in series}, is illustrated in - Figure~\ref{fig:seriescmpmap}. - \begin{figure} - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/series} - \caption[A CmpMap composed of two component Mappings joined in series]{A CmpMap (compound Mapping) composed of two component - Mappings joined in series. The output coordinates of the first Mapping - feed into the input coordinates of the second one, so that the whole - entity behaves like a single Mapping.} - \label{fig:seriescmpmap} - \end{center} - \end{figure} - - - Here, the transformations implemented by each component Mapping are - performed one after the other, with the output from the first Mapping - feeding into the second. The second way, \emph{in parallel}, is shown in - Figure~\ref{fig:parallelcmpmap}. - \begin{figure} - \begin{center} - \includegraphics[width=0.5\textwidth]{sun211_figures/parallel} - \caption[A CmpMap composed of two Mappings joined in parallel.]{A CmpMap composed of two Mappings joined in parallel. Each - component Mapping acts on a complementary subset of the input and - output coordinates.} - \label{fig:parallelcmpmap} - \end{center} - \end{figure} - -In this case, each Mapping acts on a complementary subset of the -input and output coordinates.\footnote{A pair of Mappings can be combined -in a third way using a \htmlref{TranMap}{TranMap}. A TranMap allows the forward -transformation of one Mapping to be combined with the inverse -transformation of another to produce a single Mapping.} - - The CmpMap forms the key to building arbitrarily complex Mappings - because it is itself a form of Mapping. This means that a CmpMap may - contain other CmpMaps as components - (\emph{e.g.}\ Figure~\ref{fig:complexcmpmap}). This nesting of CmpMaps - can be repeated indefinitely, so that complex Mappings may be built in - a hierarchical manner out of simper ones. - \begin{figure} - \begin{center} - \includegraphics[width=0.65\textwidth]{sun211_figures/complex} - \caption[CmpMaps may be nested in order to - construct complex Mappings out of simpler building blocks.]{CmpMaps - (compound Mappings) may be nested in order to - construct complex Mappings out of simpler building blocks.} - \label{fig:complexcmpmap} - \end{center} - \end{figure} - This gives AST great flexibility in the coordinate transformations it - can describe. - -\textbf{Further reading:} For a more complete description of CmpMaps, -see \secref{ss:cmpmaps}. Also see the CmpMap entry in -\appref{ss:classdescriptions}. - -\subsection{Representing Coordinate Systems} - - While Mappings (\secref{ss:mappingoverview}) represent the - relationships between coordinate systems in AST, the coordinate - systems themselves are represented by Objects called Frames - (Figure~\ref{fig:frames}). - \begin{figure} - \begin{center} - \includegraphics[width=0.55\textwidth]{sun211_figures/frames} - \caption[Representing coordinate systems as Frames.]{(a) A basic Frame is used to represent a Cartesian coordinate - system, here 2-dimensional. (b) A \htmlref{SkyFrame}{SkyFrame} represents a (spherical) - celestial coordinate system. (c) The axis order of any \htmlref{Frame}{Frame} may be - permuted to match the coordinate space it describes.} - \label{fig:frames} - \end{center} - \end{figure} - -A Frame is similar in concept to the frame you might draw around a -graph. It contains information about the labels which appear on the -axes, the axis units, a title, knowledge of how to format the -coordinate values on each axis, \emph{etc.} An AST Frame is not, -however, restricted to two dimensions and may have any number of axes. - -A basic Frame may be used to represent a Cartesian coordinate system -by setting values for its \emph{attributes} (all AST Objects have -values associated with them called attributes, which may be set and -enquired). Usually, this would involve setting appropriate axis -labels and units, for example. Functions are provided for use with -Frames to perform operations such as formatting coordinate values as -text, calculating distances between points, interchanging axes, -\emph{etc.} - -There are several more specialised forms of Frame, which provide the -additional functionality required when handling coordinates within some -specific physical domain. This ranges from tasks such as formatting axis -values, to complex tasks such as determining the transformation between -any pair of related coordinate systems. For instance, the SkyFrame -(Figure~\ref{fig:frames}b,c), represents celestial coordinate systems, -the \htmlref{SpecFrame}{SpecFrame} represents spectral coordinate systems, and the \htmlref{TimeFrame}{TimeFrame} -represents time coordinate systems. All these provide a wide range of -different systems for describing positions within their associated physical -domain, and these may be selected by setting appropriate attributes. - - As with compound Mappings (\secref{ss:cmpmapoverview}), it is possible - to merge two Frames together to form a compound Frame, or \htmlref{CmpFrame}{CmpFrame}, in - which both sets of axes are combined. One could, for example, have - celestial coordinates on two axes and an unrelated coordinate - (wavelength, perhaps) on a third (Figure~\ref{fig:cmpframe}). - Knowledge of the relationships between the axes is preserved - internally by the process of constructing the CmpFrame which - represents them. - \begin{figure} - \begin{center} - \includegraphics[width=0.4\textwidth]{sun211_figures/cmpframe} - \caption[A CmpFrame (compound Frame) formed by combining two simpler - Frames.]{A CmpFrame (compound Frame) formed by combining two simpler - Frames. Note how the special relationship which exists between the RA - and Dec axes is preserved within this data structure. As with compound - Mappings (Figure~\ref{fig:complexcmpmap}), CmpFrames may be nested in - order to build more complex Frames.} - \label{fig:cmpframe} - \end{center} - \end{figure} - -\textbf{Further reading:} For a more complete description of Frames see -\secref{ss:frames}, for SkyFrames see \secref{ss:skyframes} and for -SpecFrames see \secref{ss:specframes}. Also see the Frame, SkyFrame, -SpecFrame, TimeFrame and CmpFrame entries in \appref{ss:classdescriptions}. - -\subsection{Networks of Coordinate Systems} - - Mappings and Frames may be connected together to form networks called - FrameSets, which are used to represent sets of inter-related - coordinate systems (Figure~\ref{fig:frameset}). - \begin{figure} - \begin{center} - \includegraphics[width=0.65\textwidth]{sun211_figures/frameset} - \caption[A FrameSet is a network of Frames.]{A FrameSet is a network of Frames inter-connected by Mappings - such that there is exactly one conversion path, \emph{via} Mappings, - between any pair of Frames.} - \label{fig:frameset} - \end{center} - \end{figure} - - -A \htmlref{FrameSet}{FrameSet} may be extended by adding a new \htmlref{Frame}{Frame} to it, together with -an associated \htmlref{Mapping}{Mapping} which relates the new coordinate system to one -which is already present. This process ensures that there is always -exactly one path, \emph{via} Mappings, between any pair of Frames. A -function is provided for identifying this path and returning the -complete Mapping. - -One of the Frames in a FrameSet is termed its \emph{base} Frame. This -underlies the FrameSet's purpose, which is to calibrate datasets and -other entities by attaching coordinate systems to them. In this -context, the base Frame represents the ``native'' coordinate system -(for example, the pixel coordinates of an image). Similarly, one -Frame is termed the \emph{current} Frame and represents the -``currently-selected'' coordinates. It might, typically, be a -celestial or spectral coordinate system and would be used during -interactions with -a user, as when plotting axes on a graph or producing a table of -results. Other Frames within the FrameSet represent a library of -alternative coordinate systems which a software user can select by -making them current. - -\textbf{Further reading:} For a more complete description of -FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. Also -see the FrameSet entry in \appref{ss:classdescriptions}. - -\subsection{Input/Output Facilities} - -AST allows you to convert any kind of \htmlref{Object}{Object} into a stream of text -which contains a full description of that Object. This text may be -written out by one program and read back in by another, thus allowing -the original Object to be reconstructed. - -The filter which converts Objects into text and back again is itself a -kind of Object, called a \htmlref{Channel}{Channel}. A Channel provides a number of -options for controlling the information content of the text, such as -the addition of comments for human interpretation. It is also -possible to intercept the text being processed by a Channel so that it -may be redirected to/from any chosen external data store, such as a -text file, an astronomical dataset, or a network connection. - -The text format used by the basic Channel class is peculiar to the AST -library - no other software will understand it. However, more specialised -forms of Channel are provided which use text formats more widely -understood. - -To further facilitate the storage of coordinate system information in -astronomical datasets, a more specialised form of Channel called a -\htmlref{FitsChan}{FitsChan} is provided. Instead of using free-format text, a FitsChan -converts AST Objects to and from FITS header cards. It also allows the -information to be encoded in the FITS cards in a number of ways -(called \emph{encodings}), so that WCS information from a variety of -sources can be handled. - -Another sub-class of Channel, called \htmlref{XmlChan}{XmlChan}, is a specialised form of -Channel that stores the text in the form of XML markup. Currently, two -markup formats are provided by the XmlChan class, one is closely related -to the text format produced by the basic Channel class (currently, no -schema or DTD is available describing this format). The other is a subset -of an early draft of the IVOA Space-Time-Coordinates XML (STC-X) schema -(V1.20) described at -\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html -}\footnote{XML documents which use only the subset of the STC schema -supported by AST can be read by the XmlChan class to produce -corresponding AST objects (subclasses of the \htmlref{Stc}{Stc} class). However, the -reverse is not possible. That is, AST objects can not currently be -written out in the form of STC documents.}. The version of STC-X that has -been adopted by the IVOA differs in several significant respects from -V1.20, and therefore this XmlChan format is of historical interest only. - -Finally, the \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing -IVOA STC-S region descriptions. STC-S (see -\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string -syntax that allows simple specification of STC metadata. AST supports a -subset of the STC-S specification, allowing an STC-S description of a -region within an AST-supported astronomical coordinate system to be converted -into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. - -\textbf{Further reading:} For a more complete description of Channels -see \secref{ss:channels} and for FitsChans see \secref{ss:nativefits} -and \secref{ss:foreignfits}. Also see the Channel and FitsChan entries -in \appref{ss:classdescriptions} and the \htmlref{Encoding}{Encoding} entry in -\appref{ss:attributedescriptions}. - -\subsection{Producing Graphical Output} - -Two dimensional graphical output is supported by a specialised form of -\htmlref{FrameSet}{FrameSet} called -a \htmlref{Plot}{Plot}, whose base \htmlref{Frame}{Frame} corresponds with the native coordinates of -the underlying graphics system. Plotting operations are specified in -\emph{physical coordinates} which correspond with the Plot's current -Frame. Typically, this might be a celestial coordinate system. - -Three dimensional plotting is also supported, via the \htmlref{Plot3D}{Plot3D} class - -sub-class of Plot. - -Operations, such as drawing lines, are automatically transformed from -physical to graphical coordinates before plotting, using an adaptive -algorithm which ensures smooth curves (because the transformation is -usually non-linear). ``Missing'' coordinates (\emph{e.g.}\ graphical -coordinates which do not project on to the celestial sphere), -discontinuities and generalised clipping are all consistently handled. -It is possible, for example, to plot in equatorial coordinates and -clip in galactic coordinates. The usual plotting operations are -provided (text, markers), but a geodesic curve replaces the primitive -straight line element. There is also a separate function for drawing -axis lines, since these are normally not geodesics. - -In addition to drawing coordinate grids over an area of the sky, another -common use of the Plot class is to produce line plots such as flux -against wavelength, displacement again time, \emph{etc}. For these -situations the current Frame of the Plot would be a compound Frame -(\htmlref{CmpFrame}{CmpFrame}) containing a pair of 1-dimensional Frames - the first -representing the X axis quantity (wavelength, time, etc), and the second -representing the Y axis quantity (flux, displacement, etc). The Plot -class includes an option for axes to be plotted logarithmically. - - Perhaps the most useful graphics function available is for drawing - fully annotated coordinate grids (\emph{e.g.}\ Figure~\ref{fig:gridplot}). - \begin{figure} - \begin{center} - \includegraphics[width=0.6\textwidth]{sun211_figures/gridplot_bw} - \caption[A labelled coordinate grid for an all-sky zenithal equal area - projection in ecliptic coordinates.]{A labelled coordinate grid for an all-sky zenithal equal area - projection in ecliptic coordinates. This was composed and drawn - \emph{via} a Plot using a - single function call.} - \label{fig:gridplot} - \end{center} - \end{figure} - -This uses a general algorithm which does not depend on knowledge of -the coordinates being represented, so can also handle -programmer-defined coordinate systems. Grids for all-sky projections, -including polar regions, can be drawn and most aspects of the output -(colour, line style, \emph{etc.}) can be adjusted by setting -appropriate Plot attributes. - -\textbf{Further reading:} For a more complete description of -Plots and how to produce graphical output, see \secref{ss:plots}. Also -see the Plot entry in \appref{ss:classdescriptions}. - -\cleardoublepage -\section{\label{ss:howto}How To\ldots} - -For those of you with a plane to catch, this section provides some -instant templates and recipes for performing the most -commonly-required operations using AST, but without going into -detail. The examples given (sort of) follow on from each other, so you -should be able to construct a variety of programs by piecing them -together. Note that some of them appear longer than they actually -are, because we have included plenty of comments and a few options -that you probably won't need. - -If any of this material has you completely baffled, then you may want -to read the introduction to AST programming concepts in -\secref{ss:primer} first. Otherwise, references to more detailed -reading are given after each example, just in case they don't quite do -what you want. - -\subsection{\ldots Obtain and Install AST} -The AST library is available both as a stand-alone package and also as -part of the Starlink Software Collection\footnote{The Starlink Software -Collection can be downloaded from -\url{http://www.starlink.ac.uk/Download/}.}. If your site has the Starlink -Software Collection installed then AST should already be available. - -If not, you can download the AST library by itself from -\url{http://www.starlink.ac.uk/ast/}. - -\subsection{\ldots Structure an AST Program} - -An AST program normally has the following structure: - -\begin{small} -\begin{terminalv} -/* Include the interface to the AST library. */ -#include "ast.h" - -/* Main program (or could be any function). */ -main () { - <normal C declarations and statements> - -/* Enclose the parts which use AST between the astBegin and astEnd macros. */ - astBegin; - <C statements which use AST> - astEnd; - - <maybe more C statements> -} -\end{terminalv} -\end{small} - -The use of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} is optional, but has the effect of -tidying up after you have finished using AST, so is normally -recommended. For more details of this, see \secref{ss:contexts}. For -details of how to access the ``ast.h'' header file, see -\secref{ss:accessingheaderfile}. - -\subsection{\label{ss:howtobuild}\ldots Build an AST Program} - -To build a simple AST program that doesn't use graphics, use: - -\begin{small} -\begin{terminalv} -cc program.c -L/star/lib -I/star/include `ast_link` -o program -\end{terminalv} -\end{small} - -To build a program which uses PGPLOT for graphics, use: - -\begin{small} -\begin{terminalv} -cc program.c -L/star/lib `ast_link -pgplot` -o program -\end{terminalv} -\end{small} - -For more details about accessing the ``ast.h'' header file, see -\secref{ss:accessingheaderfile}. For more -details about linking programs, see \secref{ss:linking} and the -description of the ``\htmlref{ast\_link}{ast\_link}'' command in -\appref{ss:commanddescriptions}. - -\subsection{\label{ss:howtoreadwcs}\ldots Read a WCS Calibration from a Dataset} - -Precisely how you extract world coordinate system (WCS) information -from a dataset obviously depends on what type of dataset it -is. Usually, however, you should be able to obtain a set of FITS -header cards which contain the WCS information (and probably much more -besides). Suppose that ``cards'' is a pointer to a string -containing a complete set of concatenated FITS header cards (such as -produced by the CFITSIO function fits\_hdr2str). Then proceed as follows: - -\begin{small} -\begin{terminalv} -fitsfile *fptr; -AstFitsChan *fitschan; -AstFrameSet *wcsinfo; -char *header; -int nkeys, status; - -... - -/* Obtain all the cards in the header concatenated into a single dynamically - allocated null-terminated character string. Note, we do not exclude - any cards since we may later modify the WCS information within the - header and consequently want to write the entire header out again. */ - if( fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) - printf(" Error getting header\n"); - ... - -/* Header obtained succesfully... */ - } else { - -/* Create a FitsChan and fill it with FITS header cards. */ - fitschan = astFitsChan( NULL, NULL, "" ); - astPutCards( fitschan, header ); - -/* Free the memory holding the concatenated header cards. */ - header = free( header ); - -/* Read WCS information from the FitsChan. */ - wcsinfo = astRead( fitschan ); - - ... - -\end{terminalv} -\end{small} - - -The result should be a pointer, ``wcsinfo'', to a \htmlref{FrameSet}{FrameSet} which -contains the WCS information. This pointer can now be used to perform -many useful tasks, some of which are illustrated in the following -recipes. - -Some datasets which do not easily yield FITS header cards may require -a different approach, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} -(\secref{ss:channels}) rather than a \htmlref{FitsChan}{FitsChan}. In the case of the -Starlink NDF data format, for example, all the above may be replaced -by a single call to the function -\xref{ndfGtwcs}{sun33}{ndfGtwcs}---see \xref{SUN/33}{sun33}{}. The -whole process can probably be encapsulated in a similar way for -most data systems, whether they use FITS header cards or not. - -For more details about reading WCS information from datasets, see -\secref{ss:identifyingfitsencoding} and -\secref{ss:readingforeignfits}. For a more general description of -FitsChans and their use with FITS header cards, see -\secref{ss:nativefits} and \secref{ss:foreignfits}. For more details -about FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. - -\subsection{\ldots Validate WCS Information} - -Once you have read WCS information from a dataset, as in -\secref{ss:howtoreadwcs}, you may wish to check that you have been -successful. The following will detect and classify the things that -might possibly go wrong: - -\begin{small} -\begin{terminalv} -#include <string.h> - -... - -if ( !astOK ) { - <an error occurred (a message will have been issued)> -} else if ( wcsinfo == AST__NULL ) { - <there was no WCS information present> -} else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { - <something unexpected was read (i.e. not a FrameSet)> -} else { - <WCS information was read OK> -} -\end{terminalv} -\end{small} - -For more information about detecting errors in AST functions, see -\secref{ss:errordetection}. For details of how to validate input data -read by AST, see \secref{ss:validatinginput} and -\secref{ss:readingforeignfits}. - -\subsection{\ldots Display AST Data} - -If you have a pointer to any AST \htmlref{Object}{Object}, you can display the data -stored in that Object in textual form as follows: - -\begin{small} -\begin{terminalv} -astShow( wcsinfo ); -\end{terminalv} -\end{small} - -Here, we have used a pointer to the \htmlref{FrameSet}{FrameSet} which we read earlier -(\secref{ss:howtoreadwcs}). The result is written to the program's -standard output stream. This can be very useful during debugging. - -For more details about using \htmlref{astShow}{astShow}, see -\secref{ss:displayingobjects}. For information about interpreting the -output, also see \secref{ss:textualoutputformat}. - -\subsection{\label{ss:howtotransform}\ldots Convert Between Pixel and World Coordinates} - -You may use a pointer to a \htmlref{FrameSet}{FrameSet}, such as we read in -\secref{ss:howtoreadwcs}, to transform a set of points between the -pixel coordinates of an image and the associated world coordinates. If -you are working in two dimensions, proceed as follows: - -\begin{small} -\begin{terminalv} -double xpixel[ N ], ypixel[ N ]; -double xworld[ N ], yworld[ N ]; - -... - -astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); -\end{terminalv} -\end{small} - -Here, N is the number of points to be transformed, ``xpixel'' and -``ypixel'' hold the pixel coordinates, and ``xworld'' and ``yworld'' -receive the returned world coordinates.\footnote{By pixel coordinates, -we mean a coordinate system in which the first pixel in the image is -centred on (1,1) and each pixel is a unit square. Note that the world -coordinates will not necessarily be celestial coordinates, but if they -are, then they will be in radians.} To transform in the opposite -direction, interchange the two pairs of arrays (so that the world -coordinates are given as input) and change the fifth argument of -\htmlref{astTran2}{astTran2} to zero. - -To transform points in one dimension, use \htmlref{astTran1}{astTran1}. In any other -number of dimensions (or if the number of dimensions is initially -unknown), use \htmlref{astTranN}{astTranN} or \htmlref{astTranP}{astTranP}. These functions are described in -\appref{ss:functiondescriptions}. - -For more information about transforming coordinates, see -\secref{ss:transforming} and \secref{ss:framesetasmapping}. For -details of how to handle missing coordinates, see -\secref{ss:badcoordinates}. - -\subsection{\label{ss:howtotestforcelestial}\ldots Test if a WCS is a Celestial Coordinate System} - -The world coordinate system (WCS) currently associated with an image -may often be a celestial coordinate system, but this need not -necessarily be the case. For instance, instead of right ascension and -declination, an image might have a WCS with axes representing -wavelength and slit position, or maybe just plain old pixels. - -If you have obtained a WCS calibration for an image, as in -\secref{ss:howtoreadwcs}, in the form of a pointer ``wcsinfo'' to a -\htmlref{FrameSet}{FrameSet}, then you may determine if the current coordinate system is a -celestial one or not, as follows: - -\begin{small} -\begin{terminalv} -AstFrame *frame; -int issky; - -... - -/* Obtain a pointer to the current Frame and determine if it is a - SkyFrame. */ -frame = astGetFrame( wcsinfo, AST__CURRENT ); -issky = astIsASkyFrame( frame ); -frame = astAnnul( frame ); -\end{terminalv} -\end{small} - -This will set ``issky'' to 1 if the WCS is a celestial coordinate -system, and to zero otherwise. - -\subsection{\label{ss:howtotestforspectral}\ldots Test if a WCS is a Spectral Coordinate System} -Testing for a spectral coordinate system is basically the same as testing -for a celestial coordinate system (see the previous section). The one -difference is that you use the -astIsASpecFrame function -in place of the -astIsASkyFrame function. - -\subsection{\label{ss:howtoformatcoordinates}\ldots Format Coordinates for Display} - -Once you have converted pixel coordinates into world coordinates -(\secref{ss:howtotransform}), you may want to format them as text -before displaying them. Typically, this would convert from (say) -radians into something more comprehensible. Using the \htmlref{FrameSet}{FrameSet} pointer -``wcsinfo'' obtained in \secref{ss:howtoreadwcs} and a pair of world -coordinates ``xw'' and ``yw'' (\emph{e.g.}\ see -\secref{ss:howtotransform}), you could proceed as follows: - -\begin{small} -\begin{terminalv} -#include <stdio.h> -const char *xtext, *ytext; -double xw, yw; - -... - -xtext = astFormat( wcsinfo, 1, xw ); -ytext = astFormat( wcsinfo, 2, yw ); - -(void) printf( "Position = %s, %s\n", xtext, ytext ); -\end{terminalv} -\end{small} - -Here, the second argument to \htmlref{astFormat}{astFormat} is the axis number. - -With celestial coordinates, this will usually result in sexagesimal -notation, such as ``12:34:56.7''. However, the same method may be -applied to any type of coordinates and appropriate formatting will be -employed. - -For more information about formatting coordinate values and how to -control the style of formatting used, see -\secref{ss:formattingaxisvalues} and -\secref{ss:formattingskyaxisvalues}. If necessary, also see -\secref{ss:normalising} for details of how to ``normalise'' a set of -coordinates so that they lie within the standard range (\emph{e.g.}\ 0 -to 24 hours for right ascension and $\pm 90^\circ$ for -declination). - -\subsection{\ldots Display Coordinates as they are Transformed} - -In addition to formatting coordinates as part of a program's output, -you may also want to examine coordinate values while debugging your -program. To save time, you can ``eavesdrop'' on the coordinate values -being processed every time they are transformed. For example, when -using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in -\secref{ss:howtoreadwcs} to transform coordinates -(\secref{ss:howtotransform}), you could inspect the coordinate values -as follows: - -\begin{small} -\begin{terminalv} -astSet( wcsinfo, "Report=1" ); -astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld ); -\end{terminalv} -\end{small} - -By setting the FrameSet's \htmlref{Report}{Report} attribute to 1, coordinate -transformations are automatically displayed on the program's standard -output stream, appropriately formatted, for example: - -\begin{terminalv} -(42.1087, 20.2717) --> (2:06:03.0, 34:22:39) -(43.0197, 21.1705) --> (2:08:20.6, 35:31:24) -(43.9295, 22.0716) --> (2:10:38.1, 36:40:09) -(44.8382, 22.9753) --> (2:12:55.6, 37:48:55) -(45.7459, 23.8814) --> (2:15:13.1, 38:57:40) -(46.6528, 24.7901) --> (2:17:30.6, 40:06:25) -(47.5589, 25.7013) --> (2:19:48.1, 41:15:11) -(48.4644, 26.6149) --> (2:22:05.6, 42:23:56) -(49.3695, 27.5311) --> (2:24:23.1, 43:32:41) -(50.2742, 28.4499) --> (2:26:40.6, 44:41:27) -\end{terminalv} - -For a complete description of the Report attribute, see its entry in -\appref{ss:attributedescriptions}. For further details of how to set -and enquire attribute values, see \secref{ss:settingattributes} and -\secref{ss:gettingattributes}. - -\subsection{\ldots Read Coordinates Entered by a User} - -In addition to writing out coordinate values generated by your program -(\secref{ss:howtoformatcoordinates}), you may also need to accept -coordinates entered by a user, or perhaps read from a file. In this -case, you will probably want to allow ``free-format'' input, so that -the user has some flexibility in the format that can be used. You will -probably also want to detect any typing errors. - -Let's assume that you want to read a number of lines of text, each -containing the world coordinates of a single point, and to split each -line into individual numerical coordinate values. Using the \htmlref{FrameSet}{FrameSet} -pointer ``wcsinfo'' obtained earlier (\secref{ss:howtoreadwcs}), you -could proceed as follows: - -\begin{small} -\begin{terminalv} -#include <stdio.h> -char *t; -char text[ MAXCHARS + 2 ]; -double coord[ 10 ]; -int iaxis, n, naxes; - -... - -/* Obtain the number of coordinate axes (if not already known). */ -naxes = astGetI( wcsinfo, "Naxes" ); - -/* Loop to read each line of input text, in this case from the - standard input stream (your programming environment will probably - provide a better way of reading text than this). Set the pointer - "t" to the start of each line read. */ -while ( t = fgets( text, MAXCHARS + 2, stdin ) ) { - -/* Attempt to read a coordinate for each axis. */ - for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { - n = astUnformat( wcsinfo, iaxis, t, &coord[ iaxis - 1 ] ); - -/* If nothing was read and this is not the first axis or the - end-of-string, try stepping over a separator and reading again. */ - if ( !n && ( iaxis > 1 ) && *t ) - n = astUnformat( wcsinfo, iaxis, ++t, &coord[ iaxis - 1 ] ); - -/* Quit if nothing was read, otherwise move on to the next coordinate. */ - if ( !n ) break; - t += n; - } - -/* Test for the possible errors that may occur... */ - -/* Error detected by AST (a message will have been issued). */ - if ( !astOK ) { - break; - -/* Error in input data at character t[n]. */ - } else if ( *t || !n ) { - <handle the error, or report your own message here> - break; - - } else { - <coordinates were read OK> - } -} -\end{terminalv} -\end{small} - -This algorithm has the advantage of accepting free-format input in -whatever style is appropriate for the world coordinates in use (under -the control of the FrameSet whose pointer you provide). For example, -wavelength values might be read as floating point numbers -(\emph{e.g.}\ ``1.047'' or ``4787''), whereas celestial positions -could be given in sexagesimal format (\emph{e.g.}\ ``12:34:56'' or -``12~34.5'') and would be converted into radians. Individual -coordinate values may be separated by white space and/or any -non-ambiguous separator character, such as a comma. - -For more information on reading coordinate values using the -\htmlref{astUnformat}{astUnformat} function, see \secref{ss:unformattingaxisvalues}. For -details of how sexagesimal formats are handled, and the forms of input -that may be used for celestial coordinates, see -\secref{ss:unformattingskyaxisvalues}. - -\subsection{\label{ss:howtocreatenewwcs}\ldots Create a New WCS Calibration} - -This section describes how to add a WCS calibration to a data set which you -are creating from scratch, rather than modifying an existing data set. - -In most common cases, the simplest way to create a new WCS calibration -from scratch is probably to create a set of strings describing the -required calibration in terms of the keywords used by the FITS WCS -standard, and then convert these strings into an AST \htmlref{FrameSet}{FrameSet} describing -the calibration. This FrameSet can then be used for many other purposes, or -simply stored in the data set. - -The full FITS-WCS standard is quite involved, currently running to four -separate papers, but the basic kernel is quite simple, involving the -following keywords (all of which end with an integer axis index, -indicated below by $<i>$): - -\begin{description} -\item[CRPIX<i>]\mbox{}\\ -hold the pixel coordinates at a reference point -\item[CRVAL<i>]\mbox{}\\ -hold the corresponding WCS coordinates at the reference point -\item[CTYPE<i>]\mbox{}\\ -name the quantity represented by the WCS axes, together with the -projection algorithm used to convert the scaled and rotated pixel coordinates -to WCS coordinates. -\item[CD<i>\_<j>]\mbox{}\\ -a set of keywords which specify the elements of a matrix. This matrix scales -pixel offsets from the reference point into the offsets required as input -by the projection algorithm specified by the CTYPE keywords. This matrix -specifies the scale and rotation of the image. If there is no rotation -the off-diagonal elements of the matrix (\emph{e.g.} CD1\_2 and -CD2\_1) can be omitted. -\end{description} - -As an example consider the common case of a simple 2D image of the sky in -which north is parallel to the second pixel axis and east parallel to the -(negative) first pixel axis. The image scale is 1.2 arc-seconds per pixel -on both axes, and the image is presumed to have been obtained with a -tangent plane projection. Furthermore, it is known that pixel coordinates -(100.5,98.4) correspond to an RA of 11:00:10 and a Dec. of -23:26:02. -A suitable set of FITS-WCS header cards could be: - -\begin{small} -\begin{terminalv} -CTYPE1 = 'RA---TAN' / Axis 1 represents RA with a tan projection -CTYPE2 = 'DEC--TAN' / Axis 2 represents Dec with a tan projection -CRPIX1 = 100.5 / Pixel coordinates of reference point -CRPIX2 = 98.4 / Pixel coordinates of reference point -CRVAL1 = 165.04167 / Degrees equivalent of "11:00:10" hours -CRVAL2 = -23.433889 / Decimal equivalent of "-23:26:02" degrees -CD1_1 = -0.0003333333 / Decimal degrees equivalent of -1.2 arc-seconds -CD2_2 = 0.0003333333 / Decimal degrees equivalent of 1.2 arc-seconds -\end{terminalv} -\end{small} - -Notes: -\begin{itemize} -\item a FITS header card begins with the keyword name starting at column 1, -has an equals sign in column 9, and the keyword value in columns 11 to 80. -\item string values must be enclosed in single quotes. -\item celestial longitude and latitude must both be specified in decimal degrees. -\item the CD1\_1 value is negative to indicate that RA increases as the -first pixel axis decreases. -\item the (RA,Dec) coordinates will be taken as ICRS coordinates. For FK5 -you should add: - -\begin{small} -\begin{terminalv} -RADESYS = 'FK5' -EQUINOX = 2005.6 -\end{terminalv} -\end{small} - -The EQUINOX value defaults to J2000.0 if omitted. FK4 can also be used in -place of FK5, in which case EQUINOX defaults to B1950.0. - -\end{itemize} - -Once you have created these FITS-WCS header card strings, you should -store them in a \htmlref{FitsChan}{FitsChan} and then read the corresponding FrameSet from the -FitsChan. How to do this is described in \secref{ss:howtoreadwcs}. - -Having created the WCS calibration, you may want to store it in a data -file. How to do this is described in \secref{ss:howtowritewcs}).\footnote{If -you are writing the WCS calibration to a FITS file you obviously -have the choice of storing the FITS-WCS cards directly.} - -If the required WCS calibration cannot be described as a set of FITS-WCS -headers, then a different approach is necessary. In this case, you should -first create a \htmlref{Frame}{Frame} describing pixel coordinates, and store this Frame -in a new FrameSet. You should then create a new Frame describing the -world coordinate system. This Frame may be a specific subclass of Frame such -as a \htmlref{SkyFrame}{SkyFrame} for celestial coordinates, a \htmlref{SpecFrame}{SpecFrame} for spectral -coordinates, a Timeframe for time coordinates, or a \htmlref{CmpFrame}{CmpFrame} for a combination -of different coordinates. -You also need to create a suitable \htmlref{Mapping}{Mapping} which transforms pixel -coordinates into world coordinates. AST provides many different types of -Mappings, all of which can be combined together in arbitrary fashions to -create more complicated Mappings. The WCS Frame should then be added into -the FrameSet, using the Mapping to connect the WCS Frame with the pixel -Frame. - -\subsection{\label{ss:howtomodifywcs}\ldots Modify a WCS Calibration} - -The usual reason for wishing to modify the WCS calibration associated -with a dataset is that the data have been geometrically transformed in -some way (here, we will assume a 2-dimensional image dataset). This -causes the image features (stars, galaxies, \emph{etc.}) to move with -respect to the grid of pixels which they occupy, so that any -coordinate systems previously associated with the image become -invalid. - -To correct for this, it is necessary to set up a \htmlref{Mapping}{Mapping} which -expresses the positions of image features in the new data grid in -terms of their positions in the old grid. In both cases, the grid -coordinates we use will have the first pixel centred at (1,1) with -each pixel being a unit square. - -AST allows you to correct for any type of geometrical transformation -in this way, so long as a suitable Mapping to describe it can be -constructed. For purposes of illustration, we will assume here that -the new image coordinates ``xnew'' and ``ynew'' can be expressed in -terms of the old coordinates ``xold'' and ``yold'' as follows: - -\begin{small} -\begin{terminalv} -double xnew, xold, ynew, yold; -double m[ 4 ], z[ 2 ]; - -... - -xnew = xold * m[ 0 ] + yold * m[ 1 ] + z[ 0 ]; -ynew = xold * m[ 2 ] + yold * m[ 3 ] + z[ 1 ]; -\end{terminalv} -\end{small} - -where ``m'' is a 2$\times$2 transformation matrix and ``z'' represents -a shift of origin. This is therefore a general linear coordinate -transformation which can represent displacement, rotation, -magnification and shear. - -In AST, it can be represented by concatenating two Mappings. The first -is a \htmlref{MatrixMap}{MatrixMap}, which implements the matrix multiplication. The second -is a \htmlref{WinMap}{WinMap}, which linearly transforms one coordinate window on to -another, but will be used here simply to implement the shift of -origin (alternatively, a \htmlref{ShiftMap}{ShiftMap} could have been used in place of a -WinMap). These Mappings may be constructed and concatenated as follows: - -\begin{small} -\begin{terminalv} -AstCmpMap *newmap; -AstMatrixMap *matrixmap; -AstWinMap *winmap; - -... - -/* The MatrixMap may be constructed directly from the matrix "m". */ -matrixmap = astMatrixMap( 2, 2, 0, m, "" ); - -/* For the WinMap, we set up the coordinates of the corners of a unit - square (window) and then the same square shifted by the required - amount. */ -{ - double ina[] = { 0.0, 0.0 }; - double inb[] = { 1.0, 1.0 }; - double outa[] = { z[ 0 ], z[ 1 ] }; - double outb[] = { 1.0 + z[ 0 ], 1.0 + z[ 1 ] }; - -/* The WinMap will then implement this shift. */ - winmap = astWinMap( 2, ina, inb, outa, outb, "" ); -} - -/* Join the two Mappings together, so that they are applied one after - the other. */ -newmap = astCmpMap( matrixmap, winmap, 1, "" ); -\end{terminalv} -\end{small} - -You might, of course, create any other form of Mapping depending on -the type of geometrical transformation involved. For an overview of -the Mappings provided by AST, see \secref{ss:mappingselection}, and -for a description of the capabilities of each class of Mapping, see -its entry in \appref{ss:classdescriptions}. For an overview of how -individual Mappings may be combined, see \secref{ss:cmpmapoverview} -(\secref{ss:cmpmaps} gives more details). - -Assuming you have obtained a WCS calibration for your original image -in the form of a pointer to a \htmlref{FrameSet}{FrameSet}, ``wcsinfo1'' -(\secref{ss:howtoreadwcs}), the Mapping created above may be used to -produce a calibration for the new image as follows: - -\begin{small} -\begin{terminalv} -AstFrameSet *wcsinfo1, *wcsinfo2; - -... - -/* If necessary, make a copy of the WCS calibration, since we are - about to alter it. */ -wcsinfo2 = astCopy( wcsinfo1 ); - -/* Re-map the base Frame so that it refers to the new data grid - instead of the old one. */ -astRemapFrame( wcsinfo2, AST__BASE, newmap ); -\end{terminalv} -\end{small} - -This will produce a pointer, ``wcsinfo2'', to a new FrameSet in which -all the coordinate systems associated with your original image are -modified so that they are correctly registered with the new image -instead. - -For more information about re-mapping the Frames within a FrameSet, -see \secref{ss:remapframe}. Also see \secref{ss:wcsprocessingexample} -for a similar example to the above, applicable to the case of reducing -the size of an image by binning. - -\subsection{\label{ss:howtowritewcs}\ldots Write a Modified WCS Calibration to a Dataset} - -If you have modified the WCS calibration associated with a dataset, -such as in the example above (\secref{ss:howtomodifywcs}), then you -will need to write the modified version out along with any new data. - -In the same way as when reading a WCS calibration -(\secref{ss:howtoreadwcs}), how you do this will depend on your data -system, but we will assume that you wish to generate a set of FITS -header cards that can be stored with the data. You should usually make -preparations for doing this when you first read the WCS calibration -from your input dataset by modifying the example given in -\secref{ss:howtoreadwcs} as follows: - -\begin{small} -\begin{terminalv} -AstFitsChan *fitschan1; -AstFrameSet *wcsinfo1; -const char *encode; - -... - -/* Create an input FitsChan and fill it with FITS header cards. Note, - if you have all the header cards in a single string, use astPutCards in - place of astPutFits. */ -fitschan1 = astFitsChan( NULL, NULL, "" ); -for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan1, cards[ icard ], 0 ); - -/* Note which encoding has been used for the WCS information. */ -encode = astGetC( fitschan1, "Encoding" ); - -/* Rewind the input FitsChan and read the WCS information from it. */ -astClear( fitschan1, "Card" ); -wcsinfo1 = astRead( fitschan1 ); -\end{terminalv} -\end{small} - -Note how we have added an enquiry to determine how the WCS information -is encoded in the input FITS cards, storing a pointer to the resulting -string in the ``encode'' variable. This must be done \textbf{before} -actually reading the WCS calibration. - -\emph{(\textbf{N.B.}\ If you will be making extensive use of astGetC in -your program, then you should allocate a buffer and make a copy of -this string, because the pointer returned by astGetC will only remain -valid for 50 invocations of the function, and you will need to use the -\htmlref{Encoding}{Encoding} value again later on.)} - -Once you have produced a modified WCS calibration for the output -dataset (\emph{e.g.}\ \secref{ss:howtomodifywcs}), in the form of a -\htmlref{FrameSet}{FrameSet} identified by the pointer ``wcsinfo2'', you can produce a new -\htmlref{FitsChan}{FitsChan} containing the output FITS header cards as follows: - -\small -\begin{terminalv} -AstFitsChan *fitschan2; -AstFrameSet *wcsinfo2; - -... - -/* Make a copy of the input FitsChan, AFTER the WCS information has - been read from it. This will propagate all the input FITS header - cards, apart from those describing the input WCS calibration. */ -fitschan2 = astCopy( fitschan1 ); - -/* If necessary, make modifications to the cards in "fitschan2" - (e.g. you might need to change NAXIS1, NAXIS2, etc., to account for - a change in image size). You probably only need to do this if your - data system does not provide these facilities itself. */ -<details not shown - see below> - -/* Alternatively, if your data system handles the propagation of FITS - header cards to the output dataset for you, then simply create an - empty FitsChan to contain the output WCS information alone. -fitschan2 = astFitsChan( NULL, NULL, "" ); -*/ - -/* Rewind the new FitsChan (if necessary) and attempt to write the - output WCS information to it using the same encoding method as the - input dataset. */ -astSet( fitschan2, "Card=1, Encoding=%s", encode ); -if ( !astWrite( fitschan2, wcsinfo2 ) ) { - -/* If this didn't work (the WCS FrameSet has become too complex), then - use the native AST encoding instead. */ - astSet( fitschan2, "Encoding=NATIVE" ); - (void) astWrite( fitschan2, wcsinfo2 ); -} -\end{terminalv} -\normalsize - -For details of how to modify the contents of the output FitsChan in -other ways, such as by adding, over-writing or deleting header cards, -see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and -\secref{ss:findingandchangingfits}. - -Once you have assembled the output FITS cards, you may retrieve them -from the FitsChan that contains them as follows: - -\small -\begin{terminalv} -#include <stdio.h> -char card[ 81 ]; - -... - -astClear( fitschan2, "Card" ); -while ( astFindFits( fitschan2, "%f", card, 1 ) ) (void) printf( "%s\n", card ); -\end{terminalv} -\normalsize - -Here, we have simply written each card to the standard output stream, -but you would obviously replace this with a function invocation to -store the cards in your output dataset. - -For data systems that do not use FITS header cards, a different -approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan} -(\secref{ss:channels}) rather than a FitsChan. In the case of the -Starlink NDF data format, for example, all of the above may be -replaced by a single call to the function -\xref{ndfPtwcs}{sun33}{ndfPtwcs}---see \xref{SUN/33}{sun33}{}. The -whole process can probably be encapsulated in a similar way for most -data systems, whether they use FITS header cards or not. - -For an overview of how to propagate WCS information through data -processing steps, see \secref{ss:propagatingwcsinformation}. For more -information about writing WCS information to FitsChans, see -\secref{ss:writingnativefits} and \secref{ss:writingforeignfits}. For -information about the options for encoding WCS information in FITS -header cards, see \secref{ss:nativeencoding}, -\secref{ss:foreignencodings}, and the description of the Encoding -attribute in \appref{ss:attributedescriptions}. For a complete -understanding of FitsChans and their use with FITS header cards, you -should read \secref{ss:nativefits} and \secref{ss:foreignfits}. - -\subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid} - - A common requirement when displaying image data is to plot an - associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid}) - over the displayed image. - \begin{figure} - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/overgrid_bw} - \caption[An example of a displayed image with a coordinate grid - plotted over it.]{An example of a displayed image with a coordinate grid - plotted over it.} - \label{fig:overgrid} - \end{center} - \end{figure} - -The use of AST in such circumstances is independent of the underlying -graphics system, so starting up the graphics system, setting up a -coordinate system, displaying the image, and closing down afterwards -can all be done using the graphics functions you would normally use. - -However, displaying an image at a precise location can be a little -fiddly with some graphics systems, and obviously the grid drawn by AST -will not be accurately registered with the image unless this is done -correctly. In the following template, we therefore illustrate both -steps, basing the image display on the C interface to the PGPLOT -graphics package.\footnote{An interface is provided with AST that -allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics, -although interfaces to other graphics systems may also be written.} -Plotting a coordinate grid with AST then becomes a relatively minor -part of what is almost a complete graphics program. - -Once again, we assume that a pointer, ``wcsinfo'', to a suitable -\htmlref{FrameSet}{FrameSet} associated with the image has already been obtained -(\secref{ss:howtoreadwcs}). - -\small -\begin{terminalv} -#include "cpgplot.h" -AstPlot *plot; -const float *data; -float hi, lo, scale, x1, x2, xleft, xright, xscale; -float y1, y2, ybottom, yscale, ytop; -int nx, ny; - -... - -/* Access the image data, which we assume has dimension sizes "nx" and - "ny", and will be accessed via the "data" pointer. Also derive - limits for scaling it, which we assign to the variables "hi" and - "lo". */ -<this stage depends on your data system, so is not shown> - -/* Open PGPLOT using the device given by environment variable - PGPLOT_DEV and check for success. */ -if( cpgbeg( 0, " ", 1, 1 ) == 1 ) { - -/* Clear the screen and ensure equal scales on both axes. */ - cpgpage(); - cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f ); - -/* Obtain the extent of the plotting area (not strictly necessary for - PGPLOT, but possibly for other graphics systems). From this, derive - the display scale in graphics units per pixel so that the image - will fit within the display area. */ - cpgqwin( &x1, &x2, &y1, &y2 ); - xscale = ( x2 - x1 ) / nx; - yscale = ( y2 - y1 ) / ny; - scale = ( xscale < yscale ) ? xscale : yscale; - -/* Calculate the extent of the area in graphics units that the image - will occupy, so as to centre it within the display area. */ - xleft = 0.5f * ( x1 + x2 - nx * scale ); - xright = 0.5f * ( x1 + x2 + nx * scale ); - ybottom = 0.5f * ( y1 + y2 - ny * scale ); - ytop = 0.5f * ( y1 + y2 + ny * scale ); - -/* Set up a PGPLOT coordinate transformation matrix and display the - image data as a grey scale map (these details are specific to - PGPLOT). */ - { - float tr[] = { xleft - 0.5f * scale, scale, 0.0f, - ybottom - 0.5f * scale, 0.0f, scale }; - cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr ); - } - -/* BEGINNING OF AST BIT */ -/* ==================== */ -/* Store the locations of the bottom left and top right corners of the - region used to display the image, in graphics coordinates. */ - { - float gbox[] = { xleft, ybottom, xright, ytop }; - -/* Similarly, store the locations of the image's bottom left and top - right corners, in pixel coordinates -- with the first pixel centred - at (1,1). */ - double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 }; - -/* Create a Plot, based on the FrameSet associated with the - image. This attaches the Plot to the graphics surface so that it - matches the displayed image. Specify that a complete set of grid - lines should be drawn (rather than just coordinate axes). */ - plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" ); - } - -/* Optionally, we can now set other Plot attributes to control the - appearance of the grid. The values assigned here use the - colour/font indices defined by the underlying graphics system. */ - astSet( plot, "Colour(grid)=2, Font(textlab)=3" ); - -/* Use the Plot to draw the coordinate grid. */ - astGrid( plot ); - - <maybe some more AST graphics here> - -/* Annul the Plot when finished (or use the astBegin/astEnd technique - shown earlier). */ - plot = astAnnul( plot ); - -/* END OF AST BIT */ -/* ============== */ - -/* Close down the graphics system. */ - cpgend(); -} -\end{terminalv} -\normalsize - -Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a -displayed image, you may also use it to generate further graphical -output of your own, specified in the image's world coordinate system -(such as markers to represent astronomical objects, annotation, -\emph{etc.}). There is also a range of Plot attributes which gives -control over most aspects of the output's appearance. For details of -the facilities available, see \secref{ss:plots} and the description of -the Plot class in \appref{ss:classdescriptions}. - -For details of how to build a graphics program which uses PGPLOT, see -\secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in -\appref{ss:commanddescriptions}. - -\subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid} - -Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid -(\secref{ss:howtoplotgrid}), it is a simple matter to change things so -that the grid represents a different celestial coordinate system. For -example, after creating the Plot with \htmlref{astPlot}{astPlot}, you could use: - -\small -\begin{terminalv} -astSet( plot, "System=Galactic" ); -\end{terminalv} -\normalsize -or: -\small -\begin{terminalv} -astSet( plot, "System=FK5, Equinox=J2010" ); -\end{terminalv} -\normalsize - -and any axes and/or grid drawn subsequently would represent the new -celestial coordinate system you specified. Note, however, that this -will only work if the original grid represented celestial coordinates -of some kind (see \secref{ss:howtotestforcelestial} for how to -determine if this is the case\footnote{Note that the methods applied -to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not, -you will get an error message. - -For more information about the celestial coordinate systems available, -see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in -\appref{ss:attributedescriptions}. - -\subsection{\ldots Give a User Control Over the Appearance of a Plot} - -The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the -graphical output it produces (\secref{ss:howtoplotgrid} and -\secref{ss:howtoswitchgrid}) can easily be extended to allow the user -of a program complete control over such matters. - -For instance, if the file ``plot.config'' contains a series of -plotting options in the form of Plot attribute assignments (see below -for an example), then we could create a Plot and implement these -assignments before producing the graphical output as follows: - -\small -\begin{terminalv} -#include <stdio.h> -#define MAXCHARS 120 -FILE *stream; -char line[ MAXCHARS + 2 ]; -int base; - -... - -/* Create a Plot and define the default appearance of the graphical - output it will produce. */ -plot = astPlot( wcsinfo, gbox, pbox, - "Grid=1, Colour(grid)=2, Font(textlab)=3" ); - -/* Obtain the value of any Plot attributes we want to preserve. */ -base = astGetI( plot, "Base" ); - -/* Open the plot configuration file, if it exists. Read each line of - text and use it to set new Plot attribute values. Close the file - when done. */ -if ( stream = fopen( "plot.config", "r" ) ) { - while ( fgets( line, MAXCHARS + 2, stream ) ) astSet( plot, "%s", line ); - close( stream ); -} - -/* Restore any attribute values we are preserving. */ -astSetI( plot, "Base", base ); - -/* Produce the graphical output (e.g.). */ -astGrid( plot ); -\end{terminalv} -\normalsize - -Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved -so that the user cannot change it. This is because graphical output -will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe -the plotting surface to which we attached the Plot when we created it. - -The arrangement shown above allows the contents of the ``plot.config'' -file to control most aspects of the graphical output produced -(including the coordinate system used; the colour, line style, -thickness and font used for each component; the positioning of axes -and tick marks; the precision, format and positioning of labels; -\emph{etc.}) \emph{via} assignments of the form: - -\small -\begin{terminalv} -System=Galactic, Equinox = 2001 -Border = 1, Colour( border ) = 1 -Colour( grid ) = 2 -DrawAxes = 1 -Colour( axes ) = 3 -Digits = 8 -Labelling = Interior -\end{terminalv} -\normalsize - -For a more sophisticated interface, you could obviously perform -pre-processing on this input---for example, to translate words like -``red'', ``green'' and ``blue'' into colour indices, to permit -comments and blank lines, \emph{etc.} - -For a full list of the attributes that may be used to control the -appearance of graphical output, see the description of the Plot class -in \appref{ss:classdescriptions}. For a complete description of each -individual attribute (\emph{e.g.}\ those above), see the attribute's -entry in \appref{ss:attributedescriptions}. - -\cleardoublepage -\section{\label{ss:primer}An AST Object Primer} - -The AST library deals throughout with entities called Objects and a -basic understanding of how to handle these is needed before you can -use the library effectively. If you are already familiar with an -object-oriented language, such as C$++$, few of the concepts should -seem new to you. Be aware, however, that AST is designed to be used -\emph{via} fairly conventional C and Fortran interfaces, so some -things have to be done a little differently. - -If you are not already familiar with object-oriented programming, then -don't worry---we will not emphasise this aspect more than is necessary -and will not assume any background knowledge. Instead, this section -concentrates on presenting all the fundamental information you will -need, explaining how AST Objects behave and how to manipulate them -from conventional C programs. - -If you like to read documents from cover to cover, then you can -consider this section as an introduction to the programming techniques -used in the rest of the document. Otherwise, you may prefer to skim -through it on a first reading and return to it later as reference -material. - -\subsection{AST Objects} - -An AST \htmlref{Object}{Object} is an entity which is used to store information and -Objects come in various kinds, called \emph{classes}, according to the -sort of information they hold. Throughout this section, we will make -use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to -illustrate many of the basic concepts. - -A ZoomMap is an Object that contains a recipe for converting -coordinates between two hypothetical coordinate systems. It does this -by multiplying all the coordinate values by a constant called the -\emph{\htmlref{Zoom}{Zoom} factor}. A ZoomMap is a very simple Object which exists -mainly for use in examples. It allows us to illustrate the ways in -which Objects are manipulated and to introduce the concept of a -\htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental -to the way the AST library works. - -\subsection{\label{ss:objectcreation}Object Creation and Pointers} - -Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very -simply as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstZoomMap *zoommap; - -... - -zoommap = astZoomMap( 2, 5.0, "" ) -\end{terminalv} -\normalsize - -The first step is to include the header file ``ast.h'' which declares -the interface to the AST library. We then declare a pointer of type -AstZoomMap$*$ to receive the result and invoke the function \htmlref{astZoomMap}{astZoomMap} -to create the ZoomMap. The pattern is the same for all other classes -of AST \htmlref{Object}{Object}---you simply prefix ``ast'' to the class name to obtain -the function that creates the Object and prefix ``Ast'' to obtain the -type of the returned pointer. - -These functions are called \emph{constructor functions}, or simply -\emph{constructors} (you can find an individual description of all AST -functions in \appref{ss:functiondescriptions}) and the arguments -passed to the constructor are used to initialise the new Object. In -this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we -are going to work in a 2-dimensional -space) and 5.0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a C -double value. We will return to the final argument, an empty string, -shortly (\secref{ss:attributeinitialisation}). - -The value returned by the constructor is termed an \emph{Object pointer} -or, in this case, a \emph{ZoomMap pointer} and is used to refer to the -Object. You perform all subsequent operations on the Object by -passing this pointer to other AST functions. - -\subsection{\label{ss:objecthierarchy}The Object Hierarchy} - -Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it -relates to other kinds of \htmlref{Object}{Object} before investigating what we can do -with it. - -We have so far indicated that a ZoomMap is a kind of Object and have -also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements -can be represented very simply using the following hierarchy: - -\small -\begin{terminalv} -Object - Mapping - ZoomMap -\end{terminalv} -\normalsize - -which is a way of stating that a ZoomMap is a special class of -Mapping, while a Mapping, in turn, is a special class of Object. This -is exactly like saying that an Oak is a special form of Tree, while a -Tree, in turn, is a special form of Plant. This may seem almost -trivial, but before you turn to read something less dull, be assured -that it is a very important idea to keep in mind in what follows. - -If we look at some of the other Objects used by the AST library, we -can see how these are all related in a similar way (don't worry about -what they do at this stage): -\label{ss:mappinghierarchy} - -\small -\begin{terminalv} -Object - Mapping - Frame - FrameSet - Plot - UnitMap - ZoomMap - Channel - FitsChan - XmlChan -\end{terminalv} -\normalsize - -Notice that there are several different types of Mapping available -(\emph{i.e.}\ there are classes of Object indented beneath the -``Mapping'' heading) and, in addition, other types of Object which are -not Mappings---Channels for instance (which are at the same -hierarchical level as Mappings). - -The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we -will not discuss in detail until \secref{ss:plots}). As you can see, a -Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and, -like everything else, ultimately an Object. - -What this means is that you can use a Plot not only for its own -specialised behaviour, but also whenever any of these other -less-specialised classes of Object is called for. The general rule is -that an Object of a particular class may substitute for any of the -classes appearing above it in this hierarchy. The Object is then said -to \emph{inherit} the behaviour of these higher classes. We can -therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object -is called for. - -Sometimes, this can lead to some spectacular short-cuts by avoiding -the need to break large Objects down in order to access their -components. With some practice and a little lateral thinking you -should soon be able to spot opportunities for this. - -You can find the full \emph{class hierarchy}, as this is called, for -the AST library in \appref{ss:classhierarchy} and you may need to -refer to it occasionally until you are familiar with the classes you -need to use. - -\subsection{\label{ss:displayingobjects}Displaying Objects} - -Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier -(\secref{ss:objectcreation}) and examine what it's made of. -There is a function for doing this, called \htmlref{astShow}{astShow}, which is provided -mainly for looking at Objects while you are debugging programs. - -If you consult the description of astShow in -\appref{ss:functiondescriptions}, you will find that it takes a -pointer to an \htmlref{Object}{Object} (of type AstObject$*$) as its argument. Although -we have only a ZoomMap pointer available, this is not a problem. If -you refer to the brief class hierarchy described above -(\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an -Object, albeit a specialised one, so it inherits the properties of all -Objects and can be substituted wherever an Object is required. We can -therefore pass our ZoomMap pointer directly to astShow, as follows: - -\small -\begin{terminalv} -astShow( zoommap ); -\end{terminalv} -\normalsize - -The output from this will appear on the standard output stream and -should look like the following: - -\small -\begin{terminalv} -Begin ZoomMap - Nin = 2 -IsA Mapping - Zoom = 5 -End ZoomMap -\end{terminalv} -\normalsize - -Here, the ``Begin'' and ``End'' lines mark the beginning and end of -the ZoomMap, while the values 2 and 5 are simply the values we -supplied to initialise it (\secref{ss:objectcreation}). These have -been given simple names to make them easy to refer to. - -The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line -between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a -property shared by all Mappings, so the ZoomMap has inherited this -from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however, -is specific to a ZoomMap and isn't shared by other kinds of Mappings. - -\subsection{\label{ss:gettingattributes}Getting Attribute Values} - -We saw above (\secref{ss:displayingobjects}) how to display the -internal values of an \htmlref{Object}{Object}, but what about accessing these values -from a program? Not all internal Object values are accessible in this -way, but many are. Those that are, are called \emph{attributes}. A -description of all the attributes used by the AST library can be found -in \appref{ss:attributedescriptions}. - -Attributes come in several data types (character string, integer, -boolean and floating point) and there is a standard way of obtaining -their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin} -attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as -follows: - -\small -\begin{terminalv} -int nin; - -... - -nin = astGetI( zoommap, "Nin" ); -\end{terminalv} -\normalsize - -Here, the function astGetI is used to extract the attribute value by -giving it the ZoomMap pointer and the attribute name (attribute names -are not case sensitive, but we have used consistent capitalisation in -this document in order to identify them). Remember to use the -``ast.h'' header file to include the function prototype. - -If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably -have used astGetD instead, this being a double version of the same -function, for example: - -\small -\begin{terminalv} -double zoom; - -... - -zoom = astGetD( zoommap, "Zoom" ); -\end{terminalv} -\normalsize - -However, we could equally well have read the Nin value as double, or -the Zoom value as an integer, or whatever we wanted. - -The data type you want returned is specified simply by replacing the -final character of the astGetX function name with C~(character -string), D~(double), F~(float), I~(int) or L~(long). If possible, the -value is converted to the type you want. If not, an error message will -result. Note that all floating point values are stored internally as -double, and all integer values as int. Boolean values are also stored -as integers, but only take the values 1 and 0 (for true/false). - -\subsection{\label{ss:settingattributes}Setting Attribute Values} - -Some attribute values are read-only and cannot be altered after an -\htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing -the number of coordinates) is like this. It is defined when the -ZoomMap is created, but cannot then be altered. - -Other attributes, however, can be modified whenever you want. A -ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this -could be done simply as follows: - -\small -\begin{terminalv} -astSetD( zoommap, "Zoom", 99.6 ); -\end{terminalv} -\normalsize - -which sets the value to 99.6. As when getting an attribute value -(\secref{ss:gettingattributes}), you have a choice of which data type -you will use to supply the new value. For instance, you could use an -integer value, as in: - -\small -\begin{terminalv} -astSetI( zoommap, "Zoom", 99 ); -\end{terminalv} -\normalsize - -and the necessary data conversion would occur. You specify the data -type you want to supply simply by replacing the final character of the -astSetX function name with C~(character string), D~(double), -F~(float), I~(int) or L~(long). Setting a boolean attribute to any -non-zero integer causes it to take the value 1. - -An alternative way of setting attribute values for Objects is to use -the \htmlref{astSet}{astSet} function (\emph{i.e.}\ with no final character specifying a -data type). In this case, you supply the attribute values in a -character string. The big advantage of this method is that you can -assign values to several attributes at once, separating them with -commas. This also reads more naturally in programs. For example: - -\small -\begin{terminalv} -astSet( zoommap, "Zoom=99.6, Report=1" ); -\end{terminalv} -\normalsize - -would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute -(about which more shortly---\secref{ss:transforming}). You don't really -have to worry about data types with this method, as any character -representation will do. Note, when using astSet, a -literal comma may be included in an attribute value by enclosed the value in -quotation marks: -\small -\begin{terminalv} - astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' ); -\end{terminalv} -\normalsize - -Another attractive feature of astSet is that you can build the -character string which contains the attribute settings in the same way -as when using the C run time library ``printf'' function. This is most -useful when the values you want to set are held in other -variables. For example: - -\small -\begin{terminalv} -double zoom = 99.6; -int report = 1; - -... - -astSet( zoommap, "Zoom=%g, Report=%d", zoom, report ); -\end{terminalv} -\normalsize - -would replace the ``\%'' conversion specifications by the values -supplied as additional arguments. Any number of additional arguments -may be supplied and the formatting rules are exactly the same as for -the C ``printf'' family of functions. This is a very flexible -technique, but does contain one pitfall: - -\begin{quote} -\textbf{Pitfall.} The default precision used by ``printf'' (and astSet) -for floating point values is only 6 decimal digits, corresponding -approximately to float on most machines, whereas the AST library -stores such values internally as doubles. You should be careful to -specify a larger precision (such as DBL\_DIG, as defined in -$<$float.h$>$) when necessary. For example: - -\small -\begin{terminalv} -#include <float.h> - -... - -astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value ); -\end{terminalv} -\normalsize -\end{quote} - -Substituted strings may contain commas and this is a useful way of -assigning such strings as attribute values without the comma being -interpreted as an assignment separator, for example: - -\small -\begin{terminalv} -astSet( object, "Attribute=%s", "A string, containing a comma" ); -\end{terminalv} -\normalsize - -This is equivalent to using astSetC and one of these two methods -should always be used when assigning string attribute values which -might potentially contain a comma (\emph{e.g.}\ strings obtained from -an external source). However, you should not attempt to use astSet to -substitute strings that contain newline characters, since these are -used internally as separators between adjacent attribute assignments. -\label{ss:attributeinitialisation} - -Finally, a very convenient way of setting attribute values is to do so -at the same time as you create an Object. Every Object constructor -function has a final character string argument which allows you to do -this. Although you can simply supply an empty string, it is an ideal -opportunity to initialise the Object to have just the attributes you -want. For example, we might have created our original ZoomMap with: - -\small -\begin{terminalv} -zoommap = astZoomMap( 2, 5.0, "Report=1" ); -\end{terminalv} -\normalsize - -and it would then start life with its Report attribute set to 1. -The ``printf''-style substitution described above may also be used -here. - -\subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes} - -You can use the astGetX family of functions -(\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute -at any time, regardless of whether a value has previously been set for -it. If no value has been set, the AST library will generate a suitable -default value. - -Often, the default value of an attribute will not simply be trivial -(zero or blank) but may involve considerable processing to -calculate. Wherever possible, defaults are designed to be real-life, -sensible values that convey information about the state of the -Object. In particular, they may often be based on the values of other -attributes, so their values may change in response to changes in these -other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a -little too simple to show this behaviour, but we will meet it later -on. - -An attribute that returns a default value in this way is said to be -\emph{un-set}. Conversely, once an explicit value has been assigned to -an attribute, it becomes \emph{set} and will always return precisely -that value, never a default. - -The distinction between set and un-set attributes is important and -affects the behaviour of several key routines in the AST library. You -can test if an attribute is set using the function \htmlref{astTest}{astTest}, which -returns a boolean (integer) result, as in: - -\small -\begin{terminalv} -if ( astTest( zoommap, "Report" ) ) { - <the Report attribute is set> -} -\end{terminalv} -\normalsize - - -Once an attribute is set, you can return it to its un-set state using -\htmlref{astClear}{astClear}. The effect is as if it had never been set in the first -place. For example: - -\small -\begin{terminalv} -astClear( zoommap, "Report" ); -\end{terminalv} -\normalsize - -would ensure that the default value of the \htmlref{Report}{Report} attribute is used -subsequently. - -%\subsection{TBW--Handling Character Attributes} - -\subsection{\label{ss:transforming}Transforming Coordinates} - -We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show -what it is really for. Here, we will also encounter a routine that is -a little more fussy about the type of pointer it will accept. - -The purpose of a ZoomMap is to multiply coordinates by a constant zoom -factor. To witness this in action, we will first set the \htmlref{Report}{Report} -attribute for our ZoomMap to a non-zero value: - -\small -\begin{terminalv} -astSet( zoommap, "Report=1" ); -\end{terminalv} -\normalsize - -This boolean (integer) attribute, which is present in all Mappings -(and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all -coordinate values that the Mapping converts. It is not a good idea to -leave this feature turned on in a finished program, but it can save a -lot of work during debugging. - -Our next step is to set up some coordinates for the ZoomMap to work -on, using two arrays ``xin'' and ``yin'', and two arrays to receive -the transformed coordinates, ``xout'' and ``yout''. Note that these -are arrays of double, as are all coordinate data processed by the AST -library: - -\small -\begin{terminalv} -double xin[ 10 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 }; -double yin[ 10 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0 }; -double xout[ 10 ]; -double yout[ 10 ]; -\end{terminalv} -\normalsize - -We will now use the function \htmlref{astTran2}{astTran2} to transform the input -coordinates. This is the most commonly-used (2-dimensional) coordinate -transformation function. If you look at its description in -\appref{ss:functiondescriptions}, you will see that it requires a -pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer, -as we could with the functions discussed previously. If we passed it a -pointer to an inappropriate Object, an error message would result. - -Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we -can use it with astTran2 to transform our coordinates, as follows: - -\small -\begin{terminalv} -astTran2( zoommap, 10, xin, yin, 1, xout, yout ); -\end{terminalv} -\normalsize - -Here, 10 is the number of points we want to transform and the fifth -argument value of 1 indicates that we want to transform in the -\emph{forward} direction (from input to output). - -Because our ZoomMap's Report attribute is set to 1, this will cause -the effects of the ZoomMap on the coordinates to be displayed on the -standard output stream: - -\small -\begin{terminalv} -(0, 0) --> (0, 0) -(1, 2) --> (5, 10) -(2, 4) --> (10, 20) -(3, 6) --> (15, 30) -(4, 8) --> (20, 40) -(5, 10) --> (25, 50) -(6, 12) --> (30, 60) -(7, 14) --> (35, 70) -(8, 16) --> (40, 80) -(9, 18) --> (45, 90) -\end{terminalv} -\normalsize - -This shows the coordinate values of each point both before and after -the ZoomMap is applied. You can see that each coordinate value has -been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute -value. The transformed coordinates are now stored in the ``xout'' and -``yout'' arrays. - -If we wanted to transform in the opposite direction, we need simply -change the fifth argument of astTran2 from 1 to 0. We can also feed -the output coordinates from the above back into the function: - -\small -\begin{terminalv} -astTran2( zoommap, 10, xout, yout, 0, xin, yin ); -\end{terminalv} -\normalsize - -The output would then look like: - -\small -\begin{terminalv} -(0, 0) --> (0, 0) -(5, 10) --> (1, 2) -(10, 20) --> (2, 4) -(15, 30) --> (3, 6) -(20, 40) --> (4, 8) -(25, 50) --> (5, 10) -(30, 60) --> (6, 12) -(35, 70) --> (7, 14) -(40, 80) --> (8, 16) -(45, 90) --> (9, 18) -\end{terminalv} -\normalsize - -This is termed the \emph{inverse} transformation (we have converted -from output to input) and you can see that the original coordinates -have been recovered by dividing by the Zoom factor. - -\subsection{\label{ss:annullingpointers}Managing Object Pointers} - -So far, we have looked at creating Objects and using them in various -simple ways but have not yet considered how to get rid of them again. - -Every \htmlref{Object}{Object} consumes various computer resources (principally memory) -and should be disposed of when it is no longer required, so as to free -up these resources. One way of doing this (not necessarily the -best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once -you have finished with it, using \htmlref{astAnnul}{astAnnul}. For example: - -\small -\begin{terminalv} -zoommap = astAnnul( zoommap ); -\end{terminalv} -\normalsize - -This indicates that you have finished with the pointer. Since astAnnul -always returns the null value AST\_\_NULL (as defined in ``ast.h''), -the recommended way of using it, as here, is to assign the returned -value to the pointer being annulled. This ensures that any attempt to -use the pointer again will generate an error message. - -In general, this process may not delete the Object, because there may -still be other pointers associated with it. However, each Object -maintains a count of the number of pointers associated with it and -will be deleted if you annul the final pointer. Using astAnnul -consistently will therefore ensure that all Objects are disposed of at -the correct time. You can determine how many pointers are associated -with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute. - -\subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End} - -The use of \htmlref{astAnnul}{astAnnul} (\secref{ss:annullingpointers}) is not completely -foolproof, however. Consider the following: - -\small -\begin{terminalv} -astShow( astZoomMap( 2, 5.0, "" ) ); -\end{terminalv} -\normalsize - -This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output -(\secref{ss:displayingobjects}). Using function invocations as -arguments to other functions in this way is very convenient because it -avoids the need for intermediate pointer variables. However, the -pointer generated by \htmlref{astZoomMap}{astZoomMap} is still active, and since we have not -stored its value, we cannot use astAnnul to annul it. The ZoomMap will -therefore stay around until the end of the program. - -A simple way to avoid this problem is to enclose all use of AST -functions between invocations of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}, for example: - -\small -\begin{terminalv} -astBegin; -astShow( astZoomMap( 2, 5.0, "" ) ); -astEnd; -\end{terminalv} -\normalsize - -When the expansion of astEnd (which is a macro) executes, every \htmlref{Object}{Object} -pointer created since the previous use of astBegin (also a macro) is -automatically annulled and any Objects left without pointers are -deleted. This provides a simple solution to managing Objects and their -pointers, and allows you to create Objects very freely without needing -to keep detailed track of each one. Because this is so convenient, we -implicitly assume that astBegin and astEnd are used in most of the -examples given in this document. Pointer management is not generally -shown explicitly unless it is particularly relevant to the point being -illustrated. - -If necessary, astBegin and astEnd may be nested, like blocks delimited -by ``\{\ldots\}'' in C, to define a series of AST pointer -contexts. Each use of astEnd will then annul only those Object -pointers created since the matching use of astBegin. - -\subsection{Exporting, Importing and Exempting AST Pointers} -The \htmlref{astExport}{astExport} function allows you to export particular pointers from -one AST context (\secref{ss:contexts}) to the next outer one, as -follows: - -\small -\begin{terminalv} -astExport( zoommap ); -\end{terminalv} -\normalsize - -This would identify the pointer stored in ``zoommap'' as being required -after the end of the current AST context. It causes any pointers -nominated in this way to survive the next use of \htmlref{astEnd}{astEnd} (but only one -such use) unscathed, so that they are available to the next outer -context. This facility is not needed often, but is invaluable when -the purpose of your \htmlref{astBegin}{astBegin}\ldots astEnd block is basically to -generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting -that pointer out. - - -The \htmlref{astImport}{astImport} routine can be used in a similar manner to import a -pointer into the current context, so that it is deleted when the current -context is closed using astEnd. - -Sometimes, you may also want to exempt a pointer from all the effects -of AST contexts. You should not need to do this often, but it will -prove essential if you ever need to write a library of functions that -stores AST pointers as part of its own internal data. Without some -form of exemption, the caller of your routines could cause the -pointers you have stored to be annulled---thus corrupting your -internal data---simply by using astEnd. To avoid this, you should use -\htmlref{astExempt}{astExempt} on each pointer that you store, for example: - -\small -\begin{terminalv} -astExempt( zoommap ); -\end{terminalv} -\normalsize - -This will prevent the pointer being affected by any subsequent use of -astEnd. Of course, it then becomes your responsibility to annul this -pointer (using \htmlref{astAnnul}{astAnnul}) when it is no longer required. - - -\subsection{AST Objects within Multi-threaded Applications} - -When the AST library is built from source, the build process checks to -see if the POSIX threads library (``\texttt{pthreads}'') is available. If so, -appropriate \texttt{pthreads} calls are inserted into the AST source code to -ensure that AST is thread-safe, and the AST\_\_THREADSAFE macro (defined -in the ``ast.h'' header file) is set to ``\texttt{1}''. If the \texttt{pthreads} -library cannot be found when AST is built, a working version of the AST -library will still be created, but it will not be thread-safe. In this -case the AST\_\_THREADSAFE macro will be set to ``\texttt{0}'' in ast.h. The -rest of this section assumes that the thread-safe version of AST is being -used. - -Note, some AST functions call externally specified functions (\emph{e.g.} -the source and sink functions used by the \htmlref{Channel}{Channel} class or the graphics -primitives functions used by the \htmlref{Plot}{Plot} class). AST does not know whether -such functions are thread-safe or not. For this reason, invocations of these -functions within a multi-threaded environment are serialised using a mutex -in order to avoid two or more threads executing an external function -simultaneously. - -If an application uses more than one thread, the possibility arises that -an \htmlref{Object}{Object} created by one thread may be accessed by another thread, potentially -simultaneously. If any of the threads modifies any aspect of the Object, -this could lead to serious problems within the other threads. For this -reason, some restrictions are placed on how Objects can be used in a -multi-threaded application. - -\subsubsection{Locking AST Objects for Exclusive Use} -The basic restriction is that a thread can only access Objects that it -has previously locked for its own exclusive use. If a thread attempts to -access any \htmlref{Object}{Object} that it has not locked, an error is reported. - -The \htmlref{astAnnul}{astAnnul} function is the one exception to this restriction. Pointers -for Objects not currently locked by the calling thread can be annulled -succesfully using astAnnul. This means that a thread that has finished -with an Object pointer can unlock the Object by passing the pointer to -\htmlref{astUnlock}{astUnlock} (so that other threads can use the Object via their own cloned -pointers), and can then annul the pointer using astAnnul. Note, however, -that an error will be reported by astAnnul if the supplied pointer has -been locked by another thread using \htmlref{astLock}{astLock}. - -When an Object is created, it is initially locked by the calling thread. -Therefore a thread does not need to lock an Object explicitly if it was -created in the same thread. - -If the Object pointer is then passed to another thread, the first thread -must unlock the Object using astUnlock and the second thread must then lock -it using astLock. - -If a thread attempts to lock an Object that is already locked by another -thread, it can choose to report an error immediately or to wait until the -Object is available. - -The \htmlref{astThread}{astThread} function can be used to determine whether an Object is -locked by the running thread, locked by another thread, or unlocked. - -If two or more threads need simultaneous access to an Object, a deep copy -of the Object should be taken for each thread, using \htmlref{astCopy}{astCopy}, and then -the copies should be unlocked and passed to the othe threads, which -should then lock them. Note, if a thread modifies the Object, the -modification will have no effect on the other threads, because the Object -copies are independent of each other. - -\subsubsection{AST Pointer Contexts} - -Each thread maintains its own set of nested AST contexts, so when \htmlref{astEnd}{astEnd} -is called, only Objects that are locked by the current thread will -be annulled. - -If an \htmlref{Object}{Object} is unlocked by a thread using \htmlref{astUnlock}{astUnlock}, it is exempted from -context handling so that subsequent invocations of astEnd will not cause it -to be annulled (this is similar to using \htmlref{astExempt}{astExempt} on the Object). When the -Object is subsequently locked by another thread using \htmlref{astLock}{astLock}, it will be -imported into the context that was active when astLock was called. - - - -\subsection{\label{ss:copyingobjects}Copying Objects} - -The AST library makes extensive use of pointers, not only for -accessing Objects directly, but also as a means of storing Objects -inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to -hold collections of other Objects). Rather than copy an Object in its -entirety, a pointer to the interior Object is simply stored in the -enclosing Object. - -This means that Objects may frequently not be completely independent -of each other because, for instance, they both contain pointers to the -same sub-Object. In this situation, changing one Object (say assigning -an attribute value) may affect the other one \emph{via} the common -Object. - -It is difficult to describe all cases where this may happen, so you -should always be alert to the possibility. Fortunately, there is a -simple solution. If you require two Objects to be independent, then -simply use \htmlref{astCopy}{astCopy} to make a copy of one, \emph{e.g.}: - -\small -\begin{terminalv} -AstZoomMap *zoommap1, *zoommap2; - -... - -zoommap2 = astCopy( zoommap1 ); -\end{terminalv} -\normalsize - -This process will create a true copy of any Object and return a -pointer to the copy. This copy will not contain any pointers to any -component of the original Object (everything is duplicated), so you -can then modify it safely, without fear of affecting either the -original or any other Object. - -%\subsection{TBW - Inheritance} - -\subsection{C Pointer Types} - -At this point it is necessary to confess to a small amount of -deception. So far, we have been passing \htmlref{Object}{Object} pointers to AST -functions in order to perform operations on those Objects. In fact, -however, what we were using were not true C functions at all, but -merely macros which invoke a related set of hidden functions with -essentially the same arguments. In practical terms, this makes very -little difference to how you use the functions, as we will continue to -call them.\footnote{About the only difference is that you cannot store -a pointer to an AST ``function'' in a variable and use the variable's -value to invoke that function again later.} - -The reason for this deception has to do with the rules for data typing -in C. Recall that most AST functions can be used to process Objects -from a range of different classes (\secref{ss:objecthierarchy}). In C, -this means passing different pointer types to the same function and -most C compilers will not permit this (at least, not without -grumbling) because it usually indicates a programming error. In AST, -however, it is perfectly safe if done properly. Some way is therefore -needed of circumventing the normal compiler checking. - -The normal way of doing this in C is with a cast. This approach -quickly becomes cumbersome, however, so we have adopted the strategy -of wrapping each function in a macro which applies the appropriate -cast for you. This means that you can pass pointers of any type to any -AST function. For example, in passing a \htmlref{ZoomMap}{ZoomMap} pointer to \htmlref{astShow}{astShow}: - -\small -\begin{terminalv} -AstZoomMap *zoommap; - -... - -zoommap = astZoomMap( 2, 5.0, "" ); -astShow( zoommap ); -\end{terminalv} -\normalsize - -we are exploiting this mechanism to avoid a compiler warning, because -the notional type of astShow's parameter is AstObject$*$ (not -AstZoomMap$*$). - -We must still guard against programming errors, however, so every -pointer's type is checked by the enclosing macro immediately before -any AST function executes. This allows pointer mis-matches (in the -more liberal AST sense---\emph{i.e.}\ taking account of the class -hierarchy, rather than the stricter C sense) to be detected at -run-time and a suitable error message will be reported. This message -should also identify the line where the error occurs. - -A similar strategy is used when pointers are returned by AST functions -(\emph{i.e.}\ as the function result). In this case the pointer is -cast to void$*$, although we retain the notional pointer type in the -function's documentation -(\emph{e.g.}\ \appref{ss:functiondescriptions}). This allows you to -assign function results to pointer variables without using an explicit -cast. For example, the \htmlref{astRead}{astRead} function returns an Object pointer, but -might be used to read (say) a ZoomMap as follows: - -\small -\begin{terminalv} -AstChannel *channel; -AstZoomMap *zoommap; - -... - -zoommap = astRead( channel ); -\end{terminalv} -\normalsize - -Strictly, there is a C pointer mis-match here, but it is ignored -because the operation makes perfect sense to AST. - -\textbf{There is an important exception to this, however, in that -constructor functions always return strongly-typed pointers.} What -we mean by this is that the returned pointer is never implicitly cast -to void$*$. You must therefore match pointer types when you initially -create an Object using its constructor, such as in the following: - -\small -\begin{terminalv} -AstZoomMap *zoommap; - -... - -zoommap = astZoomMap( 2, 5.0, "" ); -\end{terminalv} -\normalsize - -If the variable receiving the pointer is of a different type, an -appropriate cast should be used, as in: - -\small -\begin{terminalv} -AstMapping *mapping; - -... - -mapping = (AstMapping *) astZoomMap( 2, 5.0, "" ); -\end{terminalv} -\normalsize - -This is an encouragement for you to declare your pointer types -consistently, since this is of great benefit to anyone trying to -understand your software. - -Finally, we should also make one more small confession---AST pointers -are not really pointers at all. Although they behave like pointers, -the actual ``values'' stored are not the addresses of C data -structures. This means that you cannot de-reference an AST pointer to -examine the data within (although you can use astShow -instead---\secref{ss:displayingobjects}). This is necessary so that AST -pointers can be made unique even although several of them might -reference the same Object. - -\subsection{\label{ss:errordetection}Error Detection} - -If an error occurs in an AST function (for example, if you supply an -invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an -error message will be written to the standard error stream and the -function will immediately return. - -To indicate than an error has occurred, an AST \emph{error status} -value is used. This integer value is stored internally by AST and is -initially clear (\emph{i.e.}\ set to zero\footnote{We will assume -throughout that the ``OK'' value is zero, as it currently is. However, -a different value could, in principle, be used if the environment in -which AST is running requires it. This is why a simple interface is -provided to isolate you from the actual value of the error status.} -to indicate no error). If an error occurs, it becomes set to a -different \emph{error value}, which allows you to detect the error, as -follows: - -\small -\begin{terminalv} -zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" ); -if ( !astOK ) { - <an error has occurred> -} -\end{terminalv} -\normalsize - -The macro \htmlref{astOK}{astOK} is used to test whether the AST error status is still -OK. In this example it would not be, because we have attempted to set -a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not -have such an attribute. The actual value of the AST error status can -be obtained using the \htmlref{astStatus}{astStatus} macro, as follows: - -\small -\begin{terminalv} -int status; - -... - - -status = astStatus; -\end{terminalv} -\normalsize - -A consequence of the AST error status being set is that almost all AST -functions will subsequently cease to function and will instead simply -return without action. This means that you do not need to use astOK -to check for errors very frequently. Instead, you can usually simply -invoke a succession of AST functions. If an error occurs in any of -them, the following ones will do nothing and you can check for the -error at the end, for example: - -\small -\begin{terminalv} -astFunctionA( ... ); -astFunctionB( ... ); -astFunctionC( ... ); -if ( !astOK ) { - <an error has occurred> -} -\end{terminalv} -\normalsize - -There are, however, a few functions which do not adhere to this -general rule and which will attempt to execute if the AST error status -is set. These functions, such as \htmlref{astAnnul}{astAnnul}, are concerned with cleaning -up and recovering resources. For example, in the following: - -\small -\begin{terminalv} -zoommap = astZoomMap( 2, 5.0, "" ); - -astFunctionX( ... ); -astFunctionY( ... ); -astFunctionZ( ... ); - -zoommap = astAnnul( zoommap ); -if ( !astOK ) { - <an error has occurred> -} -\end{terminalv} -\normalsize - -astAnnul will execute normally in order to recover the resources -associated with the ZoomMap that was created earlier, regardless of -whether an error has occurred in any of the intermediate functions. -Functions which behave in this way are noted in the relevant -descriptions in \appref{ss:functiondescriptions}. - -If a serious error occurs, you will probably want to abort your -program, but sometimes you may want to recover and carry on. Because -very few AST functions will execute once the AST error status has been -set, you must first clear this status by using the \htmlref{astClearStatus}{astClearStatus} -macro, as follows: - -\small -\begin{terminalv} -astClearStatus; -\end{terminalv} -\normalsize - -This will restore the AST error status to its OK value, so that AST -functions execute normally again. - -Occasionally, you may also need to set the AST error status to an -explicit error value (see \secref{ss:channelsink} for an -example). This is done using \htmlref{astSetStatus}{astSetStatus} and can be used to -communicate to AST that an error has occurred in some other item of -software, for example: - -\small -\begin{terminalv} -int new_status; - -... - -astSetStatus( new_status ); -\end{terminalv} -\normalsize - -The effect is that most AST routines will subsequently return without -action, just as if an error had occurred within the AST library -itself. - -\subsection{Sharing the Error Status} - -In some software, it is usual to maintain a single integer error -status variable which is accessed by each function as it executes. If -an error occurs, this status variable is set and other functions can -detect this and take appropriate action. - -If you use AST in such a situation, it can be awkward to have a -separate internal error status used by AST functions alone. To remedy -this, AST is capable of sharing the error status variable used by any -other software, so long as they use the same conventions -(\emph{i.e.}\ a C int with the same ``OK'' value). To enable this -facility, you should pass the address of your status variable to -\htmlref{astWatch}{astWatch}, as follows: - -\small -\begin{terminalv} -int my_status; -int *old_address; - -... - -old_address = astWatch( &my_status ); -\end{terminalv} -\normalsize - -Henceforth, instead of using its own internal error status variable, -AST will use the one you supply, so that it can detect errors flagged -by other parts of your software. The address of the original error -status variable is returned by astWatch, so you can restore the -original behaviour later if necessary. - -Note that this facility is not available \emph{via} the Fortran -interface to the AST library. - -\cleardoublepage -\section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)} - -In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a -\htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its -input to its output and back again (\secref{ss:transforming}). We also -saw how its behaviour could be controlled by setting various -attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made -it display coordinate values as it transformed them. - -In this section, we will look at Mappings a bit more thoroughly and -explore the behaviour which is common to all the Mappings provided by -AST. This is good background for what follows, because many of the -Objects we discuss later will also turn out to be Mappings in various -disguises. - -\subsection{\label{ss:mappingclass}The Mapping Class} - -Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class -as a whole and some of the sub-classes it contains: - -\begin{terminalv} - Mapping - CmpMap - DssMap - GrismMap - IntraMap - LutMap - MathMap - MatrixMap - PermMap - PolyMap - SlaMap - SpecMap - TimeMap - UnitMap - WcsMap - ZoomMap - - Frame - <various types of Frame> -\end{terminalv} - -The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered -in detail in \secref{ss:frames}. We start by looking at the parent -class, Mapping. - -AST does not provide a function to create a basic Mapping -(\emph{i.e.}\ the astMapping constructor does not exist). This is -because the Mapping class itself is ``virtual'' and basic Mappings are -of no use in themselves. The Mapping class serves simply to contain -the various specialised Mappings that exist. -However, it provides more than just a convenient heading for them -because it bestows all classes of Mapping with common properties -(\emph{e.g.}\ attributes) and behaviour. By examining the Mapping -class, we are therefore examining the things that all other Mappings -have in common. - -\subsection{The Mapping Model} - -The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}. -It is a black box which you can supply with a set of coordinate values -in return for a set of transformed coordinates. The two sets are -termed \emph{input} and \emph{output} coordinates. You can also go -back the other way and transform output coordinates back into input -coordinates, as we saw in \secref{ss:transforming}. - -\subsection{Changing Attributes of a Mapping} - -Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter -used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an -attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each -coordinate is to be multiplied. These attribute values should be set when -the Mapping is created and should not be changed afterwards. Indeed, the -AST library will report an error if an attempt is made to change the -value of a Mapping attribute. This is because, once created, Mappings are -often later included within other objects such as FrameSets and CmpMaps. -This means that in general there could be many active references to a single -Mapping object within a program. Changing an attribute of the Mapping -via one particular reference (i.e pointer) would cause all the other -references to change too, with often undesirable or unpredictable -consequences. To avoid this, Mappings are considered \emph{immutable} in -most situations. The one exception is if the Mapping has not yet been -cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference -couint of one) - changing the attributes of such a Mapping is allowed, -and will not generate an error. - -Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and -can be changed at any time. - -\subsection{Input and Output Coordinate Numbers} - -In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to -represent a single point need not be the same as the number that comes -out. Often these numbers will be the same, and often they will both -equal 2 (because 2-dimensional coordinate systems are common), but -this needn't necessarily be the case. - -The number of coordinates required to specify an input point is -represented by the integer attribute \htmlref{Nin}{Nin} and the number required to -specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only -attributes common to all Mappings. Generally, their values are fixed -when a Mapping is created. - -In \secref{ss:objectcreation}, we saw how the Nin attribute for a -\htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function -\htmlref{astZoomMap}{astZoomMap} which created it. In this case, the Nout attribute was not -needed and it implicitly took the same value as Nin, but we could -have enquired about its value had we wanted, as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstZoomMap *zoommap; -int nout; - -... - -nout = astGetI( zoommap, "Nout" ); -\end{terminalv} -\normalsize - -\subsection{Forward and Inverse Transformations} - -We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates -either from input to output, or \emph{vice versa}. These are termed -its \emph{forward} and \emph{inverse} transformations. - -This statement was not quite accurate, however, because in general -Mappings are only \textbf{potentially} capable of working in both -directions. In practice, coordinate transformation may only be -feasible in one direction or the other because some functions are not -easily inverted (they may be multi-valued, for instance). Allowance -must be made for this, so each Mapping has two read-only boolean -(integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate -whether each transformation is available. - -A transformation is available if the corresponding attribute is -non-zero, otherwise it is not.\footnote{Most of the Mappings provided -by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can -behave otherwise.} If you enquire about the value of these attributes, -a value of 0 or 1 is returned. Attempting to use a Mapping to apply a -transformation which is not available will result in an error. - -\subsection{\label{ss:invertingmappings}Inverting Mappings} - -An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert} -flag. This is a boolean (integer) attribute that can be assigned a new -value at any time. If it is non-zero, it has the effect of -interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the -Mapping is then said to be \emph{inverted}. By default, the Invert -attribute is zero. - -There is no magic in this. There is no fancy arithmetic involved in -inverting mathematical functions, for instance. The Invert flag is -simply a switch that interchanges a Mapping's input and output -ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are -swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and -when you ask for what was once the forward transformation you get the -inverse transformation instead (and \emph{vice versa}). When you -return the Invert attribute to zero, or clear it, the Mapping returns -to its original behaviour. - -Often, the actual value of the Invert attribute is unimportant and you -simply wish to invert its boolean sense, so that what was the -Mapping's input becomes its output and \emph{vice versa}. This is most -easily accomplished using \htmlref{astInvert}{astInvert}, as follows: - -\small -\begin{terminalv} -AstMapping *mapping; - -... - -astInvert( mapping ); -\end{terminalv} -\normalsize - -If the Mapping you have happens to be the wrong way around, astInvert -allows you to correct the problem. - -\subsection{Finding the Rate of Change of a Mapping Output} -The -\htmlref{astRate}{astRate} -function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output -with respect to any Mapping input, at a given input position. The method -used produces good accuracy (typically a relative error of 10E-10 or -less) but may require the Mapping to be evaluated 100 or more times. -An estimate of the second derivative is also produced by this function. - - -\subsection{Reporting Coordinate Transformations} - -We have already seen (\secref{ss:transforming}) how the boolean -(integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the -operation of transforming a set of coordinates will result in a report -being written to standard output. This will display the coordinate -values before and after transformation. It can save considerable time -during program development by eliminating the need to add loops and -output statements to your program. - -In a finished program, however, you should be careful that the Report -attribute is not set to a non-zero value unless you want to see the -output (there may often be rather a lot of this!). To help prevent -unwanted output being produced by accident, the Report attribute is -unusual in that its value is not preserved when a Mapping is copied -using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). Instead, it reverts to its -default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to -zero when a Mapping is written out, \emph{e.g.}\ to a file using a -\htmlref{Channel}{Channel} (\secref{ss:channels}). - -%\subsection{TBW---More on Transforming Coordinates} - -\subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values} - -Even when coordinates can, in principle, be transformed in either -direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific -coordinate values cannot be handled. For example, the Mapping may be -mathematically intractable (\emph{e.g.}\ singular) in certain places, -or it may map a subset of one space on to another, so that some points -in one space are not represented in the other. Sky projections often -show this behaviour, since it is quite common to project only half of -the celestial sphere on to two dimensions, omitting points on the -opposite side of the sky. There are many other examples. - -To indicate when coordinates cannot be transformed, for whatever -reason, AST substitutes a special output coordinate value given by the -macro AST\_\_BAD (as defined in the ``ast.h'' header file). Before -making use of coordinates generated by any of the AST transformation -functions, therefore, you may need to check for the presence of this -value. - -Because coordinates with the value AST\_\_BAD can be generated in this -way, all other AST functions are also capable of recognising this -value and handling it appropriately. The coordinate transformation -functions do this by propagating any missing input coordinate -information through to their output. This means that if you supply -coordinates with the value AST\_\_BAD, the returned coordinates are -also likely to contain this value. Here, for example, is what happens -if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of -coordinates: - -\small -\begin{terminalv} -(0, 0) --> (0, 0) -(<bad>, 2) --> (<bad>, 10) -(2, 4) --> (10, 20) -(3, 6) --> (15, 30) -(4, <bad>) --> (20, <bad>) -(5, 10) --> (25, 50) -(<bad>, <bad>) --> (<bad>, <bad>) -(7, 14) --> (35, 70) -(8, 16) --> (40, 80) -(9, 18) --> (45, 90) -\end{terminalv} -\normalsize - -The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This -is a case of ``garbage in, garbage out'' but at least it's consistent -garbage that you can recognise! - -Note how the presence of the AST\_\_BAD value in one input dimension -does not necessarily result in the loss of information for all output -dimensions. Sometimes, such loss will be unavoidable, but in general -an attempt is made to preserve information as far as possible. The -exact behaviour will depend on the Mapping involved. - -\subsection{\label{ss:unitmapexample}Example---the UnitMap} - -The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its -purpose is simply to copy coordinate values, unaltered, from its input -to its output and \emph{vice versa}. - -A UnitMap has no additional attributes beyond those of a basic -Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are -specified by the first argument supplied to its constructor. For -example: - -\small -\begin{terminalv} -AstUnitMap *unitmap; - -... - -unitmap = astUnitMap( 2, "" ); -\end{terminalv} -\normalsize - -will create a UnitMap that copies 2-dimensional coordinates. Inverting -a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert} -attribute. - -The main use of a UnitMap is to allow a Mapping to be supplied when one -is required (as an argument to a function, for example) but you wish -it to leave coordinate values unchanged. - -\subsection{\label{ss:permmapexample}Example---the PermMap} - -The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met -previously. Its purpose is to change the order, or number, of -coordinates. It is also able to substitute fixed values for -coordinates. - -To illustrate its action, suppose our input coordinates are denoted by -($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output -coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore, -should rotate the coordinate values by one position. - -To create such a PermMap, we first set up two integer arrays. One of -these, ``outperm'', controls the selection of input coordinates for -use in the output and the other, ``inperm'', controls selection of -output coordinates for use in the input: - -\small -\begin{terminalv} -int outperm[ 4 ] = { 4, 1, 2, 3 }; -int inperm[ 4 ] = { 2, 3, 4, 1 }; -\end{terminalv} -\normalsize - -Note that the numbers we store in these arrays are the indices of the -coordinates that we want to select. We have chosen these so that the -forward and inverse transformations will perform complementary -permutations on the coordinates. - -The PermMap is then created by passing these arrays to its -constructor, as follows: - -\small -\begin{terminalv} -AstPermMap *permmap; - -... - -permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" ); -\end{terminalv} -\normalsize - -Note that we specify the number of input and output coordinates -separately, but set both to 4 in this example. The resulting PermMap -would have the following effect when used to transform coordinates: - -\begin{terminalv} -Forward: - (1, 2, 3, 4) --> (4, 1, 2, 3) - (2, 4, 6, 8) --> (8, 2, 4, 6) - (3, 6, 9, 12) --> (12, 3, 6, 9) - (4, 8, 12, 16) --> (16, 4, 8, 12) - (5, 10, 15, 20) --> (20, 5, 10, 15) - -Inverse: - (4, 1, 2, 3) --> (1, 2, 3, 4) - (8, 2, 4, 6) --> (2, 4, 6, 8) - (12, 3, 6, 9) --> (3, 6, 9, 12) - (16, 4, 8, 12) --> (4, 8, 12, 16) - (20, 5, 10, 15) --> (5, 10, 15, 20) -\end{terminalv} - -If the number of input and output coordinates are unequal so, also, -will be the size of the ``outperm'' and ``inperm'' arrays. This means, -however, that we cannot fill them with coordinate indices so that they -perform complementary permutations, because one transformation will -lose information (discard a coordinate) that the other cannot recover. -To give an example, consider the following: - -\small -\begin{terminalv} -int outperm[ 3 ] = { 4, 3, 2 }; -int inperm[ 4 ] = { -1, 3, 2, 1 }; -double con[ 1 ] = { 99.004 }; -\end{terminalv} -\normalsize - -In this case, the forward transformation will change -($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The -inverse transformation restores the original coordinate order, but has -no value to assign to the first coordinate. In this case, the number -entered in the ``inperm'' array is $-$1. - -This negative value indicates that the coordinate value should be -obtained by addressing the first element of the ``con'' array -(\emph{i.e.}\ element zero). This array, ignored in the previous -example, may then be used to supply a value for the missing -coordinate. - -The constructor function: - -\small -\begin{terminalv} -permmap = astPermMap( 4, inperm, 3, outperm, con, "" ); -\end{terminalv} -\normalsize - -will then create a PermMap with the following effect when used to -transform coordinates: - -\begin{terminalv} -Forward: - (1, 2, 3, 4) --> (4, 3, 2) - (2, 4, 6, 8) --> (8, 6, 4) - (3, 6, 9, 12) --> (12, 9, 6) - (4, 8, 12, 16) --> (16, 12, 8) - (5, 10, 15, 20) --> (20, 15, 10) - -Inverse: - (4, 3, 2) --> (99.004, 2, 3, 4) - (8, 6, 4) --> (99.004, 4, 6, 8) - (12, 9, 6) --> (99.004, 6, 9, 12) - (16, 12, 8) --> (99.004, 8, 12, 16) - (20, 15, 10) --> (99.004, 10, 15, 20) -\end{terminalv} - -The ``con'' array may contain more than one value if necessary and may -be addressed by both the ``inperm'' and ``outperm'' arrays using -coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the -first, second, third,~\emph{etc.}\ elements. - -If there is no suitable replacement value that can be supplied -\emph{via} the ``con'' array, a value of zero may be entered into the -``outperm'' and/or ``inperm'' arrays. This causes the value AST\_\_BAD -to be used for the affected coordinate (as defined in the ``ast.h'' -header file), thus indicating a missing coordinate value -(\secref{ss:badcoordinates}). - -The principle use for a PermMap lies in matching a coordinate system -to a data array where there is a choice of storage order for the data. -PermMaps are also useful for discarding unwanted coordinates so as to -reduce the number of dimensions, such as when selecting a ``slice'' -from a multi-dimensional array. - -\cleardoublepage -\section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)} - -We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The -Mappings we have considered so far have been atomic, in the sense that -they perform pre-defined elementary transformations. A CmpMap, -however, is a compound Mapping. In essence, it is a framework for -containing other Mappings and its purpose is to allow those Mappings -to work together in various combinations while appearing as a single -\htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is -determined by the other Mappings it contains. - -\subsection{\label{ss:seriescmpmap}Combining Mappings in Series} - -Consider a simple example based on two 2-dimensional coordinate -systems. Suppose that to convert from one to the other we must swap -the coordinate order and multiply both coordinates by 5, so that the -coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done -in two stages: - -\begin{enumerate} -\item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the -coordinate order. - -\item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both -coordinate values by the constant 5. -\end{enumerate} - -The PermMap and ZoomMap are then said to operate \emph{in series}, -because they are applied sequentially -(\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}). We can create a \htmlref{CmpMap}{CmpMap} -that applies these Mappings in series as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstCmpMap *cmpmap; -AstPermMap *permmap; -AstZoomMap *zoommap; - -... - -/* Create the individual Mappings. */ -{ - int inperm[ 2 ] = { 2, 1 }; - int outperm[ 2 ] = { 2, 1 }; - permmap = astPermMap( 2, inperm, 2, outperm, NULL, "" ); -} -zoommap = astZoomMap( 2, 5.0, "" ) - -/* Combine them in series. */ -cmpmap = astCmpMap( permmap, zoommap, 1, "" ); - -/* Annul the individual Mapping pointers. */ -permmap = astAnnul( permmap ); -zoommap = astAnnul( zoommap ); -\end{terminalv} -\normalsize - -Here, the third argument (1) of the constructor function \htmlref{astCmpMap}{astCmpMap} -indicates ``in series''. - -When used to transform coordinates in the forward direction, the -resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap) -and then the second one (the ZoomMap). When transforming in the -inverse direction, it will apply the second one (in the inverse -direction) and then the first one (also in the inverse direction). In -general, although not in this particular example, the order in which -the two component Mappings are supplied is significant. Clearly, also, -the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first -Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for -the second one. - -\subsection{Combining Mappings in Parallel} - -Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the -only way of combining them. The alternative, \emph{in parallel}, -involves applying the two Mappings at once but on different subsets of -the coordinate values. - -Consider, for example, a set of 3-dimensional coordinates and suppose -we wish to transform them by swapping the first two coordinate values -and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms -into ($x_2,x_1,5x_3$). Again, we can perform each of these steps -individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used -earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is -1-dimensional and the individual Mappings are applied in parallel -(\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}). - -Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple: - -\small -\begin{terminalv} -cmpmap = astCmpMap( permmap, zoommap, 0, "" ); -\end{terminalv} -\normalsize - -The only difference is that the third argument of \htmlref{astCmpMap}{astCmpMap} is now -zero, meaning ``in parallel''. - -As before, the order in which the two component Mappings are supplied -is significant. The first one acts on the lower-numbered input -coordinate values (however many it needs) and produces the -lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on -the higher-numbered input coordinates (however many remain) and -generates the remaining higher-numbered output coordinates. When the -CmpMap transforms coordinates in the inverse direction, both component -Mappings are applied to the same coordinates, but in the inverse -direction. - -Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings -(\emph{i.e.}\ the numbers of input and output coordinates) will sum to -give the Nin and Nout attributes of the overall CmpMap. - -\subsection{\label{ss:cmpmapcomponents}The Component Mappings} - -A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply -holds pointers to them. In the example above -(\secref{ss:seriescmpmap}), we were free to annul the individual -\htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held -internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount} -attribute) of each component Mapping by one. The individual components -are therefore not deleted by \htmlref{astAnnul}{astAnnul}, but retained until the CmpMap -itself is deleted and annuls the pointers it holds. Consistent use of -astAnnul (\secref{ss:annullingpointers}) and/or pointer contexts -(\secref{ss:contexts}) will therefore ensure that all Objects are -deleted at the appropriate time. - -Note that access to a CmpMap's component Mappings is not generally -available unless pointers to them are retained when the CmpMap is -created. If such pointers are retained, then subsequent modifications -to the individual components can be used to indirectly modify the -behaviour of the overall CmpMap. - -There is an important exception to this, however, because a CmpMap -retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its -components and uses these in order to ignore any subsequent external -changes. This means that you may invert either component Mapping -before inserting it into a CmpMap and need not worry if you un-invert -it again later. The CmpMap's behaviour will not be affected by the -later action. - -\subsection{\label{ss:complexcmpmap}Creating More Complex Mappings} - -Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can -substitute (\secref{ss:objecthierarchy}) as a component Mapping when -constructing a new CmpMap using \htmlref{astCmpMap}{astCmpMap}. This has the effect of -nesting one CmpMap inside another and opens up many new possibilities. -For example, combining three Mappings in series can be accomplished as -follows: - -\small -\begin{terminalv} -AstMapping *map1, *map2, *map3; - -... - -cmpmap = astCmpMap( map1, astCmpMap( map2, map3, 1, "" ), 1, "" ); -\end{terminalv} -\normalsize - -The way in which the individual component Mappings are grouped within -the nested CmpMaps is not usually important. - -A similar technique can be used to combine multiple Mappings in -parallel and, of course, mixed series and parallel combinations are -also possible (Figure~\ref{fig:complexcmpmap}). There is no built-in -limit to how many CmpMaps may be nested in this way, so this mechanism -provides an indefinitely extensible method of building complex -Mappings out of the elemental building blocks provided by AST. - -In practice, you might not need to construct such complex CmpMaps -yourself very frequently, but they will often be returned by AST -routines. Nested CmpMaps underlie the library's entire ability to -represent a wide range of different coordinate transformations. - -\subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images} - -Consider, as a practical example of CmpMaps, two images of the -sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from -pixel coordinates to a standard celestial coordinate system, say -FK5~(J2000.0). If we wish to inter-compare these images, we can do so -by using this celestial coordinate system to align them. That is, we -first convert from pixel coordinates in the first image into FK5 -coordinates and we then convert from FK5 coordinates into pixel -coordinates in the second image. - -If ``mapa'' and ``mapb'' are pointers to our two original Mappings, we -could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel -coordinates of the first and second images by combining these -Mappings, as follows: - -\small -\begin{terminalv} -AstCmpMap *alignmap; -AstMapping *mapa, *mapb; - -... - -astInvert( mapb ); -alignmap = astCmpMap( mapa, mapb, 1, "" ); -astInvert( mapb ); -\end{terminalv} -\normalsize - -Here, we have used \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}) to invert -``mapb'' before inserting it into the CmpMap because, as supplied, it -converted in the wrong direction. Afterwards, we invert it again to -return it to its original state. The CmpMap, however, will ignore this -subsequent change (\secref{ss:cmpmapcomponents}). - -The forward transformation of the resulting CmpMap will now transform -from pixel coordinates in the first image to pixel coordinates in the -second image, while its inverse transformation will convert in the -opposite direction. - -\subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings} - -While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing -arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it -unfortunately also provides an opportunity for representing simple -Mappings in complex ways. Sometimes, unnecessary complexity can be -difficult to avoid but can obscure important simplifications. - -Consider the example above (\secref{ss:cmpmapexample}), in which we -inter-related two images of the sky \emph{via} a CmpMap. If the two -images turned out to be simply offset from each other by a shift along -each pixel axis, then this approach would align them correctly, but it -would be inefficient. This is because it would introduce unnecessary -and expensive transformations to and from an intermediate celestial -coordinate system, whereas a simple shift of pixel origin would -suffice. - -Recognising that a simpler and more efficient solution exists -obviously requires a little more than simply joining two Mappings -end-to-end. We must also determine whether the resulting CmpMap is -more complex than it needs to be, \emph{i.e.}\ contains redundant -information. If it is, we then need a way to simplify it. - -The problem is not always just one of efficiency, however. Sometimes -we may also need to know something about the actual form a \htmlref{Mapping}{Mapping} -takes---\emph{i.e.}\ the nature of the operations it performs. -Unnecessary complexity can obscure this, but such complexity can -easily accumulate during normal data processing. - -For example, a Mapping that transforms pixel coordinates into -positions on the sky might be repeatedly modified as changes are made -to the shape and size of the image. Typically, on each occasion, -another Mapping will be concatenated to reflect what has happened to -the image. This could soon make it difficult to discern the overall -nature of the transformation from the complex CmpMap that -accumulates. If only shifts of origin were involved on each occasion, -however, they could be combined into a single shift which could be -represented much more simply. - -Suppose we now wanted to represent our image's celestial coordinate -calibration using FITS conventions (\secref{ss:foreignfits}). This -requires AST to determine whether the Mapping which relates pixel -coordinate to sky positions conforms to the FITS model (for example, -whether it is equivalent to applying a single set of shifts and scale -factors followed by a map projection). Clearly, there is an important -use here for some means of simplifying the internal structure of a -CmpMap. - -\subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings} - -The ability to simplify compound Mappings is provided by the -\htmlref{astSimplify}{astSimplify} function. This function encapsulates a number of -heuristics for converting Mappings, or combinations of Mappings within -a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap, -astSimplify tries to reduce the number of individual Mappings within -it by merging neighbouring component Mappings together. It will do -this with both series and parallel combinations of Mappings, or both, -and will handle CmpMaps nested to any depth -(\secref{ss:complexcmpmap}). - - To illustrate how astSimplify works, consider the combination of - Mappings shown in Figure~\ref{fig:simplifyexample}. - \begin{figure} - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/simpexamp} - \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps, - ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single - UnitMap. The enclosing nested CmpMaps have been omitted for clarity.} - \label{fig:simplifyexample} - \end{center} - \end{figure} - -If this were contained in a CmpMap, it could be simplified as follows: - -\small -\begin{terminalv} -AstMapping *simpler; - -... - -simpler = astSimplify( cmpmap ); -\end{terminalv} -\normalsize - -In this case, the result would be a simple 3-dimensional UnitMap (the -identity \htmlref{Mapping}{Mapping}). To reach this conclusion, astSimplify will have -made a number of deductions, roughly as follows: - -\begin{enumerate} -\item The two 2-dimensional ZoomMaps in series are equivalent to a -single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is -equivalent to a 2-dimensional UnitMap. - -\item This UnitMap in parallel with the other 1-dimensional UnitMap is -equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched -between any other pair of Mappings, can then be eliminated. - -\item The remaining two PermMaps in series are equivalent to a single -3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap -is found to be equivalent to a 3-dimensional UnitMap. -\end{enumerate} - -This example is a little contrived, but illustrates how astSimplify -can deal with even quite complicated compound Mappings through a -series of incremental simplifications. Where possible, this will -result in either a simpler compound Mapping or, if feasible, an atomic -(non-compound) Mapping, as here. If no simplification is possible, -astSimplify will just return a pointer to the original Mapping. - -Although astSimplify cannot identify every simplification that is -theoretically possible, sufficient rules are included to deal with the -most common and important cases. - -\cleardoublepage -\section{\label{ss:frames}Representing Coordinate Systems (Frames)} - -An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate -system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is -used to describe how to convert between coordinate systems. The two -concepts are complementary and we will see how they work together in -\secref{ss:framesets}. - -In this section we will discuss only basic Frames, which represent -Cartesian coordinate systems. More specialised types of Frame -(\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate -systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate -systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes}) -and, naturally, inherit the properties and behaviour of the simple Frames -discussed here. - -\subsection{The Frame Model} - -The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would -plot around a graph. In two dimensions, you would have an ``$x$'' and -a ``$y$'' axis, a title on the graph and labels on the axes, together -with an indication of the physical units being plotted. The values -marked along each axis would be formatted in a human-readable way. The -frame around a graph therefore defines a coordinate space within which -you can locate points, draw lines, calculate distances, \emph{etc.} - -An AST Frame works in much the same way, embodying all of these -concepts and a few more. It also allows any number of axes, which -means that a Frame can represent coordinate systems with any number of -dimensions. You specify how many when you create it. - -Remember that the basic Frame we are considering here is completely -general. It knows nothing of celestial coordinates, for example, and -all its axes are equivalent. It can be adapted to describe any general -purpose Cartesian coordinate system by setting its attributes, such as -its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values. - -\subsection{\label{ss:creatingframes}Creating a Frame} - -Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern: - -\small -\begin{terminalv} -#include "ast.h" -astFrame *frame; - -... - -frame = astFrame( 2, "" ); -\end{terminalv} -\normalsize - -The first argument of the \htmlref{astFrame}{astFrame} constructor function specifies the -number of axes which the Frame should have. - -\subsection{\label{ss:frameasmapping}Using a Frame as a Mapping} - -We should briefly point out that the \htmlref{Frame}{Frame} we created above -(\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping} -(\secref{ss:mappingclass}) and therefore inherits the properties and -behaviour common to other Mappings. - -One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited -from the Mapping class) to a non-zero value and pass the Frame pointer -to a coordinate transformation function, such as \htmlref{astTran2}{astTran2}. - -\small -\begin{terminalv} -double xin[ 5 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 }; -double yin[ 5 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0 }; -double xout[ 5 ]; -double yout[ 5 ]; - -... - -astSet( frame, "Report=1" ); -astTran2( frame, 5, xin, yin, 1, xout, yout ); -\end{terminalv} -\normalsize - -The resulting output might then look like this: - -\begin{terminalv} -(1, 2) --> (1, 2) -(2, 4) --> (2, 4) -(3, 6) --> (3, 6) -(4, 8) --> (4, 8) -(5, 10) --> (5, 10) -\end{terminalv} - -This is not very exciting because a Frame implements an identity -transformation just like a \htmlref{UnitMap}{UnitMap} -(\secref{ss:unitmapexample}). However, it illustrates that a Frame can -be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both -equal to the number of Frame axes. - -When we consider more specialised Frames -(\emph{e.g.}~\secref{ss:framesets}), we will see that using them as -Mappings can be very useful indeed. - -\subsection{\label{ss:frameaxisattributes}Frame Axis Attributes} - -Frames have a number of attributes which can take multiple values, one -for each axis. These separate values are identified by appending the -axis number in parentheses to the attribute name. For example, the -Label(1) attribute is a character string containing the label which -appears on the first axis. - -\htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes -(\secref{ss:gettingattributes}, \secref{ss:settingattributes} and -\secref{ss:defaultingattributes}). For example, the Label on the second -axis might be obtained as follows: - -\small -\begin{terminalv} -const char *label; - -... - -label = astGetC( frame, "Label(2)" ); -\end{terminalv} -\normalsize - -Other attribute access functions (astSetX, \htmlref{astTest}{astTest} and \htmlref{astClear}{astClear}) may -also be applied to axis attributes in the same way. - -If the axis number is stored in a program variable, then its value -must be formatted to generate a suitable attribute name before using -this to access the attribute itself. For example, the following will -print out the Label value for each axis of a \htmlref{Frame}{Frame}: - -\small -\begin{terminalv} -#include <stdio.h> -char name[ 18 ]; -int iaxis, naxes; - -... - -naxes = astGetI( frame, "Naxes" ); -for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { - (void) sprintf( name, "Label(%d)", iaxis ); - label = astGetC( frame, name ); - (void) printf( "Label %2d: %s\n", iaxis, label ); -} -\end{terminalv} -\normalsize - -Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame -axes. - -The output from this might look like the following: - -\begin{terminalv} -Label 1: Axis 1 -Label 2: Axis 2 -\end{terminalv} - -In this case, the Frame's default axis Labels have been revealed as -rather un-exciting. Normally, you would set much more useful values, -typically when you create the Frame---perhaps something like: - -\small -\begin{terminalv} -frame = astFrame( 2, "Label(1)=Offset from centre of field," - "Unit(1) =mm," - "Label(2)=Transmission coefficient," - "Unit(2) =%" ); -\end{terminalv} -\normalsize - -Here, we have also set the (character string) Unit attribute for each -axis to describe the physical units represented on that axis. All the -attribute assignments have been combined into a single string, -separated by commas. - -\subsection{\label{ss:frameattributes}Frame Attributes} - -We will now briefly outline the various attributes associated with a -\htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the -\htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each -attribute, for which you should consult the appropriate description in -\appref{ss:attributedescriptions}. Instead, we aim simply to sketch -the range of facilities available: - -\begin{quote} -\begin{description} -\item[\htmlref{Naxes}{Naxes}]\mbox{}\\ -A read-only integer giving the number of Frame axes. - -\item[\htmlref{Title}{Title}]\mbox{}\\ -A string describing the coordinate system which the Frame represents. - -\item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\ -A label string for each axis. - -\item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\ -A string describing the physical units on each axis. You can choose -whether to make this attribute ``active'' or ``passive'' (using -\htmlref{astSetActiveUnit}{astSetActiveUnit} -). If active, its value will be taken into account when finding the -Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used -to connect two axis with units of ``km'' and ``m''). If passive, its value -is ignored. Its use is described in more detail in \secref{ss:frameunits}. - -\item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\ -A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X'' -or ``Y'') used to represent the quantity plotted on each axis. - -\item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\ -The preferred number of digits of precision to be used when formatting -values for display on each axis. - -\item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\ -A string containing a \emph{format specifier} which determines exactly -how values should be formatted for display on each axis -(\secref{ss:formattingaxisvalues}). If this attribute is un-set, the -formatting is based on the Digits value, otherwise the Format string -over-rides the Digits value. - -\item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\ -A boolean (integer) value which indicates in which direction each axis -should be plotted. If it is non-zero (the default), the axis should be -plotted in the conventional direction---\emph{i.e.}\ increasing to the -right for the abscissa and increasing upwards for the ordinate. If it -is zero, the axis should be plotted in reverse. This attribute is -provided as a hint only and programs are free to ignore it if they -wish. - -\item[\htmlref{Domain}{Domain}]\mbox{}\\ -A character string which identifies the \emph{physical domain} to -which the Frame's coordinate system applies. The primary purpose of -this attribute is to prevent unwanted conversions from occurring -between coordinate systems which are not related. Its use is described -in more detail in \secref{ss:framedomains}. - -\item[\htmlref{System}{System}]\mbox{}\\ -A character string which identifies the specific coordinate system used -to describe positions within the physical domain represented by the Frame. -For a simple Frame, this attribute currently has a fixed value of -``Cartesian'', but could in principle be extended to include options such -as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such -as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame} and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be -appropriate to the domain which they describe. For instance, the SkyFrame -allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows -values such as ``frequency'' and ``wavelength''. - -\item[\htmlref{Epoch}{Epoch}]\mbox{}\\ -This value is used to qualify a coordinate system by giving the moment in -time when the coordinates are correct. Usually, this will be the date of -observation. The Epoch value is important in cases where coordinates -systems move with respect to each other over time. An example of two such -coordinate systems are the FK4 and FK5 celestial coordinate systems. - -\item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\ -Specifies the longitude of the observer (assumed to be on the surface of -the earth). The basic Frame class does not use this value, but -specialised sub-classes may. For instance, the SpecFrame class uses it to -calculate the relative velocity of the observer and the centre of the -earth for use in converting between standards of rest. - -\item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\ -Specifies the latitude of the observer. Use in conjunction with ObsLon. - -\end{description} -\end{quote} - -There are also some further Frame attributes, not described above, -which are important when Frames are used as templates to search for -other Frames. Their use goes beyond the present discussion. -%TBW---Add reference here. - -\subsection{\label{ss:formattingaxisvalues}Formatting Axis Values} - -The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored -(\emph{e.g.}\ within your program) as double values. The Frame class -therefore provides a function, \htmlref{astFormat}{astFormat}, to convert these values into -formatted strings for display: - -\small -\begin{terminalv} -const char *string -double value; - -... - -string = astFormat( frame, iaxis, value ); -\end{terminalv} -\normalsize - -Here, the astFormat function is passed a Frame pointer, the number of -an axis (``iaxis'') and a double precision value to format -(``value''). It returns a pointer to character string containing the -formatted value. -\label{ss:formattingwithdigits} - -By default, the formatting applied will be determined by the Frame's -Digits attribute and will normally display results with seven digits -of precision (corresponding approximately to the C ``float'' data type -on many machines). Setting a different Digits value, however, allows -you to adjust the precision as necessary to suit the accuracy of the -coordinate data you are processing. If finer control is needed, it is -also possible to set a Digits value for each individual axis by -appending an axis number to the attribute name -(\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the -effect of the Frame's main Digits value for that axis. - -Even finer control is possible by setting the (character string) Format -attribute for a Frame axis. The string given should contain a C -\emph{format specifier} which explicitly determines how the values on -that axis should be formatted. This will over-ride the effects of any -Digits value\footnote{The exception to this rule is that if the Format -value includes a precision of ``$.*$'', then Digits will be used to -determine the actual precision used.}. Any valid ``printf'' format -specifier may be used so long as it consumes exactly one double value. - -When setting Format values, remember that the ``\%'' which appears in -the format specifier may need to be doubled to ``\%\%'' if you are -using a function (such as \htmlref{astSet}{astSet}) which interprets ``printf'' format -specifiers itself. - -It is recommended that you use astFormat whenever you display -formatted coordinate values, even although you could format them -yourself using ``sprintf''. This is because it puts the Frame in -control of formatting. When you start to handle more elaborate Frames -(representing, say, celestial coordinates), you will need different -formatting methods. This approach delivers them without any change to -your software. - -You should also consider regularly using the \htmlref{astNorm}{astNorm} function, -described below (\secref{ss:normalising}), for any values that will be -made visible to the user of your software. - -\subsection{\label{ss:normalising}Normalising Frame Coordinates} - -The function \htmlref{astNorm}{astNorm} is provided to cope with the fact that some -coordinate systems do not extend indefinitely in all directions. Some -may have boundaries, outside which coordinates are meaningless, while -others wrap around on themselves, so that after a certain distance you -return to the beginning again (coordinate systems based on circles and -spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but -other more specialised Frames (such as SkyFrames, representing the -celestial sphere---\secref{ss:skyframes}) do. - -The role played by astNorm is to \emph{normalise} any arbitrary set of -coordinates by converting them into a set which is ``within bounds'', -interpreted according to the particular Frame in question. For -example, on the celestial sphere, a right ascension value of 24~hours -or more can have a suitable multiple of 24~hours subtracted without -affecting its meaning and astNorm would perform this task. Similarly, -negative values of right ascension would have a multiple of 24~hours -added, so that the result lies in the range zero to 24~hours. The -coordinates in question are modified in place by astNorm, as follows: - -\small -\begin{terminalv} -double point[ 2 ]; - -... - -astNorm( frame, point ); -\end{terminalv} -\normalsize - -If the coordinates supplied are initially OK, as they would always be -with a basic Frame, then they are returned unchanged. - -Because the main purpose of astNorm is to convert coordinates into the -preferred range for human consumption, its use is almost always -appropriate immediately before formatting coordinate values for -display using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}). Even if -the Frame in question does not restrict the range of coordinates, so -that astNorm does nothing, using it will allow you to process other -more specialised Frames, where normalisation is important, without -changing your software. - -\subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values} - -The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame} -axis, such as might be produced by \htmlref{astFormat}{astFormat} -(\secref{ss:formattingaxisvalues}), back into a numerical (double) -value ready for processing is performed by \htmlref{astUnformat}{astUnformat}. However, -although this process is essentially the inverse of that performed by -astFormat, there are a number of additional difficulties that must be -addressed in practice. - -The main use for astUnformat is in reading formatted coordinate values -which have been entered by the user of a program, or read from a -file. As such, we can rarely assume that the values are neatly -formatted in the way that astFormat would produce. Instead, it is -usually desirable to allow considerable flexibility in the form of -input that can be accommodated, so as to permit ``free-format'' data -input by the user. In addition, we may need to extract individual -coordinate values embedded in other textual data. - -Underlying these requirements is the root difficulty that the textual -format used to represent a coordinate value will depend on the class -of Frame we are considering. For example, for a basic Frame, -astUnformat may have to read a value like ``1.25e-6'', whereas for a -more specialised Frame representing celestial coordinates it may have -to handle a value like ``-07d~49m~13s''. Of course, the format might -also depend on which axis is being considered. - -Ideally, we would like to write software that can handle any kind of -Frame. However, this makes it a little more difficult to analyse -textual input data to extract individual coordinate values, since we -cannot make assumptions about how the values are formatted. It would -not be safe, for example, simply to assume that the values being read -are separated by white space. This is not just because they might be -separated by some other character, but also because celestial -coordinate values might themselves contain spaces. In fact, to be -completely safe, we cannot make any assumptions about how a formatted -coordinate value is separated from the surrounding text, except that -it should be separated in some way which is not ambiguous. - -This is the very basic assumption upon which astUnformat works. It is -invoked as follows: - -\small -\begin{terminalv} -int n; - -... - -n = astUnformat( frame, iaxis, string, &value ); -\end{terminalv} -\normalsize - -It is supplied with a Frame pointer (``frame''), the number of an axis -(``iaxis'') and a character string to be read (``string''). If it -succeeds in reading a value, astUnformat returns the resulting -coordinate to the address supplied \emph{via} the final argument -(``\&value''). The returned function value indicates how many -characters were read from the string in order to obtain this result. - -The string is read as follows: - -\begin{enumerate} -\item Any white space at the start is skipped over. - -\item Further characters are considered, one at a time, until the next -character no longer matches any of the acceptable forms of input -(given the characters that precede it). The longest sequence of -characters which matches is then considered ``read''. - -\item If a suitable sequence of characters was read successfully, it -is converted into a coordinate value which is returned. Any white -space following this sequence is then skipped over and the total -number of characters consumed is returned as the function value. - -\item If the sequence of characters read is empty, or insufficient to -define a coordinate value, then the string does not contain a value to -read. In this case, the read is aborted and astUnformat returns a -function value of zero and no coordinate value. However, it returns -without error. -\end{enumerate} - -Note that failing to read a coordinate value does not constitute an -error, at least so far as astUnformat is concerned. However, an error -can occur if the sequence of characters read appears to have the -correct form but cannot be converted into a valid coordinate -value. Typically, this will be because it violates some constraint, -such as a limit on the value of one of its fields. The resulting error -message will give details. - -For any given Frame axis, astUnformat does not necessarily always use -the same algorithm for converting the sequence of characters it reads -into a coordinate value. This is because some forms of input -(particularly free-format input) can be ambiguous and might be -interpreted in several ways depending on the context. For example, the -celestial longitude ``12:34:56.7'' could represent an angle in degrees -or a right ascension in hours. To decide which to use, astUnformat may -examine the Frame's attributes and, in particular, the appropriate -\htmlref{Format(axis)}{Format(axis)} string which is used by astFormat when formatting -coordinate values (\secref{ss:formattingaxisvalues}). This is done in -order that astFormat and astUnformat should complement each other---so -that formatting a value and then un-formatting it will yield the -original value, subject to any rounding error. - -To give a simple (but crucially incomplete!) example, consider reading -a value for the axis of a basic Frame, as follows: - -\small -\begin{terminalv} -n = astUnformat( frame, iaxis, " 1.5e6 -99.0", &value ); -\end{terminalv} -\normalsize - -astUnformat will skip over the initial space in the string supplied -and then examine each successive character. It will accept the -sequence ``1.5e6'' as input, but reject the space which follows -because it does not form part of the format of a floating point -number. It will then convert the characters ``1.5e6'' into a -coordinate value and skip over the three spaces which follow them. The -returned function value will therefore be 9, equal to the total number -of characters consumed. This result may be used to address the string -during a subsequent read, so as to commence reading at the start of -``-99.0''. - -Most importantly, however, note that if the user of a program -mistakenly enters the string ``~1.5r6\ldots'' instead of -``~1.5e6\ldots'', a coordinate value of 1.5 and a function result of 4 -will be returned, because the ``r'' would prematurely terminate the -attempt to read the value. Because this sort of mistake does not -automatically result in an error but can produce incorrect results, it -is \textbf{vital} to check the returned function value to ensure that -the expected number of characters have been read.\footnote{Anyone who -seriously uses the C run time library ``scanf'' function will know -about the need for this check!} For example, if the string is -expected to contain exactly one value, and nothing else, then the -following would suffice: - -\small -\begin{terminalv} -n = astUnformat( frame, iaxis, string, &value ); -if ( astOK ) { - if ( string[ n ] || !n ) { - <error in input data> - } else { - <value read correctly> - } -} -\end{terminalv} -\normalsize - -If astUnformat does not detect an error itself, we check that it has -read to the end-of-string and consumed at least one character (which -traps the case of a zero-length input string). If this reveals an -error, the value of ``n'' indicates where it occurred. - -Another common requirement is to obtain a position by reading a list -of coordinates from a string which contains one value for each axis of -a Frame. We assume that the values are separated in some unambiguous -manner, perhaps using white space and/or some unspecified -single-character separator. The choice of separator is up to the data -supplier, who must choose it so as not to conflict with the format of -the coordinate values, but our software does not need to know what it -is. The following is a template algorithm for reading data in this -form: - -\small -\begin{terminalv} -const char *s; -double values[ 10 ]; - -... - -/* Initialise a string pointer. */ -s = string; - -/* Obtain the number of Frame axes and loop through them. */ -naxes = astGetI( frame, "Naxes" ); -for ( iaxis = 1; iaxis <= naxes; iaxis++ ) { - -/* Attempt to read a value for this axis. */ - n = astUnformat( frame, iaxis, s, &values[ iaxis - 1 ] ); - -/* If nothing was read and this is not the first axis or the - end-of-string, try stepping over a separator and reading again. */ - if ( !n && ( iaxis > 1 ) && *s ) - n = astUnformat( frame, iaxis, ++s, &values[ iaxis - 1 ] ); - -/* Quit if nothing was read, otherwise move on to the next value. */ - if ( !n ) break; - s += n; -} - -/* Check for possible errors. */ -if ( astOK ) { - if ( *s || !n ) { - <error in input data> - } else { - <values read correctly> - } -} -\end{terminalv} -\normalsize - -In this case, ``s'' will point to the location of any input error. - -Note that this algorithm is insensitive to the precise format of the -data and will therefore work with any class of Frame and any -reasonably unambiguous input data. For example, here is a range of -suitable input data for a 3-dimensional basic Frame: - -\small -\begin{terminalv} -1 2.5 3 -3.1,3.2,3.3 -1.5, 2.6, -9.9e2 --1.1+0.4-1.8 - .1/.2/.3 - 44.0 ; 55.1 -14 -\end{terminalv} -\normalsize - -\subsection{\label{ss:permutingaxes}Permuting Frame Axes} - -Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number -of axes it contains, but it is possible to change the order in which -these axes occur. To do so, an integer \emph{permutation array} is -filled with the numbers of the axes so as to specify the new order, -\emph{e.g.:} - -\small -\begin{terminalv} -int perm[ 2 ] = { 2, 1 }; -\end{terminalv} -\normalsize - -In this case, the axes of a 2-dimensional Frame could be interchanged -by passing this permutation array to the \htmlref{astPermAxes}{astPermAxes} function. That -is, an ($x_1,x_2$) coordinate system would be changed into an -($x_2,x_1$) coordinate system by: - -\small -\begin{terminalv} -astPermAxes( frame, perm ); -\end{terminalv} -\normalsize - -If the axes are permuted more than once, the effects are cumulative. -You are, of course, not restricted to Frames with only two axes. - -\subsection{Selecting Frame Axes} - -An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not -allowed, is to create a new Frame by selecting axes from an existing -one. The method of doing this is very similar to the way \htmlref{astPermAxes}{astPermAxes} -is used (\secref{ss:permutingaxes}), in that we supply an integer -array filled with the numbers of the axes we want, in their new -order. In this case, however, the number of array elements need not -equal the number of Frame axes. - -For example, we could select axes 3 and 2 (in that order) from a -3-dimensional Frame as follows: - -\small -\begin{terminalv} -astFrame *frame1, *frame2; -astMapping *mapping; -int pick[ 2 ] = { 3, 2 }; - -... - -frame2 = astPickAxes( frame1, 2, pick, &mapping ); -\end{terminalv} -\normalsize - -This would return a pointer to a 2-dimensional Frame (``frame2'') -which contains the information associated with axes 3 and 2, in that -order, from the original Frame (``frame1''). The original Frame is not -altered by this process. Beware, however, that the axis information -may still be shared by both Frames, so if you wish to alter either of -them independently you may first need to use \htmlref{astCopy}{astCopy} -(\secref{ss:copyingobjects}) to make an independent copy. - -In addition to the new Frame pointer, \htmlref{astPickAxes}{astPickAxes} will also return a -pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument (you may supply a -NULL pointer as an argument if you do not want this Mapping). This -Mapping will inter-relate the two Frames. By this we mean that its -forward transformation will convert coordinates originally in the -coordinate system represented by ``frame1'' into that represented by -``frame2'', while its inverse transformation will convert in the -opposite direction. In this particular case, the Mapping would be a -\htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following -transformations: - -\begin{terminalv} -Forward: - (1, 2, 3) --> (3, 2) - (2, 4, 6) --> (6, 4) - (3, 6, 9) --> (9, 6) - (4, 8, 12) --> (12, 8) - (5, 10, 15) --> (15, 10) - -Inverse: - (3, 2) --> (<bad>, 2, 3) - (6, 4) --> (<bad>, 4, 6) - (9, 6) --> (<bad>, 6, 9) - (12, 8) --> (<bad>, 8, 12) - (15, 10) --> (<bad>, 10, 15) -\end{terminalv} - -This is our first introduction to the idea of inter-relating pairs of -Frames \emph{via} a Mapping, but this will assume a central role later on. - -Note that when using astPickAxes, it is also possible to request more -axes than there were in the original Frame. This will involve -selecting axes from the original Frame that do not exist. To do this, -the corresponding axis number (in the ``pick'' array) should be set to -zero and the effect is to introduce an additional new axis which is -not derived from the original Frame. This axis will have default -values for all its attributes. You will need to do this because -astPickAxes does not allow you to select any of the original axes more -than once.\footnote{It will probably not be obvious why this -restriction is necessary, but consider creating a Frame with one -longitude axis and two latitude axes. Which latitude axis should be -associated with the longitude axis?} - -\subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets} -Some complementary -functions -are provided for use with Frames to allow you to perform geometric -operations without needing to know the nature of the coordinate system -represented by the \htmlref{Frame}{Frame}. - -Functions -can be used to find the distance between two points, and to offset a -specified distance along a line joining two points, \emph{etc.} In essence, -these define the metric of the coordinate space which the Frame represents. In -the case of a basic Frame, this is a Cartesian metric. - -The first of these functions, \htmlref{astDistance}{astDistance}, returns a double distance -value when supplied with the Frame coordinates of two points. For -example: - -\small -\begin{terminalv} -double dist; -double point1[ 2 ] = { 0.0, 0.0 }; -double point2[ 2 ] = { 1.0, 1.0 }; - -... - -dist = astDistance( frame, point1, point2 ); -\end{terminalv} -\normalsize - -This calculates the distance between the origin (0,0) and a point at -position (1,1). In this case, the result, as you would expect, is -$\surd{2}$. However, this is only true for the Cartesian coordinate -system which a basic Frame represents. In general, astDistance will -calculate the geodesic distance between the two points, so that with a -more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial -sphere) a great-circle distance might be returned. - -The \htmlref{astOffset}{astOffset} function is really the inverse of astDistance. Given two -points in a Frame, it calculates the coordinates of a third point -which is offset a specified distance away from the first point along -the geodesic joining it to the second one. For example: - -\small -\begin{terminalv} -double point1[ 2 ] = { 0.0, 0.0 }; -double point2[ 2 ] = { 1.0, 1.0 }; -double point3[ 2 ]; - -... - -astOffset( frame, point1. point2, 0.5, point3 ); -\end{terminalv} -\normalsize - -This would fill the ``point3'' array with the coordinates of a point -which is offset 0.5 units away from the origin (0,0) in the direction -of the position (1,1). Again, this is a simple result in a Cartesian -Frame, as varying the offset will trace out a straight line. On the -celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would -trace out a great circle. - -The functions \htmlref{astAxDistance}{astAxDistance} and \htmlref{astAxOffset}{astAxOffset} are similar to astDistance -and astOffset, except that the curves which they use as ``straight -lines'' are not geodesics, but curves parallel to a specified axis\footnote -{For instance, a line of constant Declination is not a geodesic}. One -reason for using these functions is to deal with the cyclic ambiguity of -longitude and latitude axes. - -The \htmlref{astOffset2}{astOffset2} function is similar to astOffset, but instead of using the -geodesic which passes through two positions, it uses the geodesic which -passes at a given position angle through the starting position. - -Position angles are always measured from the positive direction of the -second Frame axis to the required line, with positive angles being in the -same sense as rotation from the positive direction of the second axis to -the positive direction of the first Frame axis. This definition applies -to all classes of Frame, including SkyFrame. The default ordering of axes -in a SkyFrame makes the second axis equivalent to north, and so the -definition of position angle given above corresponds to the normal -astronomical usage, ``from north, through east''. However, it should be -remembered that it is possible to permute the axes of a SkyFrame (or -indeed any Frame), so that north becomes axis 1. In this case, an AST -``position angle'' would be the angle ``from east, through north''. -Always take the axis ordering into account when deriving an astronomical -position angle from an AST position angle. - -Within a Cartesian coordinate system, the position angle of a geodesic -(\emph{i.e.}\ a straight line) is constant along its entire length, but -this is not necessarily true of other coordinate systems. Within a -spherical coordinate system, for instance, the position angle of a geodesic -will vary along its length (except for the special cases of a meridian and -the equator). In addition to returning the required offset position, the -astOffset2 function -returns the position angle of the geodesic at the -offset position. This is useful if you want to trace out a path which -involves turning through specified angles. For instance, tracing out a -rectangle in which each side is a geodesic involves turning through 90 -degrees at the corners. To do this, use astOffset2 to calculate the -position of each corner, and then add (or subtract) 90 degrees from the -position angle returned by astOffset2. - -The \htmlref{astAngle}{astAngle} function -calculates the angle subtended by two points, at a third point. -If used with a 2-dimensional Frame the returned angle -is signed to indicate the sense of rotation (clockwise or anti-clockwise) -in taking the ``shortest route'' from the first point to the second. -If the Frame has more than 2 axes, the result is un-signed and is always -in the range zero to $\pi$. - -The \htmlref{astAxAngle}{astAxAngle} function is similar to astAngle, -but the ``reference direction'', from which angles are measured, is -a specified axis. - -The \htmlref{astResolve}{astResolve} function -resolves a given displacement within a Frame into two components, parallel and -perpendicular to a given reference direction. - -The displacement is specified by two positions within the Frame; the -starting and ending positions. The reference direction is defined by the -geodesic curve passing through the starting position and a third specified -position. The lengths of the two components are returned, together with -the position on the reference geodesic which is closest to the third -supplied point. - -\subsection{\label{ss:framedomains}The Domain Attribute} - -The \htmlref{Domain}{Domain} attribute is one of the most important properties of a -\htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little -subtle. We will introduce it here, but its true value will probably -not become apparent until later (\secref{ss:framesetconverting}). - -To understand the need for the Domain attribute, consider using -different Frames to represent the following different coordinate -systems associated with a CCD image: - -\begin{enumerate} -\item A coordinate system based on pixel numbers. - -\item Positions on the CCD chip, measured in $\mu$m. - -\item Positions in the focal plane of the telescope, measured in mm. - -\item A celestial coordinate system, measured in radians. -\end{enumerate} - -If we had two such CCD images, we might legitimately want to align -them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based -on pixel numbers) in order to, say, divide by a flat-field exposure. -We might similarly consider aligning them using any of the other -coordinate systems so as to achieve different results. For example, we -might consider merging separate images from a CCD mosaic by using -focal plane positions. - -It would obviously not be legitimate, however, to directly compare -positions in one image measured in pixels with positions in the other -measured in mm, nor to equate chip positions in $\mu$m with sky -coordinates in radians. If we wanted to inter-compare these -coordinates, we would need to do it indirectly, using other -information based on the experimental set-up. For instance, we might -need to know the size of the pixels expressed in mm and the -orientation of the CCD chip in the focal plane. - -Note that it is not simply the difference in physical units which -prevents certain coordinates from being directly inter-compared -(because the appropriate unit scaling factors could be included -without any additional information). Neither is it the fact that -different coordinate systems are in use (because we could legitimately -inter-compare two different celestial coordinate systems without any -extra information). Instead, it is the different nature of the -coordinate spaces to which these coordinate systems have been applied. - -We normally express this by saying that the coordinate systems apply -to different \emph{physical domains}. Although we may establish -\emph{ad hoc} relationships between coordinates in different physical -domains, they are not intrinsically related to each other and we need -to supply extra information before we can convert coordinates between -them. - -In AST, the role of the (character string) Domain attribute is to -assign Frames to their respective physical domains. The way it -operates is as follows: - -\begin{itemize} -\item Coordinate systems which apply to the same physical domain -(\emph{i.e.}\ whose Frames have the same Domain value) can be directly -inter-compared. - -If the domain has several coordinate systems associated with it -(\emph{e.g.}\ the celestial sphere), then a coordinate conversion may -be involved. Otherwise, coordinate values may simply be equated. - -\item Coordinate systems which apply to different physical domains -(\emph{i.e.}\ whose Frames have different Domain values) cannot be -directly inter-compared. - -If any relationship does exist between such coordinate systems---and -it need not---then additional information must be supplied in order to -establish the relationship between them in any particular case. We -will see later (\secref{ss:framesets}) how to establish such -relationships between Frames in different domains. -\end{itemize} - -With the basic Frames we are considering here, each physical domain only -has a single (Cartesian) coordinate system associated with it, so that if -two such Frames have the same Domain value, their coordinate systems will -be identical and may simply be equated. With more specialised Frames, -however, more than one coordinate system may apply to each domain. In -such cases, a coordinate conversion may need to be performed. - -When a basic Frame is created, its Domain attribute defaults to an -empty string. This means that all such Frames belong to the same -(null) domain by default and therefore describe the same unspecified -physical coordinate space. In order to assign a Frame to a different -domain, you simply need to set its Domain value. This is normally most -conveniently done when it is created, as follows: - -\small -\begin{terminalv} -frame1 = astFrame( 2, "Domain=CCD_CHIP," - "Unit(1)=micron," - "Unit(2)=micron" ); -frame2 = astFrame( 2, "Domain=FOCAL_PLANE," - "Unit(1)=mm," - "Unit(2)=mm" ); -\end{terminalv} -\normalsize - -Here, we have created two Frames in different physical -domains. Although their coordinate values all have units of length, -they cannot be directly inter-compared (because their axes may be -rotated with respect to each other, for instance). - -All Domain values are automatically converted to upper case and white -space is removed, but there are no other restrictions on the names you -may use to label different physical domains. From a practical point of -view, however, it is worth following a few conventions -(\secref{ss:domainconventions}). - -\subsection{\label{ss:domainconventions}Conventions for Domain Names} - -When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it -obviously makes sense to avoid generic names which might clash with -those used for similar (but subtly different!) purposes by other -programmers. If you are developing software for an instrument, for -example, and want to identify an instrumental coordinate system, then -it is sensible to add a distinguishing prefix. For instance, you might -use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an -acronym) identifies your instrument. - -For some purposes, however, a standard choice of Domain name is -desirable so that different items of software can communicate. For -this purpose, the following Domain names are reserved by AST and the -use recommended below should be carefully observed: - -\begin{quote} -\begin{description} -\item[GRAPHICS]\mbox{}\\ -Identifies the coordinate space used by an underlying computer -graphics system to specify plotting operations. Typically, when -performing graphical operations, AST is used to define additional -coordinate systems which are related to these ``native'' graphical -coordinates. Plotting may be carried out in any of these coordinate -systems, but the GRAPHICS domain identifies the native coordinates -through which AST communicates with the underlying graphics system. - -\item[GRID]\mbox{}\\ -Identifies the instantaneous \emph{data grid} used to store and handle -data, together with an associated coordinate system. In this -coordinate system, the first element stored in an array of data always -has a coordinate value of unity at its centre and all elements have -unit extent. This applies to all dimensions. - -If data are copied or transformed to a new data grid (by whatever -means), or a subset of the original grid is extracted, then the same -rules apply to the copy or subset. Its first element therefore has -GRID coordinate values of unity at its centre. Note that this means -that GRID coordinates remain attached to the first element of the data -grid and not to its data content (\emph{e.g.}\ the features in an -image). - -\item[PIXEL]\mbox{}\\ -Identifies an array of pixels and an associated \emph{pixel-based} -coordinate system which is related to the GRID coordinate system -(above) simply by a shift of origin along each axis. This shift may be -integral, fractional, positive, negative or zero. The data elements -retain their unit extent along each axis. - -Because the amount of shift is unspecified, the PIXEL domain is -distinct from the GRID domain. The relationship between them contains -a degree of uncertainty, such as typically arises from the different -conventions used by different software systems. For instance, in some -software the first pixel is regarded as being centred at (1,1), while -in other software it is at (0.5,0.5). In addition, some software -packages implement a ``pixel origin'' which allows pixel coordinates -to start at an arbitrary value. - -The GRID domain (which corresponds with the pixel-numbering convention -used by FITS) is a special case of the PIXEL domain and avoids this -uncertainty. In general, additional information is required in order -to convert from one to the other. - -\item[SKY]\mbox{}\\ -Identifies the domain which contains all equivalent celestial -coordinate systems. Because these are represented in AST by SkyFrames -(\secref{ss:skyframes}), it should be no surprise that the default -Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you -probably won't need to change this very often. - -\item[SPECTRUM]\mbox{}\\ -Identifies the domain used to describe positions within an -electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes}) -class describes positions within this domain, allowing a wide range of -different coordinate systems to be used (frequency, wavelength, -\emph{etc}). The default Domain value for a SpecFrame is SPECTRUM. - -\item[TIME]\mbox{}\\ -Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame} -class describes positions within this domain, allowing a wide range of -different coordinate systems and timescales to be used. The default Domain -value for a TimeFrame is TIME. - -\end{description} -\end{quote} - -Although we have drawn a necessary distinction here between the GRID -and PIXEL domains, we will continue to refer in general terms to image -``pixels'' and ``pixel coordinates'' whenever this distinction is not -important. This should not be taken to imply that the GRID convention -for numbering pixels is excluded---in fact, it is usually to be -preferred (at the level of data handling being discussed in this -document) and we recommend it. - -\subsection{\label{ss:frameunits}The Unit Attribute} -Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used -to describe positions on the axis. The index of the axis to which the -attribute refers should normally be placed in parentheses following the -attribute name (``Unit(2)'' for instance). However, if the Frame has only -a single axis, then the axis index can be omitted. - -In versions of AST prior to version 2.0, the Unit attribute was nothing -more than a descriptive string intended purely for human readers---no -part of the AST system used the Unit string for any purpose (other than -inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no -account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between -two Frames. Thus if the conversion between a pair of 1-dimensional Frames -representing velocity was found (using -\htmlref{astConvert}{astConvert} -) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit -attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is -referred to below as a \emph{passive} Unit attribute. - -As of AST version 2.0, a facility exists which allows the Unit attribute -to be \emph{active}; that is, differences in the -Unit attribute may be taken into account when finding the Mapping between -two Frames. In order to minimise the risk of breaking older software, the -\emph{default} behaviour of simple Frames and SkyFrames is unchanged from -previous versions (\emph{i.e.} they have passive Unit attributes). However, -the new -functions \htmlref{astSetActiveUnit}{astSetActiveUnit} and \htmlref{astGetActiveUnit}{astGetActiveUnit} -allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame} -classes \emph{always} have an active Unit attribute (attempts to change this -are ignored). - -For instance, consider the above example of two 1-dimensional Frames -describing velocity. These Frames can be created as follows: - -\small -\begin{terminalv} -AstFrame *frame1, *frame2; -frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" ); -frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" ); -\end{terminalv} -\normalsize - -By default, these Frames have passive Unit attributes, and so an attempt -to find a Mapping between them would ignore the difference in their Unit -attributes and return a unit Mapping. To avoid this, we indicate that we -want these Frames to have \emph{active} Unit attributes, as follows: - -\small -\begin{terminalv} -astSetActiveUnit( frame1, 1 ); -astSetActiveUnit( frame2, 1 ); -\end{terminalv} -\normalsize - -If we then find the Mapping between them as follows: - -\small -\begin{terminalv} -AstFrameSet *cvt; -... -cvt = astConvert( frame1, frame2, "" ); -\end{terminalv} -\normalsize - -the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by -astConvert -will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a -velocity in $km/h$) by a factor of 0.278 to create its output (a velocity -in $m/s$). - -In fact we need not have set the Unit attribute active in ``frame1'' -since the behaviour of astConvert is determined by its ``to'' Frame -(the second Frame parameter). - -\subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings} -Conversion between units systems relies on the use of a specific syntax -for the Unit attribute. If the value of the Unit attribute does not -conform to this syntax, then an error will be reported if an attempt is -made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen -if the Unit attribute is \emph{passive}). - -The adopted syntax is that described in FITS-WCS paper I "Representation -of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish -here between ``basic'' units and ``derived'' units: derived units are -defined in terms of other units (either derived or basic), whereas basic -units have no such definitions. Derived units may be represented by their -own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a -\emph{mathematical expression} which combines other symbols and constants -to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per -second). Unit symbols may be prefixed by a string representing a standard -multiple or sub-multiple. - -In addition to the unit symbols listed in FITS-WCS Paper I, any other -arbitrary unit symbol may be used, with the proviso that it will not be -possible to convert between Frames using such units. The exception to -this is if both Frames refer to the same unknown unit string. For instance, -an axis with unknown unit symbol "flop" \emph{could} be converted to an axis -with unit "Mflop" (Mega-flop). - -Unit symbols (optionally prefixed with a multiple or sub-multiple) can be -combined together using a limited range of mathematical operators and -functions, to produce new units. Such expressions may also contain -parentheses and numerical constants (these may optionally use -``scientific'' notation including an ``E'' character to represent the -power of 10). - -The following tables list the symbols for the basic and derived units which -may be included in a units string, the standard prefixes for multiples -and sub-multiples, and the strings which may be used to represent -mathematical operators and functions. - -\begin{table}[htbp] -\begin{center} -\begin{tabular}{|l|l|l|} -\hline -\multicolumn{3}{|c|}{{\large Basic units}} \\ \hline -\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & -\multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline -length & m & metre \\ -mass & g & gram \\ -time & s & second \\ -plane angle & rad & radian \\ -solid angle & sr & steradian \\ -temperature & K & Kelvin \\ -electric current & A & Ampere \\ -amount of substance & mol & mole \\ -luminous intensity & cd & candela \\ -\hline -\end{tabular} -\end{center} -\end{table} - -\begin{table}[htbp] -\begin{center} -\begin{small} -\begin{tabular}{|l|l|l|l|} -\hline -\multicolumn{4}{|c|}{{\large Derived units}} \\ \hline -\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} & -\multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline -area & barn & barn & 1.0E-28 m**2 \\ -area & pix & pixel & \\ -area & pixel & pixel & \\ -electric capacitance & F & Farad & C/V \\ -electric charge & C & Coulomb & A s \\ -electric conductance & S & Siemens & A/V \\ -electric potential & V & Volt & J/C \\ -electric resistance & Ohm & Ohm & V/A \\ -energy & J & Joule & N m \\ -energy & Ry & Rydberg & 13.605692 eV \\ -energy & eV & electron-Volt & 1.60217733E-19 J \\ -energy & erg & erg & 1.0E-7 J \\ -events & count & count & \\ -events & ct & count & \\ -events & ph & photon & \\ -events & photon & photon & \\ -flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\ -flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\ -flux density & mag & magnitude & \\ -force & N & Newton & kg m/s**2 \\ -frequency & Hz & Hertz & 1/s \\ -illuminance & lx & lux & lm/m**2 \\ -inductance & H & Henry & Wb/A \\ -length & AU & astronomical unit & 1.49598E11 m \\ -length & Angstrom & Angstrom & 1.0E-10 m \\ -length & lyr & light year & 9.460730E15 m \\ -length & pc & parsec & 3.0867E16 m \\ -length & solRad & solar radius & 6.9599E8 m \\ -luminosity & solLum & solar luminosity & 3.8268E26 W \\ -luminous flux & lm & lumen & cd sr \\ -magnetic field & G & Gauss & 1.0E-4 T \\ -magnetic flux & Wb & Weber & V s \\ -mass & solMass & solar mass & 1.9891E30 kg \\ -mass & u & unified atomic mass unit & 1.6605387E-27 kg \\ -magnetic flux density & T & Tesla & Wb/m**2 \\ -plane angle & arcmin & arc-minute & 1/60 deg \\ -plane angle & arcsec & arc-second & 1/3600 deg \\ -plane angle & mas & milli-arcsecond & 1/3600000 deg \\ -plane angle & deg & degree & pi/180 rad \\ -power & W & Watt & J/s \\ -pressure, stress & Pa & Pascal & N/m**2 \\ -time & a & year & 31557600 s \\ -time & d & day & 86400 s \\ -time & h & hour & 3600 s \\ -time & yr & year & 31557600 s \\ -time & min & minute & 60 s \\ - & D & Debye & 1.0E-29/3 C.m \\ -\hline -\end{tabular} -\end{small} -\end{center} -\end{table} - -\begin{table}[htbp] -\begin{center} -\begin{tabular}{|lll|lll|} -\hline -\multicolumn{6}{|c|}{{\large Prefixes for multiples \& -sub-multiples}} \\ \hline -\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & -\multicolumn{1}{c|}{Prefix} & -\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} & -\multicolumn{1}{c|}{Prefix} \\ \hline -$10^{-1}$ & deci & d & $10$ & deca & da \\ -$10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\ -$10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\ -$10^{-6}$ & micro & u & $10^{6}$ & mega & M \\ -$10^{-9}$ & nano & n & $10^{9}$ & giga & G \\ -$10^{-12}$ & pico & p & $10^{12}$ & tera & T \\ -$10^{-15}$ & femto & f & $10^{15}$ & peta & P \\ -$10^{-18}$ & atto & a & $10^{18}$ & exa & E \\ -$10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\ -$10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\ -\hline -\end{tabular} -\end{center} -\end{table} - -\begin{table}[htbp] -\begin{center} -\begin{tabular}{|l|l|} -\hline -\multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\ -\hline -\multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline -sym1 sym2 & multiplication (a space) \\ -sym1*sym2 & multiplication (an asterisk) \\ -sym1.sym2 & multiplication (a dot) \\ -sym1/sym2 & division \\ -sym1**y & exponentiation ($y$ must be a numerical constant)\\ -sym1\verb+^+y & exponentiation ($y$ must be a numerical constant)\\ -log(sym1) & common logarithm \\ -ln(sym1) & natural logarithm \\ -exp(sym1) & exponential \\ -sqrt(sym1) & square root \\ -\hline -\end{tabular} -\end{center} -\end{table} - -\subsubsection{Side-effects of Changing the Unit attribute} -If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by -setting a new value or by clearing it so that the default value is -re-instated) may cause the Label and Symbol attributes to be changed -accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'', -``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)'' -will cause AST to change its Label and Symbol to ``log(Frequency)'' and -``Log(nu)''. These changes are only made if the Unit attribute is active, -and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other - hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change -to the Label or Symbol attributes. - -\cleardoublepage -\section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)} - -A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on -the celestial sphere is obviously of great importance in -astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine -the additional properties and behaviour of a SkyFrame that distinguish -it from a basic Frame (\secref{ss:frames}). - -\subsection{The SkyFrame Model} - -A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a -\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and -behaviour of these two ancestral classes. When used as a Mapping, a -SkyFrame implements a unit transformation, exactly like a basic Frame -(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its -behaviour is not of great importance. - -When used as a Frame, however, a SkyFrame represents a 2-dimensional -\emph{spherical} coordinate system, in which the shortest distance -between two points is a great circle. A SkyFrame therefore always has -exactly two axes which represent the longitude and latitude of a -coordinate system residing on the celestial sphere. Many such -coordinate systems can be represented by a SkyFrame, as we will see -shortly. - -A SkyFrame can represent any of the commonly used celestial coordinate -systems. Optionally, the origin of the longitude/latitude system can be -moved to any specified point in the standard celestial system, allowing -a SkyFrame to represent offsets from a specified sky position. - -When it is first created, a SkyFrame's axes are always in the order -(longitude,~latitude) but this can be changed, if required, by using the -\htmlref{astPermAxes}{astPermAxes} function (\secref{ss:permutingaxes}). The order of the axes -can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A -SkyFrame's coordinate values are always stored as angles in (double -precision) radians, regardless of the setting of the Unit attribute -\footnote{The units used for the internal floating-point representation of an -axis value can be determined by examining the InternalUnit attribute of -the Frame. For most Frames, the Unit and InternalUnit attributes will be -equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}. - -\subsection{Creating a SkyFrame} - -The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a -SkyFrame with default attributes is created as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstSkyFrame *skyframe; - -... - -skyframe = astSkyFrame( "" ); -\end{terminalv} -\normalsize - -Such a SkyFrame would represent the default celestial coordinate -system which, at present, is the ICRS system (the default was "FK5(J2000)" -in versions of AST prior to 3.0). - -\subsection{Specifying a Particular Celestial Coordinate System} - -For many purposes, the ICRS coordinate system is perfectly -adequate. In order to support conversion between a variety of -celestial coordinate systems, however, you can create SkyFrames that -represent any of these. - -Selection of a particular coordinate system is performed simply by -setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System} -attribute. This setting is most conveniently done when the SkyFrame is -created. For example, a SkyFrame representing the old FK4~(B1950.0) -coordinate system would be created by: - -\small -\begin{terminalv} -skyframe = astSkyFrame( "System=FK4" ); -\end{terminalv} -\normalsize - -Note that specifying ``System$=$FK4'' also changes the associated -equinox (from J2000.0 to B1950.0). This is because the default value -of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends -on the System attribute setting. - -You may change the System value at any time, although this is not -usually needed. The values supported are set out in the attribute's -description in \appref{ss:attributedescriptions} and include a variety -of equatorial coordinate systems, together with ecliptic and galactic -coordinates. - -General spherical coordinates are supported by specifying -``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be -created to convert between ``unknown'' coordinates and any of the other -celestial coordinate systems (see \secref{ss:introducingconversion} ). - -\subsection{Attributes which Qualify Celestial Coordinate Systems} - -Many celestial coordinate systems have some additional free parameters -which serve to identify a particular coordinate system from amongst a -broader class of related coordinate systems. For example, the -FK5~(J2010.0) system is distinguished from the FK5~(J2000.0) -system by a different equinox---and the coordinates of a fixed -astronomical source would have different values when expressed in -these two systems. - -In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame} -attributes, each of which has a default appropriate to -(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} -attribute. Each of these \emph{qualifying attributes} may, however, be -assigned an explicit value so as to select a particular coordinate -system. Note, it is usually best to assign explicit -values whenever possible rather than relying on defaults. Attribute -should only be left at their default value if you ``don't care'' what -value is used. In certain circumstances (particularly, when aligning two -Frames), a default value for an attribute may be replaced by the value -from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by -assigning an explicit value to the attribute, rather than simply relying on -the default. - - -The main SkyFrame attributes which qualify the System attribute are: - -\begin{quote} -\begin{description} - -\item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\ -This attribute is inherited from the Frame class. It gives the moment in -time when the coordinates are correct for the astronomical source -under study (usually the date of observation). - -\item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\ -This value is used to qualify celestial coordinate systems that are -notionally based on the Earth's equator and/or the ecliptic (the plane -of the Earth's orbit around the Sun). The position of either of these -planes is difficult to specify precisely, so in practice a model -\emph{mean} equator and/or ecliptic are used instead. These, together -with the point on the sky that defines the coordinate origin (termed -the \emph{mean equinox}) move with time according to some model which -smoothes out the more rapid fluctuations. The SkyFrame class supports -both the old FK4 model and the newer FK5 one. - -Coordinates expressed in any of these systems vary with time due to -movement (by definition) of the coordinate system itself, and must -therefore be qualified by a moment in time (the \emph{epoch of the mean -equinox}, or ``equinox'' for short) which specifies the position of -the model coordinate system on the sky. This is the role of the -Equinox attribute. - -Note that it is quite valid and common to relate the position of a -source to an equinox other than the date of observation. Usually a -standard equinox such as J2000.0 is used, meaning that the coordinates -are referred to axes defined by where the model mean equator and -ecliptic would lie on the sky at the Julian epoch J2000.0. -\end{description} -\end{quote} - -For further details of these attributes you should consult their -descriptions in \appref{ss:attributedescriptions} and for details of -the System settings for which they are relevant, see the description -of the System attribute (also in \appref{ss:attributedescriptions}). -For the interested reader, an excellent overview of celestial -coordinate systems can also be found in the documentation for the -SLALIB library (\xref{SUN/67}{sun67}{}). - -The value of these qualifying attributes is most conveniently set at -the same time as the System value, \emph{e.g.}\ when a SkyFrame is -created. For instance: - -\small -\begin{terminalv} -skyframe = astSkyFrame( "System=Ecliptic, Equinox=J2005.5" ); -\end{terminalv} -\normalsize - -would create a SkyFrame representing an ecliptic coordinate system -referred to the mean equinox and ecliptic of Julian epoch J2005.5. - -Note that it does no harm to assign values to qualifying attributes -which are not relevant to the main System value. Any such values are -stored, but are not used unless the System value is later set so that -they become relevant. - -\subsection{Using Default SkyFrame Attributes} - -The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend -on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this -means that there is usually little need to specify many of these -attributes explicitly unless you have some special requirement. This -can be illustrated by using \htmlref{astShow}{astShow} to examine a SkyFrame, as follows: - -\small -\begin{terminalv} -astShow( astSkyFrame( "System=FK4-NO-E, Epoch=1958" ) ); -\end{terminalv} -\normalsize - -The output from this might look like the following: - -\begin{terminalv} - Begin SkyFrame # Description of celestial coordinate system -# Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0; -epoch B1958.0" # Title of coordinate system - Naxes = 2 # Number of coordinate axes -# Domain = "SKY" # Coordinate system domain - Epoch = 1958 # Besselian epoch of observation -# Lbl1 = "Right ascension" # Label for axis 1 -# Lbl2 = "Declination" # Label for axis 2 - System = "FK4-NO-E" # Coordinate system type -# Uni1 = "hh:mm:ss.s" # Units for axis 1 -# Uni2 = "ddd:mm:ss" # Units for axis 2 -# Dir1 = 0 # Plot axis 1 in reverse direction -# Bot2 = -1.5707963267949 # Lowest legal axis value -# Top2 = 1.5707963267949 # Highest legal axis value - Ax1 = # Axis number 1 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - Ax2 = # Axis number 2 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - IsA Frame # Coordinate system description -# Eqnox = 1950 # Besselian epoch of mean equinox - End SkyFrame -\end{terminalv} - -Note that the defaults (indicated by the ``\verb?#?'' comment -character at the start of the line) for attributes such as the \htmlref{Title}{Title}, -axis Labels and Format specifiers are all set to values appropriate -for the particular equatorial coordinate system that the SkyFrame -represents. - -This means, for example, that if we were to use this SkyFrame to -format a right ascension value stored in radians using \htmlref{astFormat}{astFormat} -(\secref{ss:formattingaxisvalues}), it would automatically result in a -string in sexagesimal notation (such as ``12:14:35.7'') suitable for -display. If we changed the value of the SkyFrame's Digits attribute -(which is inherited from the \htmlref{Frame}{Frame} class), the number of digits -appearing would also change accordingly. - -These choices would be appropriate for a System value of ``FK4-NO-E'', -but if a different System value were set, the defaults would be -correspondingly different. For example, ecliptic longitude is -traditionally expressed in degrees, so setting ``System=ecliptic'' -would result in coordinate values being formatted as degrees by -default. - -Of course, if you do not like any of these defaults, you may always -over-ride them by setting explicit attribute values yourself. - -\subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates} - -SkyFrames use \htmlref{astFormat}{astFormat} for formatting coordinate values in the same -way as other Frames (\secref{ss:formattingaxisvalues}). However, they -offer a different set of formatting options more appropriate to -celestial coordinates. - -The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way -as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the -precision with which celestial coordinates are displayed can also be -adjusted in this way. However, the range of format specifiers that can -be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format -resulting from any particular Digits value, is different. - -The syntax of SkyFrame format specifiers is detailed under the -description of the Format(axis) attribute in -\appref{ss:attributedescriptions}. Briefly, however, it allows -celestial coordinates to be expressed either as angles or times and to -include one or more of the fields: - -\begin{quote} -\begin{itemize} -\item degrees or hours -\item arc-minutes or minutes -\item arc-seconds or seconds -\end{itemize} -\end{quote} - -with a specified number of decimal places for the final field. A range -of field separators is also available, as the following examples show: - -\begin{quote} -\begin{center} -\begin{tabular}{|l|l|} -\hline -\textbf{Format Specifier} & \textbf{Example Formatted Value}\\ -\hline \hline -{\tt{d}} & {\tt{219}}\\ -{\tt{d.3}} & {\tt{219.123}}\\ -{\tt{dm}} & {\tt{219:05}}\\ -{\tt{dm.2}} & {\tt{219:05.44}}\\ -{\tt{dms}} & {\tt{219:05:42}}\\ -{\tt{hms.1}} & {\tt{15:44:13.8}}\\ -{\tt{bdms.2}} & {\tt{219 05 42.81}}\\ -{\tt{lhms.3}} & {\tt{15h44m13.88s}}\\ -{\tt{+zlhms}} & {\tt{+06h10m44s}}\\ -{\tt{ms.1}} & {\tt{13145:42.8}}\\ -{\tt{lmst.3}} & {\tt{876m22.854s}}\\ -{\tt{s.2}} & {\tt{788742.81}}\\ -\hline -\end{tabular} -\end{center} -\end{quote} - -Note the following key points: - -\begin{itemize} -\item The required fields are specified using characters chosen from -either ``dms'' or ``hms'' according to whether the value is to be -formatted as an angle (in degrees) or a time (in hours). - -\item If no degrees or hours field is required, the distinction -between angle and time may be made by including ``t'' to request time. - -\item The number of decimal places (for the final field) is indicated -using ``\texttt{.}'' followed by an integer. An asterisk can be used in -place of an integer, in which case the number of decimal places is -chosen so that the total number of digits in the formatted value is equal -to the value of the Digits attribute. - -\item ``b'' causes fields to be separated by blanks, while ``l'' -causes them to be separated by the appropriate letters (the default -being a colon). - -\item ``z'' causes padding with leading zeros. - -\item ``+'' cause a plus sign to be prefixed to positive values -(negative values always have a minus sign). -\end{itemize} - -The formatting performed by a SkyFrame is also influenced by the -\htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each -SkyFrame axis. It determines whether the default format specifier for -an axis will present values as angles (\emph{e.g.}\ in degrees) if it -is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero. - -The default AsTime value depends on the celestial coordinate system -which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System} -attribute value. For example, equatorial longitude values (right -ascension) are normally expressed in hours, whereas ecliptic -longitudes are normally expressed in degrees, so their default AsTime -values will reflect this difference. - -The value of the AsTime attribute may be set explicitly to over-ride -these defaults if required, with the formatting precision being -determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the -Format(axis) attribute may be set explicitly to specify both the -format and precision required. Setting an explicit Format value always -over-rides the effects of both the Digits and AsTime attributes (unless -the Format value does not specify the required number of decimal places, -in which case Digits is used to determine the default number of decimal -places) - -\subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates} - -The process of converting formatted celestial coordinates, such as -might be produced by the \htmlref{astFormat}{astFormat} function -(\secref{ss:formattingskyaxisvalues}), into numerical (double) -coordinate values is performed by using \htmlref{astUnformat}{astUnformat} -(\secref{ss:unformattingaxisvalues}) and passing it a pointer to a -\htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats -accepted is appropriate to positions on the sky expressed as angles -and/or times, while the returned value is in radians. - -The following describes the forms of celestial coordinate which are -supported: - -\begin{itemize} -\item You may supply an optional sign, followed by between one and -three fields representing either degrees, arc-minutes, arc-seconds or -hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03''). - -\item Each field should consist of a sequence of one or more digits, -which may include leading zeros. At most one field may contain a -decimal point, in which case it is taken to be the final field -(\emph{e.g.}\ decimal degrees might be given as ``124.707'', while -degrees and decimal arc-minutes might be given as ``$-$13~33.8''). - -\item The first field given may take any value, allowing angles and -times outside the conventional ranges to be represented. However, -subsequent fields must have values of less than 60 (\emph{e.g.} -``720~45~31'' is valid, whereas ``11~45~61'' is not). - -\item Fields may be separated by white space or by ``:'' (colon), but -the choice of separator must be used consistently throughout the -value. Additional white space may be present around fields and -separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1''). - -\item The following field identification characters may be used as -separators to replace those above (or may be appended to the final -field), in order to identify the field to which they are appended: - -\begin{quote} -\begin{tabular}{lll} -d & -- & degrees \\ -h & -- & hours \\ -m & -- & minutes (of arc or time) \\ -s & -- & seconds (of arc or time) \\ -\texttt{'} & -- & arc-minutes \\ -\texttt{"} & -- & arc-seconds -\end{tabular} -\end{quote} - -Either lower or upper case may be used. Fields must be given in order -of decreasing significance -(\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s''). - -\item The presence of certain field identification characters -indicates whether the value is to be interpreted as an angle or a time -(with 24 hours corresponding to 360 degrees), as follows: - -\begin{quote} -\begin{tabular}{lll} -d & -- & angle \\ -\texttt{'} & -- & angle \\ -\texttt{"} & -- & angle \\ -h & -- & time -\end{tabular} -\end{quote} - -Incompatible angle/time identification characters may not be mixed -(\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid). The remaining -field identification characters and separators do not specify a -preference for an angle or a time and may be used with either. - -\item If no preference for an angle or a time is expressed anywhere -within the value, then it is interpreted as an angle if the Format -attribute string associated with the SkyFrame axis generates an angle -and as a time otherwise. This ensures that values produced by -astFormat (\secref{ss:formattingskyaxisvalues}) are correctly -interpreted by astUnformat. - -\item Fields may be omitted, in which case they default to zero. The -remaining fields may be identified by using appropriate field -identification characters (see above) and/or by adding extra colon -separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field -is not identified explicitly, it is assumed that adjacent fields have -been given, after taking account of any extra separator -characters. For example: - -\begin{quote} -\begin{tabular}{lll} -10d & -- & degrees \\ -10d12 & -- & degrees and arc-minutes \\ -11:14\texttt{"} & -- & arc-minutes and arc-seconds \\ -9h13s & -- & hours and seconds of time \\ -:45:33 & -- & minutes and seconds (of arc or time) \\ -:55: & -- & minutes (of arc or time) \\ -::13 & -- & seconds (of arc or time) \\ -$-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\ -07m14 & -- & minutes and seconds (of arc or time) \\ -$-$8:14\texttt{'} & -- & degrees and arc-minutes \\ -$-$h3:14 & -- & minutes and seconds of time \\ -h:2.1 & -- & seconds of time -\end{tabular} -\end{quote} - -\item If fields are omitted in such a way that the remaining ones -cannot be identified uniquely (e.g. ``01:02''), then the first field -(either given explicitly or implied by an extra leading colon -separator) is taken to be the most significant field that astFormat -would produce when formatting a value (using the Format attribute -associated with the SkyFrame axis). By default, this means that the -first field will normally be interpreted as degrees or hours. However, -if this does not result in consistent field identification, then the -last field (either given explicitly or implied by an extra trailing -colon separator) is taken to to be the least significant field that -astFormat would produce. - -\end{itemize} - -This final convention is intended to ensure that values formatted by -astFormat which contain less than three fields will be correctly -interpreted if read back using astUnformat, even if they do not -contain field identification characters. However, it also affects -other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set -to ``mst.1'' (producing two fields representing minutes and seconds of -time), then formatted input would be interpreted by astUnformat as -follows: - -\begin{quote} -\begin{tabular}{lll} -12 13 & -- & minutes and seconds \\ -12 & -- & minutes \\ -:13 & -- & seconds \\ -$-$18: & -- & minutes \\ -12.8 & -- & minutes \\ -1 2 3 & -- & hours, minutes and seconds \\ -& & \\ -4\texttt{'} & -- & arc-minutes \\ -60::\texttt{"} & -- & degrees \\ -$-$23:\texttt{"} & -- & arc-minutes \\ -$-$33h & -- & hours -\end{tabular} -\end{quote} - -(in the last four cases, explicit field identification has been given -which overrides the implicit identification). - -Alternatively, if the Format(axis) string were set to ``s.3'' -(producing only an arc-seconds field), then formatted input would be -interpreted by astUnformat as follows: - -\begin{quote} -\begin{tabular}{lll} -12.8 & -- & arc-seconds \\ -12 13 & -- & arc-minutes and arc-seconds \\ -:12 & -- & arc-seconds \\ -13: & -- & arc-minutes \\ -1 2 3 & -- & degrees, arc-minutes and arc-seconds -\end{tabular} -\end{quote} - -In general, if you are preparing formatted input data containing -celestial coordinates and wish to omit certain fields, then you are -advised to identify clearly those that you do provide by using the -appropriate field identification characters and/or extra colon -separators. This prevents you depending on the implicit field -identification described above which, in turn, depends on an -appropriate Format(axis) string having been set. - -When writing software, it is also a good idea to set the Format(axis) -string so that data input will be as simple as possible for the -user. Unless some special effect is desired, this normally means that -it should contain ``d'' or ``h'' to ensure that the first field -entered by the user will be interpreted as degrees or hours, unless -otherwise identified. This is the normal behaviour unless an explicit -Format(axis) value has been set to override the default. - -\subsection{Representing Offsets from a Specified Sky Position} -A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are -referred to an origin at any specified sky position. Such a coordinate -system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System} -attribute should be set to represent the celestial coordinate system in -which the origin is to be specified. Then the SkyRef attribute should be -set to hold the coordinates of the origin within the selected celestial -coordinate system. - -By default, ``north'' in the new offset coordinate system is parallel to -north in the original celestial coordinate system. However, the direction -of north in the offset system can be controlled by assigning a value to -the SkyRefP attribute. This attribute should be assigned the celestial -coordinates of a point which is on the zero longitude meridian and which -has non-zero latitude. - -By default, the position given by the SkyRef attribute is used as the -origin of the new longitude/latitude system, but an option exists to use -it as the north pole of the system instead. This option is controlled by -the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what -sort of offset coordinate system you want. Setting SkyRefIs to -``Origin'' (the default) produces an offset coordinate system which is -approximately Cartesian close to the specified position. Setting SkyRefIs -to -``Pole'' produces an offset coordinate system which is approximately Polar -close to the specified position. - -\cleardoublepage -\section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)} - -The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate -systems which describe a position within an electro-magnetic spectrum. -In this section we examine the additional properties and behaviour of a -SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}). - -\subsection{The SpecFrame Model} - -As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a -\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and -behaviour of these two ancestral classes. When used as a Mapping, a -SpecFrame implements a unit transformation, exactly like a basic Frame -(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its -behaviour is not of great importance. - -When used as a Frame, however, a SpecFrame represents a wide range of -different 1-dimensional coordinate system which can be used to describe -positions within a spectrum. The options available largely mirror those -described in the FITS-WCS paper III \emph{Representations of spectral -coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen). - -\subsection{Creating a SpecFrame} - -The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a -SpecFrame with default attributes is created as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstSpecFrame *specframe; - -... - -specframe = astSpecFrame( "" ); -\end{terminalv} -\normalsize - -Such a SpecFrame would represent the default coordinate system which is -heliocentric wavelength in metres (i.e. wavelength corrected to take into -account the Doppler shift caused by the velocity of the observer around the -sun). - -\subsection{Specifying a Particular Spectral Coordinate System} - -Selection of a particular coordinate system is performed simply by -setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System} -attribute. This setting is most conveniently done when the SpecFrame is -created. For example, a SpecFrame representing Energy would be created by: - -\small -\begin{terminalv} -specframe = astSpecFrame( "System=Energy" ); -\end{terminalv} -\normalsize - -Note that specifying ``System$=$Energy'' also changes the associated -Unit (from metres to Joules). This is because the default value -of the SpecFrame's Unit attribute depends on the System attribute setting. - -You may change the System value at any time, although this is not -usually needed. The values supported are set out in the attribute's -description in \appref{ss:attributedescriptions} and include a variety -of velocity systems, together with frequency, wavelength, energy, -wave-number, \emph{etc}. - -\subsection{Attributes which Qualify Spectral Coordinate Systems} - -Many spectral coordinate systems have some additional free parameters -which serve to identify a particular coordinate system from amongst a -broader class of related coordinate systems. For example, the -velocity systems are all parameterised by a rest frequency---the -frequency which defines zero velocity, and all coordinate systems -are qualified by a `standard of rest'' which indicates the rest frame to -which the values refer. - -In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame} -attributes, each of which has a default appropriate to -(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System} -attribute. Each of these \emph{qualifying attributes} may, however, be -assigned an explicit value so as to select a particular coordinate -system. Note, it is usually best to assign explicit -values whenever possible rather than relying on defaults. Attribute -should only be left at their default value if you ``don't care'' what -value is used. In certain circumstances (particularly, when aligning two -Frames), a default value for an attribute may be replaced by the value -from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by -assigning an explicit value to the attribute, rather than simply relying on -the default. - - -The main SpecFrame attributes which qualify the System attribute are: - -\begin{quote} -\begin{description} - -\item[\htmlref{Epoch}{Epoch}]\mbox{}\\ -This attribute is inherited from the Frame class. It gives the moment in -time when the coordinates are correct for the astronomical source -under study (usually the date of observation). It is needed in order to -calculate the Doppler shift produced by the velocity of the observer -relative to the centre of the earth, and of the earth relative to the sun. - -\item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\ -This specifies the rest frame in which the coordinates are correct. -Transforming between different standards of rest involves taking account -of the Doppler shift introduced by the relative motion of the two -standards of rest. - -\item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\ -Specifies the frequency which correspond to zero velocity. When setting a -value for this attribute, the value may be supplied as a wavelength -(including an indication of the units being used, ``nm'' ``Angstrom'', -\emph{etc.}), which will be automatically be converted to a frequency. - -\item[\htmlref{RefRA}{RefRA}]\mbox{}\\ -Specifies the RA (FK5 J2000) of the source. This is used when converting -between standards of rest. It specifies the direction along which the -component of the relative velocity of the two standards of rest is taken. - -\item[\htmlref{RefDec}{RefDec}]\mbox{}\\ -Specifies the Dec (FK5 J2000) of the source. Used in conjunction with -REFRA. - -\item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\ -This defines the ``source'' standard of rest. This is a rest frame which -is moving towards the position given by RefRA and RefDec, at a velocity -given by SourceVel. The velocity is stored internally as a heliocentric -velocity, but can be given in any of the other supported standards of rest. - -\end{description} -\end{quote} - -For further details of these attributes you should consult their -descriptions in \appref{ss:attributedescriptions} and for details of -the System settings for which they are relevant, see the description -of the System attribute (also in \appref{ss:attributedescriptions}). - -Note that it does no harm to assign values to qualifying attributes -which are not relevant to the main System value. Any such values are -stored, but are not used unless the System value is later set so that -they become relevant. - -\subsection{Using Default SpecFrame Attributes} - -The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend -on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this -means that there is usually little need to specify many of these -attributes explicitly unless you have some special requirement. This -can be illustrated by using \htmlref{astShow}{astShow} to examine a SpecFrame, as follows: - -\small -\begin{terminalv} -astShow( astSpecFrame( "System=Vopt, RestFreq=250 GHz" ) ); -\end{terminalv} -\normalsize - -The output from this might look like the following: - -\begin{terminalv} - Begin SpecFrame # Description of spectral coordinate system -# Title = "Optical velocity, rest frequency = 250 GHz" # Title -of coordinate system - Naxes = 1 # Number of coordinate axes -# Domain = "SPECTRUM" # Coordinate system domain -# Epoch = 2000 # Julian epoch of observation -# Lbl1 = "Optical velocity" # Label for axis 1 - System = "VOPT" # Coordinate system type -# Uni1 = "km/s" # Units for axis 1 - Ax1 = # Axis number 1 - Begin Axis # Coordinate axis - End Axis - IsA Frame # Coordinate system description -# SoR = "Heliocentric" # Standard of rest - RstFrq = 250000000000 # Rest frequency (Hz) - End SpecFrame -\end{terminalv} - -Note that the defaults (indicated by the ``\verb?#?'' comment -character at the start of the line) for attributes such as the \htmlref{Title}{Title}, -axis Labels and Unit specifiers are all set to values appropriate -for the particular velocity system that the SpecFrame represents. - -These choices would be appropriate for a System value of ``Vopt'', -but if a different System value were set, the defaults would be -correspondingly different. For example, by default frequency is measured in -units of GHz, not $km/s$, so setting ``System=freq'' -would change the appropriate line above from: - -\begin{terminalv} -# Uni1 = "km/s" # Units for axis 1 -\end{terminalv} - -to - -\begin{terminalv} -# Uni1 = "GHz" # Units for axis 1 -\end{terminalv} - -Of course, if you do not like any of these defaults, you may always -over-ride them by setting explicit attribute values yourself. For -instance, you may choose to have your frequency axis expressed in ``kHz'' -rather than ``GHz''. To do this simply set the attribute value as follows: - -\small -\begin{terminalv} -astSetC( specframe, "Unit", "kHz" ); -\end{terminalv} -\normalsize - -No error will be reported if you accidentally set an inappropriate Unit value -(say "J" - Joules)---after all, AST cannot tell what you are about to do, -and you \emph{may} be about to change the System value to ``Energy''. -However, an error \emph{will} be reported if you attempt to find a -conversion between two SpecFrames (for instance using -\htmlref{astConvert}{astConvert} -) if either SpecFrame has a Unit value which is inappropriate for its -System value. - -SpecFrame attributes, like all other attributes, all have default -value. However, be aware that for some attributes these default values -can never be more than ``a legal numerical value'' and have no -astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes -(which give the source position) both have a default value of zero. So -unless your source happens to be at that point (highly unlikely!) you will -need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute -has an arbitrary default value of 1.0E5 GHz. Some operations are not -affected by inappropriate values for these attributes (for instance, -converting from frequency to wavelength, changing axis units, \emph{etc}), -but some are. For instance, converting from frequency to velocity -requires a correct rest frequency, moving between different standards of -rest requires a correct source position. The moral is, always set explicit -values for as many attributes as possible. - -\subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes} -You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube -containing two spatial axes and a spectral axis. To do this you would -create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame} -(often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine -these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}. - -\small -\begin{terminalv} -AstSkyFrame *skyframe; -AstSpecFrame *specframe; -AstCmpFrame *cmpframe; -... -skyframe = astSkyFrame( "Epoch=J2002" ); -specframe = astSpecFrame( "System=Freq,StdOfRest=LSRK" ); -cmpframe = astCmpFrame( skyframe, specframe, "" ); -\end{terminalv} -\normalsize - -In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis -3 will be Frequency. If this is not the order you want, you can permute -the axes using -\htmlref{astPermAxes}{astPermAxes}. - -There is one potential problem with this approach if you are interested in -unusually high accuracy. Conversion between different standards of rest -involves taking account of the Doppler shift caused by the relative -motion of the two standards of rest. At some point this involves finding -the component of the relative velocity in the direction of interest. -For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} -attributes, even if the SpecFrame is embedded within a CmpFrame as above. -It would be more appropriate if this ``direction of interest'' was -specified by the values passed into the CmpFrame on the RA and DEC axes, -allowing each pixel within a data cube to have a slightly different -correction for Doppler shift. - -Unfortunately, the SpecFrame class cannot do this (since it is purely a -1-dimensional Frame), and so some small degree of error will be -introduced when converting between standards of rest, the size of the -error varying from pixel to pixel. It is hoped that at some point in the -future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which -allows for this spatial variation in Doppler shift. - -The maximum velocity error introduced by this problem is of the order of -$V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the -relative velocity of the two standards of rest. As an example, when -correcting from the observers rest frame (i.e. the topocentric rest -frame) to the kinematic local standard of rest the maximum value of $V$ -is about 20 $km/s$, so for 5 arc-minute field of view the maximum -velocity error introduced by the correction will be about 0.03 $km/s$. As -another example, the maximum error when correcting from the observers -rest frame to the local group is about 5 $km/s$ over a 1 degree field of -view. - -\subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra} -Dual sideband super-heterodyne receivers produce spectra in which each channel -contains contributions from two different frequencies, referred to as the -``upper sideband frequency'' and the ``lower sideband frequency''. In the -rest frame of the observer (topocentric), these are related to each other as -follows: - -\begin{quote} -\begin{small} -\begin{equation} -\label{eqn:dsb} - f_{lsb} = 2.f_{LO} - f_{usb} -\end{equation} -\end{small} -\end{quote} - -where $f_{LO}$ is a fixed frequency known as the ``local oscillator -frequency''. In other words, the local oscillator frequency is always -mid-way between any pair of corresponding upper and lower sideband -frequencies\footnote{Note, this simple relationship only applies if all -frequencies are topocentric.}. If you want to describe the spectral axis -of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the -SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot -describe both sidebands simultaneously. However, there is a sub-class of -SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty. - -A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the -DSBSpecFrame is currently being used to describe the upper or lower -sideband spectral axis. The value of this attribute can be changed at any -time. If you use the -\htmlref{astConvert}{astConvert} -function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for -the two SideBand attributes will be taken into account. Thus, if you take -a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use -astConvert -to find a Mapping from the original to the modified copy, the resulting -Mapping will be of the form of equation \ref{eqn:dsb} (if the -DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric''). - -In general, when finding a Mapping between two arbitrary DSBSpecFrames, -the total Mapping is made of of three parts in series: - -\begin{enumerate} -\item A Mapping which converts the first DSBSpecFrame into its upper -sideband representation. If the DSBSpecFrame already represents its upper -sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}. -\item A Mapping which converts from the first to the second DSBSpecFrame, -treating them as if they were both basic SpecFrames. This takes account of -any difference in units, standard of rest, system, \emph{etc} between the -two DSBSpecFrames. -\item A Mapping which converts the second DSBSpecFrame from its upper -sideband representation to its current sideband. If the DSBSpecFrame -currently represents its upper sideband, this Mapping will be a UnitMap. -\end{enumerate} - -If an attempt is made to find the Mapping between a DSBSpecFrame and a -basic SpecFrame, then the DSBSpecFrame will be treated like a basic -SpecFrame. In other words, the returned Mapping will not be affected by -the setting of the SideBand attribute (or any of the other attributes -specific to the DSBSpecFrame class). - -In practice, the local oscillator frequency for a dual sideband -instrument may not be easily available to an observer. Instead, it is -common practice to specify the spectral position of some central feature -in the observation (commonly the centre of the instrument passband), -together with an ``intermediate frequency''. Together, these two values -allow the local oscillator frequency to be determined. The intermediate -frequency is the difference between the topocentric frequency at the -central spectral position and the topocentric frequency of the local -oscillator. So: - -\begin{quote} -\begin{small} -\begin{equation} -\label{eqn:dsb2} - f_{LO} = f_{central} + f_{if} -\end{equation} -\end{small} -\end{quote} - -The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central -spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the -intermediate frequency ($f_{if}$). The DSBCentre value is given and returned -in the spectral system described by the DSBSpecFrame (thus you do not need to -calculate the corresponding topocentric frequency yourself - this will be -done automatically by the DSBSpecFrame when you assign a new value to the -DSBCentre attribute). The value assigned to the IF attribute should -always be a topocentric frequency in units of Hz, however a negative -value may be given to indicate that the DSBCentre value is in the upper -sideband (that is, if $IF < 0$ then $f_{central} > f_{LO}$). A positive -value for IF indicates that the DSBCentre value is in the lower sideband -(that is, if $IF > 0$ then $f_{central} < f_{LO}$). - - -\cleardoublepage -\section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)} - -The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in -time. In this section we examine the additional properties and behaviour of a -TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}). - -\subsection{The TimeFrame Model} - -As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a -\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and -behaviour of these two ancestral classes. When used as a Mapping, a -TimeFrame implements a unit transformation, exactly like a basic Frame -(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its -behaviour is not of great importance. - -When used as a Frame, however, a TimeFrame represents a wide range of -different 1-dimensional coordinate system which can be used to describe -moments in time. Absolute times and relative (i.e. elapsed) times are -supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales -(attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can -be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch}, -\emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to -allow them to be used with any unit of time (attribute Unit). The TimeFrame -class also allows times to formatted as either a simple floating point value -or as a Gregorian date and time of day (attribute Format). - -\subsection{Creating a TimeFrame} - -The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a -TimeFrame with default attributes is created as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstTimeFrame *timeframe; - -... - -timeframe = astTimeFrame( "" ); -\end{terminalv} -\normalsize - -Such a TimeFrame would represent the default coordinate system which is -Modified Julian Date (with the usual units of days) in the International -Atomic Time (TAI) time scale. - -\subsection{Specifying a Particular Time System} -By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent -Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the -time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}). - -Selection of a particular coordinate system is performed simply by -setting a value for the TimeFrame's (character string) System -attribute. This setting is most conveniently done when the TimeFrame is -created. For example, a TimeFrame representing Julian Epoch would be created -by: - -\small -\begin{terminalv} -timeframe = astTimeFrame( "System=JEPOCH" ); -\end{terminalv} -\normalsize - -Note that specifying ``System$=$JEPOCH'' also changes the associated -default Unit (from days to years). This is because the default value -of the TimeFrame's Unit attribute depends on the System attribute setting. - -You may change the System value at any time, although this is not -usually needed. The values supported are set out in the attribute's -description in \appref{ss:attributedescriptions}. - -\subsection{Attributes which Qualify Time Coordinate Systems} - -Time coordinate systems require some additional free parameters to identify -a particular coordinate system from amongst a broader class of related -coordinate systems. For example, all TimeFrames are qualified by the time -scale (that is, the physical process used to define the flow of time), -and some require the position of the observer's clock. - -In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame} -attributes, each of which has a default appropriate to (\emph{i.e.}\ defined -by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying -attributes} may, however, be assigned an explicit value so as to select a -particular coordinate system. Note, it is usually best to assign explicit -values whenever possible rather than relying on defaults. Attribute -should only be left at their default value if you ``don't care'' what -value is used. In certain circumstances (particularly, when aligning two -Frames), a default value for an attribute may be replaced by the value -from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by -assigning an explicit value to the attribute, rather than simply relying on -the default. - -The main TimeFrame attributes which qualify the System attribute are: - -\begin{quote} -\begin{description} - -\item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\ -This specifies the time scale. - -\item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\ -This specifies the offset from Local Time to UTC in hours (time zones -east of Greenwich have positive values). Note, AST uses the value as -supplied without making any correction for daylight saving. - -\item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\ -This specifies the zero point from which time values are measured, within -the system specified by the System attribute. Thus, a value of zero (the -default) indicates that time values represent absolute times. Non-zero -values may be used to indicate that the TimeFrame represents elapsed time -since the specified origin. - -\end{description} -\end{quote} - -For further details of these attributes you should consult their -descriptions in \appref{ss:attributedescriptions} and for details of -the System settings for which they are relevant, see the description -of the System attribute (also in \appref{ss:attributedescriptions}). - -Note that it does no harm to assign values to qualifying attributes -which are not relevant to the main System or TimeScale value. Any such -values are stored, but are not used unless the System and/or TimeScale -value is later set so that they become relevant. - -\cleardoublepage -\section{\label{ss:cmpframes}Compound Frames (CmpFrames)} - -We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The -Frames we have considered so far have been atomic, in the sense that -they represent pre-defined elementary physical domains. A CmpFrame, -however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for -containing other Frames and its purpose is to allow those Frames -to work together in various combinations while appearing as a single -\htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is -determined by the other Frames it contains (its ``component'' Frames). - -As with compound Mappings, compound Frames can be nested within each -other, forming arbitrarily complex Frames. - -\subsection{Creating a CmpFrame} -A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a -``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes -represents position within a spectrum, and the other two axes represent -position on the sky (or some other spatial domain such as the focal plane -of a telescope). As an example, we create such a CmpFrame in which axes -1 and 2 represent Right Ascension and Declination (ICRS), and axis 3 -represents wavelength (these are the default coordinate Systems -represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively): - -\small -\begin{terminalv} -AstSkyFrame *skyframe; -AstSpecFrame *specframe; -AstCmpFrame *cmpframe; -... -skyframe = astSkyFrame( "" ); -specframe = astSpecFrame( "" ); -cmpframe = astCmpFrame( skyframe, specframe, "" ); -\end{terminalv} -\normalsize - -If it was desired to make RA and Dec correspond to axes 1 and 3, with -axis 2 being the spectral axis, then the axes of the CmpFrame created -above would need to be permuted as follows: - -\small -\begin{terminalv} -int perm[ 3 ]; -... - -perm[ 0 ] = 0; -perm[ 1 ] = 2; -perm[ 2 ] = 1; -astPermAxes( cmpframe, perm ); -\end{terminalv} -\normalsize - -\subsection{The Attributes of a CmpFrame} - -A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame. -The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by -concatenating the Domains of the two component Frames, separated by a -minus sign (``-'').\footnote{If both component Frames have blank Domains, -then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed) -value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to -change the System value of a CmpFrame is ignored.} A CmpFrame has no -further attributes over and above those common to all Frames. However, -attributes of the two component Frames can be accessed as if they were -attributes of the CmpFrame, as described below. - -Frame attributes which are specific to individual axes (such as Label(2), -Format(1), \emph{etc}) simply mirror the corresponding axes of the -relevant component Frame. That is, if the ``Label(2)'' attribute of a -CmpFrame is accessed, the CmpFrame will forward the access request to the -component Frame which contains axis 2. Thus, default values for axis -attributes will be the same as those provided by the component Frames. - -An axis index can optionally be appended to the name of Frames attributes -which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title}, -\emph{etc}). If this is done, the access request is forwarded to the -component Frame containing the indicated axis. For instance, if a -CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes -have not been permuted, then getting the value of attribute ``System'' will -return ``Compound'' as mentioned above (that is, the System value of the -CmpFrame as a whole), whereas getting the value of attribute -``System(1)'' will return ``Spectral''(that is, the System value of the -component Frame containing axis 1 --- the SpecFrame). - -This technique is not limited to attributes common to all Frames. For -instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is -not held by other classes of Frames. To set a value for the Equinox -attribute of the SkyFrame contained within the above CmpFrame, assign the -value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame -defines both axes 2 and 3 of the CmpFrame, we could equivalently have set -a value for ``Equinox(3)'' since this would also result in the attribute -access being forwarded to the SkyFrame. - -Finally, if an attribute is not qualified by a axis index, attempts will -be made to access it using each of the CmpFrame axes in turn. Using the -above example of the spectral cube, if an attempt was made to get the -value of attribute ``Equinox'' (with no axis index), each axis in turn -would be used. Since axis 1 is contained within a SpecFrame, the first -attempt would fail since the SpecFrame class does not have an Equinox -attribute. However, the second attempt would succeed because axis 2 is -contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus -the returned attribute value would be that obtained from the SkyFrame -containing axis 2. When getting or testing an attribute value, the -returned value is determined by the \emph{first} axis which recognises -the attribute. When setting an attribute value, \emph{all} axes -which recognises the attribute have the attribute value set to the given -value. Likewise, when clearing an attribute value, all axes -which recognises the attribute have the attribute value cleared. - -\cleardoublepage -\section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions} - -In this section, we start to look at techniques for converting between -different coordinate systems. At this stage, the tools we have available -are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}), -SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and -various Mappings (\secref{ss:mappings}). These are sufficient to allow us to -begin examining the problem, but more sophisticated approaches will also emerge -later (\secref{ss:framesetconverting}). - -\subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems} - -We begin by examining how to convert between two celestial coordinate -systems represented by SkyFrames, as this is both an illuminating and -practical example. Consider the problem of converting celestial -coordinates between: - -\begin{enumerate} -\item The old FK4 system, with no E terms, a Besselian epoch of -1958.0 and a Besselian equinox of 1960.0. - -\item An ecliptic coordinate system based on the mean equinox and -ecliptic of Julian epoch 2010.5. -\end{enumerate} - -This example is arbitrary but not completely unrealistic. Unless you -already have expertise with such conversions, you are unlikely to find -it straightforward. - -Using AST, we begin by creating two SkyFrames to represent these -coordinate systems, as follows: - -\small -\begin{terminalv} -#include "ast.h" -AstSkyFrame *skyframe1, *skyframe2; - -... - -skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); -skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); -\end{terminalv} -\normalsize - -Note how specifying the coordinate systems consists simply of -initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately. The next -step is to find a way of converting between these SkyFrames. This is -done using \htmlref{astConvert}{astConvert}, as follows: - -\small -\begin{terminalv} -AstFrameSet *cvt; - -... - -cvt = astConvert( skyframe1, skyframe2, "" ); -if ( cvt == AST__NULL ) { - <conversion is not possible> -} else { - <conversion is possible> -} -\end{terminalv} -\normalsize - -The third argument of astConvert is not used here and should be an -empty string. - -astConvert will return a null result, AST\_\_NULL (as defined in the -``ast.h'' header file), if conversion is not possible. In this -example, conversion is possible, so it will return a pointer to a new -\htmlref{Object}{Object} that describes the conversion. - -The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed -FrameSets yet (\secref{ss:framesets}), but for the present purposes we -can consider them simply as Objects that can behave both as Mappings -and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we -are mainly interested here, because the Mapping it implements is the -one we require---\emph{i.e.}\ it converts between the two celestial -coordinate systems (\secref{ss:framesetsfromconvert}). - -For example, if ``alpha1'' and ``delta1'' are two arrays containing -the longitude and latitude, in radians, of N points on the sky in the -original coordinate system (corresponding to ``skyframe1''), then they -could be converted into the new coordinate system (represented by -``skyframe2'') as follows: - -\small -\begin{terminalv} -#define N 10 -double alpha1[ N ], delta1[ N ]; -double alpha2[ N ], delta2[ N ]; - -... - -astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); -\end{terminalv} -\normalsize - -The new coordinates are returned \emph{via} the ``alpha2'' and -``delta2'' arrays. To transform coordinates in the opposite -direction, we simply invert the 5th (boolean int) argument to -\htmlref{astTran2}{astTran2}, as follows: - -\small -\begin{terminalv} -astTran2( cvt, N, alpha2, delta2, 0, alpha1, delta1 ); -\end{terminalv} -\normalsize - -The FrameSet returned by astConvert also contains information about -the SkyFrames used in the conversion -(\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet -may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the -``destination'' Frame used in the conversion (\emph{i.e.}\ like -``skyframe2''). We could therefore use the ``cvt'' FrameSet to -calculate the distance between two points (with coordinates in -radians) in the destination coordinate system, using \htmlref{astDistance}{astDistance}: - -\small -\begin{terminalv} -double distance, point1[ 2 ], point2[ 2 ]; - -... - -distance = astDistance( cvt, point1, point2 ); -\end{terminalv} -\normalsize - -and the result would be the same as if the ``skyframe2'' SkyFrame had -been used. - -Another way to see how the FrameSet produced by astConvert retains -information about the coordinate systems involved is to set its \htmlref{Report}{Report} -attribute (inherited from the Mapping class) so that it displays the -coordinates before and after conversion (\secref{ss:transforming}): - -\small -\begin{terminalv} -astSet( cvt, "Report=1" ); -astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 ); -\end{terminalv} -\normalsize - -The output from this might look like the following: - -\begin{terminalv} -(2:06:03.0, 34:22:39) --> (42.1087, 20.2717) -(2:08:20.6, 35:31:24) --> (43.0197, 21.1705) -(2:10:38.1, 36:40:09) --> (43.9295, 22.0716) -(2:12:55.6, 37:48:55) --> (44.8382, 22.9753) -(2:15:13.1, 38:57:40) --> (45.7459, 23.8814) -(2:17:30.6, 40:06:25) --> (46.6528, 24.7901) -(2:19:48.1, 41:15:11) --> (47.5589, 25.7013) -(2:22:05.6, 42:23:56) --> (48.4644, 26.6149) -(2:24:23.1, 43:32:41) --> (49.3695, 27.5311) -(2:26:40.6, 44:41:27) --> (50.2742, 28.4499) -\end{terminalv} - -Here, we see that the input FK4 equatorial coordinate values (given in -radians) have been formatted automatically in sexagesimal notation -using the conventional hours for right ascension and degrees for -declination. Conversely, the output ecliptic coordinates are shown in -decimal degrees, as is conventional for ecliptic coordinates. Both are -displayed using the default precision of 7 digits.\footnote{The -leading digit is zero and is therefore not seen in this particular -example.} - -In fact, the ``cvt'' FrameSet has access to all the information in the -original SkyFrames which were passed to astConvert. If you had set a -new Digits attribute value for either of these, the formatting above -would reflect the different precision you requested by displaying a -greater or smaller number of digits. - - -\subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems} -The principles described in the previous section for converting between -celestial coordinate systems also apply to the task of converting between -spectral coordinate systems. As an example, let's look at how we might -convert between frequency measured in $GHz$ as measured in the rest frame -of the telescope, and radio velocity measured in $km/s$ measured with -respect the kinematic Local Standard of Rest. - -First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to -describe the required radio velocity system (this is slightly more -convenient, given the relatively large number of attributes, than -specifying the attribute values in a single string such as would be -passed to the SpecFrame constructor). We then take a copy of this -SpecFrame, and change the attribute values so that the copy describes the -original frequency system (modifying a copy, rather than creating a new -SpecFrame from scratch, avoids the need to specify the epoch, reference -position, \emph{etc} a second time since they are all inherited by the copy): - -\small -\begin{terminalv} -#include "ast.h" -AstSpecFrame *specframe1, *specframe2; - -... - -specframe1 = astSpecFrame( "" ); -astSet( specframe1, "System=vradio" ); -astSet( specframe1, "Unit=km/s" ); -astSet( specframe1, "Epoch=1996-Oct-2 12:13:56.985" ); -astSet( specframe1, "ObsLon=W155:28:18" ); -astSet( specframe1, "ObsLat=N19:49:34" ); -astSet( specframe1, "RefRA=18:14:50.6" ); -astSet( specframe1, "RefDec=-4:40:49" ); -astSet( specframe1, "RestFreq=230.538 GHz" ); -astSet( specframe1, "StdOfRest=LSRK" ); - -specframe2 = astCopy( specframe1 ); -astSet( specframe1, "System=freq" ); -astSet( specframe1, "Unit=GHz" ); -astSet( specframe1, "StdOfRest=Topocentric" ); - -\end{terminalv} -\normalsize - -Note, the fact that a SpecFrame has only a single axis means that we were -able to refer to the Unit attribute without an axis index. The other -attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical -position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source -on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the -standard of rest (\htmlref{StdOfRest}{StdOfRest}). - -The next step is to find a way of converting between these SpecFrames. We -use exactly the same code that we did in the previous section where we were -converting between celestial coordinate systems: - -\small -\begin{terminalv} -AstFrameSet *cvt; - -... - -cvt = astConvert( specframe1, specframe2, "" ); -if ( cvt == AST__NULL ) { - <conversion is not possible> -} else { - <conversion is possible> -} -\end{terminalv} -\normalsize - -A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible, -which should always be the case for our example), and we can use the -FrameSet to convert between the two spectral coordinate systems. We use -\htmlref{astTran1}{astTran1} in place of \htmlref{astTran2}{astTran2} -since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two). - -For example, if ``frq'' is an array containing the observed frequency, in -GHz, of N spectral channels (describe by ``specframe1''), then they -could be converted into the new coordinate system (represented by -``specframe2'') as follows: - -\small -\begin{terminalv} -#define N 10 -double frq[ N ]; -double vel[ N ]; - -... - -astTran1( cvt, N, frq, 1, vel ); -\end{terminalv} -\normalsize - -The radio velocity values are returned in the ``vel'' array. - - -\subsection{Converting between Time Coordinate Systems} -All the principles outlined in the previous section about aligning -spectral cocordinate systems (SpecFrames) can be applied directly to the -problem of aligning time coordinate systems (TimeFrames). - -\subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations} - -We can illustrate an important point if we swap the axis order of -either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes}) -before identifying the conversion. Let's assume we use \htmlref{astPermAxes}{astPermAxes} -(\secref{ss:permutingaxes}) to do this to the second SkyFrame, before -applying \htmlref{astConvert}{astConvert}, as follows: - -\small -\begin{terminalv} -int perm[ 2 ] = { 2, 1 }; - -... - -astPermAxes( skyframe2, perm ); -cvt = astConvert( skyframe1, skyframe2, "" ); -\end{terminalv} -\normalsize - -Now, the destination SkyFrame system no longer represents the -coordinate system: - -\begin{quote} -(ecliptic~longitude, ecliptic~latitude) -\end{quote} - -but instead represents the transposed system: - -\begin{quote} -(ecliptic~latitude, ecliptic~longitude) -\end{quote} - -As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by astConvert to -apply a coordinate transformation, we obtain something like the -following: - -\begin{terminalv} -(2:06:03.0, 34:22:39) --> (20.2717, 42.1087) -(2:08:20.6, 35:31:24) --> (21.1705, 43.0197) -(2:10:38.1, 36:40:09) --> (22.0716, 43.9295) -(2:12:55.6, 37:48:55) --> (22.9753, 44.8382) -(2:15:13.1, 38:57:40) --> (23.8814, 45.7459) -(2:17:30.6, 40:06:25) --> (24.7901, 46.6528) -(2:19:48.1, 41:15:11) --> (25.7013, 47.5589) -(2:22:05.6, 42:23:56) --> (26.6149, 48.4644) -(2:24:23.1, 43:32:41) --> (27.5311, 49.3695) -(2:26:40.6, 44:41:27) --> (28.4499, 50.2742) -\end{terminalv} - -When compared to the original (\secref{ss:convertingskyframes}), the -output coordinate order has been swapped to compensate for the -different destination SkyFrame axis order. - -In all, there are four possible axis combinations, corresponding to two -possible axis orders for each of the source and destination SkyFrames, -and astConvert will convert correctly between any of these. -The point to note is that a SkyFrame contains knowledge about how to -convert to and from other SkyFrames. Since its two axes (longitude and -latitude) are distinguishable, the conversion is able to take account -of the axis order. - -If you need to identify the axes of a SkyFrame explicitly, taking into -account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be -used. These are read-only attributes which give the indices of the -latitude and longitude axes respectively. - -\subsection{\label{ss:convertingframes}Converting Between Frames} - -Having seen how clever SkyFrames are (\secref{ss:convertingskyframes} -and \secref{ss:convertingpermutedaxes}), we will next examine how dumb -a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two -2-dimensional Frames and use \htmlref{astConvert}{astConvert} to derive a conversion between -them, as follows: - -\small -\begin{terminalv} -AstFrame *frame1, *frame2; - -... - -frame1 = astFrame( 2, "" ); -frame2 = astFrame( 2, "" ); -cvt = astConvert( frame1, frame2, "" ); -\end{terminalv} -\normalsize - -then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs -will be as follows: - -\begin{terminalv} -(1, 2) --> (1, 2) -(2, 4) --> (2, 4) -(3, 6) --> (3, 6) -(4, 8) --> (4, 8) -(5, 10) --> (5, 10) -\end{terminalv} - -This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap} -(\secref{ss:unitmapexample}). Even if we permute the axis order of our -Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will -fare no better. The conversion between our two basic Frames will -always be an identity transformation. - -The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start -life the same and have axes that are indistinguishable. Therefore, -permuting their axes doesn't make them look any different---they still -represent the same coordinate system. -%Actually, this behaviour isn't as dumb as it seems and can actually be -%very useful, as the following example illustrates. -% -%\subsection{Distinguishable and Indistinguishable Axes} -% -%c+ -%Imagine you have two Frames which represent the pixel coordinates of -%two 2-dimensional images. Let's call their axes ``X'' and ``Y''. -%Suppose you now transpose the second image and swap its Frame axes -%(with \htmlref{astPermAxes}{astPermAxes}) to take account of this. -%c- -%f+ -%Imagine you have two Frames which represent the pixel coordinates of -%two 2-dimensional images. Let's call their axes ``X'' and ``Y''. -%Suppose you now transpose the second image and swap its Frame axes -%(with astPermAxes) to take account of this. -%f- -% -%Next, consider what happens if you want to subtract one image from the -%other. If you have a ``subtract'' program that is intelligent and -%tries to align the two images for you, one of two things could happen: -% -%\begin{enumerate} -%c+ -%\item If the axes are distinguishable, when your program invokes -%astConvert it will derive a transformation between the two images -%which swaps the X and Y coordinates (corresponding to the transposition -%you applied to the second image). However, in aligning X-with-X and -%Y-with-Y, this will completely undo the effects of your transposition! -%c- -%f+ -%\item If the axes are distinguishable, when your program invokes -%AST\_CONVERT it will derive a transformation between the two images -%which swaps the X and Y coordinates (corresponding to the transposition -%you applied to the second image). However, in aligning X-with-X and -%Y-with-Y, this will completely undo the effects of your transposition! -%f- -% -%\item If the axes are indistinguishable, the transformation between -%the two images will always be an identity -%(\secref{ss:convertingframes}). Therefore, your program will align -%X-with-Y and Y-with-X, so that you see the effects of your earlier -%transposition of the second image. -%\end{enumerate} -% -%Clearly, if we are considering pixel coordinates, the latter behaviour -%is preferable, since there would be no point in implementing an image -%transposition program if we could never see the effects of it. This -%indicates that a basic Frame, with is indistinguishable axes, is the -%correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where -%this behaviour is necessary. -% -%Conversely, the former behaviour would be more useful if the axes we -%were considering were, say, wavelength (in nm) and slit position (in -%mm). In this case, we would expect our ``subtract'' program to -%subtract data at corresponding wavelengths and slit positions, not -%just at corresponding pixels. This case requires distinguishable axes, -%so that corresponding axes in the two images can be matched up, just -%as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}). -% -%Of course, there may also be intermediate cases, where some axes are -%distinguishable and others aren't. - -\subsection{\label{ss:alignmentsystem}The Choice of Alignment System} - -In practice, when AST is asked to find a conversion between two Frames -describing two different coordinate systems on a given physical domain, -it uses an intermediate ``alignment'' system. Thus, when finding a -conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from -system A to some alignment system, system C, and then finds the Mapping -from this system C to the required system B. It finally concatenates -these two Mappings to get the Mapping from system A to system B. - -One advantage of this is that it cuts down the number of conversion -algorithms required. If there are $N$ different Systems which may be used -to describe positions within the \htmlref{Domain}{Domain}, then this approach requires -about $2*N$ conversion algorithms to be written. The alternative approach -of going directly from system A to system B would require about $N*N$ -conversion algorithms. - -In addition, the use of an intermediate alignment system highlights the -nature of the conversion process. What do we mean by saying that a -Mapping ``converts a position in one coordinate system into the -corresponding position in another''? In practice, it means that the input -and output coordinates correspond to the same coordinates \emph{in some -third coordinate system}. The choice of this third coordinate system, the -``alignment'' system, can completely alter the nature of the Mapping. The -\htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to -specify the alignment system. - -As an example, consider the case of aligning two spectra calibrated in -radio velocity, but each with a different rest frequency (each spectrum -will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a -given velocity will correspond to different frequencies in the two -spectra. So when we come to ``align'' these two spectra (that is, find a -Mapping which converts positions in one SpecFrame to the corresponding -positions in the other), we have the choice of aligning the frequencies -or aligning the velocities. Different Mappings will be required to -describe these two forms of alignment. If we set AlignSystem to ``Freq'' -then the returned Mapping will align the frequencies described by the two -SpecFrames. On the other hand, if we set AlignSystem to ``Vradio'' -then the returned Mapping will align the velocities. - -Some choices of alignment system are redundant. For instance, in the -above example, changing the alignment system from frequency to wavelength -has no effect on the returned Mapping: if two spectra are aligned in -frequency they will also be aligned in wavelength (assuming the speed of -light doesn't change). - -The default value for AlignSystem depends on the class of Frame. For a -SpecFrame, the default is wavelength (or equivalently, frequency) -since this is the system in which observations are usually made. The -SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which -allows the standard of rest of the alignment system to be specified. -Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale} -which allows the time scale of the alignment system to be specified. -Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since -this is a close approximation to an inertial frame of rest. - -\cleardoublepage -\section{\label{ss:framesets}Coordinate System Networks (FrameSets)} - -We saw in \secref{ss:introducingconversion} how \htmlref{astConvert}{astConvert} could be -used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems -represented by Frames. There is a limitation to this, however, in that -it can only be applied to coordinate systems that are inter-related by -suitable conventions. In the case of celestial coordinates, the -relevant conventions are standards set out by the International -Astronomical Union, and others, that define what these coordinate -systems mean. In practice, however, the relationships between many -other coordinate systems are also of practical importance. - -Consider, for example, the focal plane of a telescope upon which an -image of the sky is falling. We could measure positions in this focal -plane in millimetres or, if there were a detector system such as a CCD -present, we could count pixels. We could also use celestial -coordinates of many different kinds. All of these systems are -equivalent in their effectiveness at specifying positions in the focal -plane, but some are more convenient than others for particular -purposes. - -Although we could, in principle, convert between all of these focal -plane coordinate systems, there is no pre-defined convention for doing -so. This is because the conversions required depend on where the -telescope is pointing and how the CCD is mounted in the focal -plane. Clearly, knowledge about this cannot be built into the AST -library and must be supplied in some other way. Note that this is -exactly the same problem as we met in \secref{ss:framedomains} when -discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that -apply to different physical domains require that extra information be -supplied before we can convert between them. - -What we need, therefore, is a general way to describe how coordinate -systems are inter-related, so that when there is no convention already -in place, we can define our own. We can then look forward to -converting, say, from pixels into galactic coordinates and {\emph{vice -versa.} In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability. - -\subsection{The FrameSet Model} - -Consider a coordinate system (call it number 1) which is represented -by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to -the coordinates in system 1 yields coordinates in another system, -number 2. The Mapping therefore inter-relates coordinate systems 1 and -2. - -Now consider a second Mapping which inter-relates system 1 and a -further coordinate system, number 3. If we wanted to convert -coordinates between systems 2 and 3, we could do so by: - -\begin{enumerate} -\item Applying our first Mapping in reverse, so as to convert between -systems 2 and 1. - -\item Applying the second Mapping, as given, to convert between -systems 1 and 3. -\end{enumerate} - -We are not limited to three coordinate systems, of course. In fact, we -could continue to introduce any number of further coordinate systems, -so long as we have a suitable Mapping for each one which relates it to -one of the Frames already present. Continuing in this way, we can -build up a network in which Frames are inter-related by Mappings in -such a way that there is always a way of converting between any pair -of coordinate systems. - -The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas. It -is a network composed of Frames and associated Mappings, in which -there is always exactly one path, \emph{via} Mappings, between any -pair of Frames. Since we assemble FrameSets ourselves, they can be -used to represent any coordinate systems we choose and to set up the -particular relationships between them that we want. - -\subsection{\label{ss:creatingaframeset}Creating a FrameSet} - -Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to -put into it, so let's create a simple one: - -\small -\begin{terminalv} -#include "ast.h" -AstFrame *frame1; - -... - -frame1 = astFrame( 2, "Domain=A" ); -\end{terminalv} -\normalsize - -We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to -A so that it will be distinct from the others we will be using. We can -now create a new FrameSet containing just this Frame, as follows: - -\small -\begin{terminalv} -AstFrameSet *frameset; - -... - -frameset = astFrameSet( frame1, "" ); -\end{terminalv} -\normalsize - -So far, however, this Frame isn't related to any others. - -\subsection{\label{ss:addingframes}Adding New Frames to a FrameSet} - -We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above -(\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame} -and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that -are already present (there is only one present so far). To keep the -example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates -by 10. The required Objects are created as follows: - -\small -\begin{terminalv} -AstFrame *frame2; -AstMapping *mapping12; - -... - -frame2 = astFrame( 2, "Domain=B" ); -mapping12 = astZoomMap( 2, 10.0, "" ); -\end{terminalv} -\normalsize - -To add the new Frame into our FrameSet, we use the \htmlref{astAddFrame}{astAddFrame} -function: - -\small -\begin{terminalv} -astAddFrame( frameset, 1, mapping12, frame2 ); -\end{terminalv} -\normalsize - -Whenever a Frame is added to a FrameSet, it is assigned an integer -index. This index starts with 1 for the initial Frame used to create -the FrameSet (\secref{ss:creatingaframeset}) and increments by one -every time a new Frame is added. This index is the primary way of -identifying the Frames within a FrameSet. - -When a Frame is added, we also have to specify which of the existing -ones the new Frame is related to. Here, we chose number 1, the only -one present so far, and the new one we added became number 2. - -Note that a FrameSet does not make copies of the Frames and Mappings -that you insert into it. Instead, it holds pointers to them. This -means that if you retain the original pointers to these Objects and -alter them, you will indirectly be altering the FrameSet's -contents. You can, of course, always use \htmlref{astCopy}{astCopy} -(\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if -you need to ensure its independence. - -We could also add a third Frame into our FrameSet, this time defining -a coordinate system which is reached by multiplying the original -coordinates (of ``frame1'') by 5: - -\small -\begin{terminalv} -astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) ); -\end{terminalv} -\normalsize - -Here, we have avoided storing unnecessary pointer values by using -function invocations directly as arguments for astAddFrame. This -assumes that we are using \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} (\secref{ss:contexts}) to -ensure that Objects are correctly deleted when no longer required. - - Our example FrameSet now contains three Frames and two Mappings with - the arrangement shown in Figure~\ref{fig:fsexample}. - \begin{figure} - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/fsexample} - \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to - Frame~1 by multiplying its coordinates by factors of 10 and 5 - respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its - \htmlref{Current}{Current} attribute has the value 3. The transformation performed when - the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to - its current Frame) is shown in bold.} - \label{fig:fsexample} - \end{center} - \end{figure} - The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute. - -\subsection{\label{ss:baseandcurrent}The Base and Current Frames} - -At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its -\emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame -(Figure~\ref{fig:fsexample}). These Frames are identified by two -integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices -of the nominated Frames within the FrameSet. - -The existence of the base and current Frames reflects an important -application of FrameSets, which is to attach coordinate systems to -entities such as data arrays, data files, plotting surfaces (for -graphics), \emph{etc.} In this context, the base Frame represents the -``native'' coordinate system of the attached entity---for example, the -pixel coordinates of an image or the intrinsic coordinates of a -plotting surface. The other Frames within the FrameSet represent -alternative coordinate systems which may also be used to refer to -positions within that entity. The current Frame represents the -particular coordinate system which is currently selected for use. For -instance, if an image were being displayed, you would aim to label it -with coordinates corresponding to the current Frame. In order to see a -different coordinate system, a software user would arrange for a -different Frame to be made current. - -The choice of base and current Frames may be changed at any time, -simply by assigning new values to the FrameSet's Base and Current -attributes. For example, to make the Frame with index 3 become the -current Frame, you could use: - -\small -\begin{terminalv} -astSetI( frameset, "Current", 3 ); -\end{terminalv} -\normalsize - -You can nominate the same Frame to be both the base and current Frame -if you wish. -\label{ss:baseandcurrentdefault} - -By default (\emph{i.e.}\ if the Base or Current attribute is un-set), -the first Frame added to a FrameSet becomes its base Frame and the -last one added becomes its current Frame.\footnote{Although this is -reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a -new Frame is added to a FrameSet, the Current attribute is modified so -that the new Frame becomes the current one. This behaviour is -reflected in the state of the example FrameSet in -Figure~\ref{fig:fsexample}. - -\subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames} - -It is often necessary to refer to the base and current Frames -(\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be -cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current} -attributes on each occasion. To make this easier, two macros, -AST\_\_BASE and AST\_\_CURRENT, are defined in the ``ast.h'' header -file and may be used to represent the indices of the base and current -Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is -required. - -For example, when adding a new Frame to a FrameSet -(\secref{ss:addingframes}), you could use the following to indicate -that the new Frame is related to the existing current Frame, whatever -its index happens to be: - -\small -\begin{terminalv} -AstFrame *frame; -AstMapping *mapping; - -... - -astAddFrame( frameset, AST__CURRENT, mapping, frame ); -\end{terminalv} -\normalsize - -Of course, the Frame you added would then become the new current -Frame. - -\subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping} - -The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame} -class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class -(\secref{ss:mappings}). Its behaviour when used as a Mapping is -particularly important. - -Consider, for instance, passing a FrameSet pointer to a coordinate -transformation function such as \htmlref{astTran2}{astTran2}: - -\small -\begin{terminalv} -#define N 10 -double xin[ N ], yin[ N ], xout[ N ], yout[ N ]; - -... - -astTran2( frameset, N, xin, yin, 1, xout, yout ); -\end{terminalv} -\normalsize - -The coordinate transformation applied by this FrameSet would be the -one which converts between its base and current Frames. Using the -FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates -would be multiplied by a factor of 5. If we instead requested the -FrameSet's inverse transformation, we would be transforming from its -current Frame to its base Frame, so our example FrameSet would then -multiply by a factor of 0.2. - -Whenever the choice of base and current Frames changes, the -transformations which a FrameSet performs when used as a Mapping also -change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in -consequence, because they are determined by the numbers of axes in the -FrameSet's base and current Frames respectively. These numbers need -not necessarily be equal, of course. - -Like any Mapping, a FrameSet may also be inverted by changing the -boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{astInvert}{astInvert} -(\secref{ss:invertingmappings}). If this is happens, the values of the -FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with -its Nin and Nout attributes, so that its base and current Frames swap -places. When used as a Mapping, the FrameSet will therefore perform -the inverse transformation to that which it performed previously. - -To summarise, a FrameSet may be used exactly like any other Mapping -which inter-relates the coordinate systems described by its base and -current Frames. - -\subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet} - -Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is -required (\secref{ss:framesetasmapping}), a FrameSet necessarily -contains additional information and sometimes this might cause -inefficiency or confusion. For example, if you wanted to use a -Mapping contained in one FrameSet and insert it into another, it would -probably not be efficient to insert the whole of the first FrameSet -into the second one, although it would work. - -In such a situation, the \htmlref{astGetMapping}{astGetMapping} function allows you to extract -a Mapping from a FrameSet. You do this by specifying the two Frames -which the Mapping should inter-relate using their indices within the -FrameSet. For example: - -\small -\begin{terminalv} -map = astGetMapping( frameset, 2, 3 ); -\end{terminalv} -\normalsize - -would return a pointer to a Mapping that converted between Frames~2 -and 3 in the FrameSet. Its inverse transformation would then convert -in the opposite direction, \emph{i.e.}\ between Frames~3 and 2. Note -that this Mapping might not be independent of the Mappings contained -within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so -\htmlref{astCopy}{astCopy} should be used to make a copy if you need to guarantee -independence (\secref{ss:copyingobjects}). - -Very often, the Mapping returned by astGetMapping will be a compound -Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that -conversion between the two Frames may need to be done \emph{via} an -intermediate coordinate system so that several stages may be involved. -You can, however, easily simplify this Mapping (where this is possible) -by using the \htmlref{astSimplify}{astSimplify} function (\secref{ss:simplifyingcmpmaps}) and -this is recommended if you plan to use it for transforming a large -amount of data. - -\subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame} - -A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost -always behaves as if its current Frame had been used instead. For -example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using: - -\small -\begin{terminalv} -const char *title; - -... - -title = astGetC( frameset, "Title" ); -\end{terminalv} -\normalsize - -the result will be the Title of the current Frame, or a suitable -default if the current Frame's Title attribute is un-set. The same -also applies to other attribute operations---\emph{i.e.}\ setting, -clearing and testing attributes. Most attributes shared by both -Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)}, -\htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions: - -\begin{quote} -\begin{description} -\item[\htmlref{Class}{Class}]\mbox{}\\ -Has the value ``FrameSet''. - -\item[\htmlref{ID}{ID}]\mbox{}\\ -Identifies the particular FrameSet (not its current Frame). - -\item[\htmlref{Nin}{Nin}]\mbox{}\\ -Equals the number of axes in the FrameSet's base Frame. - -\item[\htmlref{Invert}{Invert}]\mbox{}\\ -Is independent of any of the Objects within the FrameSet. - -\item[\htmlref{Nobject}{Nobject}]\mbox{}\\ -Counts the number of active FrameSets. - -\item[\htmlref{RefCount}{RefCount}]\mbox{}\\ -Counts the number of active pointers to the FrameSet (not to its -current Frame). -\end{description} -\end{quote} - -Note that the set of attributes possessed by a FrameSet can vary, -depending on the nature of its current Frame. For example, if the -current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet -will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired, -\emph{etc.} However, if the current Frame is changed to be a basic -Frame, which does not have an Equinox attribute, then this attribute -will be absent from the FrameSet as well. Any attempt to reference it -will then result in an error. - -\subsection{Extracting a Frame from a FrameSet} - -Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most -situations, it is sometimes convenient to have direct access to a -specified Frame within it. This may be obtained using the \htmlref{astGetFrame}{astGetFrame} -function, as follows: - -\small -\begin{terminalv} -frame = astGetFrame( frameset, AST__BASE ); -\end{terminalv} -\normalsize - -This would return a pointer (not a copy) to the base Frame within the -FrameSet. Note the use of AST\_\_BASE -(\secref{ss:astbaseandastcurrent}) as shorthand for the value of the -FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index. - -\subsection{Removing a Frame from a FrameSet} - -Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed -using the \htmlref{astRemoveFrame}{astRemoveFrame} function. You identify the Frame you wish to -remove in the usual way, by giving its index within the FrameSet. For -example, the following would remove the Frame with index 1: - -\small -\begin{terminalv} -astRemoveFrame( frameset, 1 ); -\end{terminalv} -\normalsize - -The only restriction is that you cannot remove the last remaining -Frame because a FrameSet must always contain at least one Frame. When -a Frame is removed, the Frames which follow it are re-numbered -(\emph{i.e.}\ their indices are reduced by one) so as to preserve the -sequence of consecutive Frame indices. The FrameSet's \htmlref{Nframe}{Nframe} -attribute is also decremented. - -If appropriate, astRemoveFrame will modify the FrameSet's \htmlref{Base}{Base} and/or -\htmlref{Current}{Current} attributes so that they continue to identify the same Frames -as previously. If either the base or current Frame is removed, -however, the corresponding attribute will become un-set, so that it -reverts to its default value (\secref{ss:baseandcurrentdefault}) and -therefore identifies an alternative Frame. - -Note that it is quite permissible to remove any Frame from a FrameSet, -even although other Frames may appear to depend on it. For example, in -Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct -relationship between Frames~2 and 3 would still be preserved, although -they would be re-numbered as Frames~1 and 2. - -\cleardoublepage -\section{\label{ss:fshigher}Higher Level Operations on FrameSets} - -\subsection{\label{ss:framesetsfromconvert}Creating FrameSets with astConvert} - -Before considering the important subject of using FrameSets to convert -between coordinate systems (\secref{ss:framesetconverting}), let us -return briefly to reconsider the output generated by \htmlref{astConvert}{astConvert}. We -used this function earlier (\secref{ss:introducingconversion}), when -converting between the coordinate systems represented by various kinds -of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the -coordinate conversion it identifies. We are now in a position to -examine the structure of this FrameSet. - -Take our earlier example (\secref{ss:convertingskyframes}) of -converting between the celestial coordinate systems represented by two -SkyFrames: - -\small -\begin{terminalv} -#include "ast.h" -AstFrameSet *cvt; -AstSkyFrame *skyframe1, *skyframe2; - -... - -skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" ); -skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" ); - -cvt = astConvert( skyframe1, skyframe2, "" ); -\end{terminalv} -\normalsize - - This will produce a pointer, ``cvt'', to the FrameSet shown in - Figure~\ref{fig:fsconvert}. - \begin{figure}[bhtp] - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/fsconvert} - \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when astConvert is used to convert - between the coordinate systems represented by two SkyFrames. The - source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame - becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the - required conversion.} - \label{fig:fsconvert} - \end{center} - \end{figure} - -As can be seen, this FrameSet contains just two Frames. The source -Frame supplied to astConvert becomes its base Frame, while the -destination Frame becomes its current Frame. (The FrameSet, of course, -simply holds pointers to these Frames, rather than making copies.) The -Mapping which relates the base Frame to the current Frame is the one -which implements the required conversion. - -As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet -returned by astConvert may be used both as a Mapping and as a Frame to -perform most of the functions you are likely to need. However, the -Mapping may be extracted for use on its own if necessary, using -\htmlref{astGetMapping}{astGetMapping} (\secref{ss:extractingamapping}), for example: - -\small -\begin{terminalv} -AstMapping *mapping; - -... - -mapping = astGetMapping( cvt, AST__BASE, AST__CURRENT ); -\end{terminalv} -\normalsize - -\subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems} - - We now consider the process of converting between the coordinate - systems represented by two FrameSets. This is a most important - operation, as a subsequent example (\secref{ss:registeringimages}) - will show, and is illustrated in Figure~\ref{fig:fsalign}. - \begin{figure} - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/fsalign} - \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion - between two FrameSets is performed by establishing - a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion - between these two Frames is possible, then a route for converting - between the current Frames of both FrameSets can also be found. In - practice, there may be many ways of pairing Frames to find the - ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to - narrow the choice.} - \label{fig:fsalign} - \end{center} - \end{figure} - -Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave -like its current \htmlref{Frame}{Frame} when necessary, conversion between two -FrameSets is performed using \htmlref{astConvert}{astConvert} -(\secref{ss:convertingskyframes}), but supplying pointers to FrameSets -instead of Frames. The effect of this is to convert between the -coordinate systems represented by the current Frames of each FrameSet: - -\small -\begin{terminalv} -AstFrameSet *frameseta, *framesetb; - -... - -cvt = astConvert( frameseta, framesetb, "SKY" ); -\end{terminalv} -\normalsize - -When using FrameSets, we are presented with considerably more -conversion options than when using Frames alone. This is because each -current Frame is related to all the other Frames in its respective -FrameSet. Therefore, if we can establish a link between any pair of -Frames, one from each FrameSet, we can form a complete conversion path -between the two current Frames (Figure~\ref{fig:fsalign}). - -This expanded range of options is, of course, precisely the -intention. By connecting Frames together within a FrameSet, we have -extended the range of coordinate systems that can be reached from any -one of them. We are therefore no longer restricted to converting -between Frames with the same Domain value (\secref{ss:framedomains}), -but can go \emph{via} a range of intermediate coordinate systems in -order to make the connection we require. Transformation between -different domains has therefore become possible because, in assembling -the FrameSets, we provided the additional information needed to -inter-relate them. - -It is important to appreciate, however, that the choice of ``missing -link'' is crucial in determining the conversion that results. -Although each FrameSet may be perfectly self-consistent internally, -this does not mean that all conversion paths through the combined -network of Mappings are equivalent. Quite the contrary in fact: -everything depends on where the inter-connecting link between the two -FrameSets is made. In practice, there may be a large number of -possible pairings of Frames and hence of possible links. Other factors -must therefore be used to restrict the choice. These are: - -\begin{enumerate} -\item Not every possible pairing of Frames is legitimate. For example, -you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which -belong to different classes, so such pairings will be ignored. - -\item In a similar way, you cannot convert directly between Frames -with different Domain values (\secref{ss:framedomains}). If the Domain -attribute is used consistently (typically only one Frame in each -FrameSet will have a particular Domain value), then this further -restricts the choice. - -\item The third argument of astConvert may then be used to specify -explicitly which Domain value the paired Frames should have. You may -also supply a comma-separated list of preferences here (see below). - -\item If the above steps fail to uniquely identify the link, then the -first suitable pairing of Frames is used, so that any ambiguity is -resolved by the order in which Frames are considered for pairing (see -the description of the astConvert function in -\appref{ss:functiondescriptions} for details of the search -order).\footnote{If you find that how this ambiguity is resolved -actually makes a difference to the conversion that results, then you -have probably constructed a FrameSet which lacks internal -self-consistency. For example, you might have two Frames representing -indistinguishable coordinate systems but inter-related by a non-null -\htmlref{Mapping}{Mapping}.} -\end{enumerate} - -In the example above we supplied the string ``SKY'' as the third -argument of astConvert. This constitutes a request that a pair of -Frames with -the Domain value SKY (\emph{i.e.}\ representing celestial coordinate -systems) should be used to inter-relate the two FrameSets. Note that -this does not specify which celestial coordinate system to use, but is -a general request that the two FrameSets be inter-related using -coordinates on the celestial sphere. - -Of course, it may be that this request cannot be met because there may -not be a celestial coordinate system in both FrameSets. If this is -likely to happen, we can supply a list of preferences, or a -\emph{domain search path}, -as the third argument to astConvert, such as -the following: - -\small -\begin{terminalv} -cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID," ); -\end{terminalv} -\normalsize - -Now, if the two FrameSets cannot be inter-related using the SKY domain, -astConvert will attempt to use the PIXEL domain instead. If this -also fails, it will try the GRID domain. A blank field in the domain -search path (here indicated by the final comma) allows any Domain -value to be used. This can be employed as a last resort when all else -has failed. - -If astConvert succeeds in identifying a conversion, it will return a -pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the -source and destination Frames are inter-connected by the required -Mapping. In this case, of course, these Frames will be the current -Frames of the two FrameSets, but in all other respects the returned -FrameSet is the same as when converting between Frames. - -Very importantly, however, astConvert may modify the FrameSets you are -converting between. It does this, in order to indicate which pairing -of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base} -attribute for each FrameSet so that the Frame used in the pairing -becomes its base Frame (\secref{ss:baseandcurrent}). - -Finally, note that astConvert may also be used to convert between a -FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is -supplied for either the first or second argument, it will behave like -a FrameSet containing only a single Frame. - -\subsection{\label{ss:registeringimages}Example---Registering Two Images} - -Consider two images which have been calibrated by attaching FrameSets -to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the -raw data grid coordinates of each image (the GRID domain of -\secref{ss:domainconventions}). Suppose, also, that these FrameSets -contain an unknown number of other Frames, representing alternative -world coordinate systems. What we wish to do is register these two -images, such that we can transform from a position in the data grid of -one into the corresponding position in the data grid of the other. -This is a very practical example because images will typically be -calibrated using FrameSets in precisely this way. - -The first step will probably involve making a copy of both FrameSets -(using \htmlref{astCopy}{astCopy}---\secref{ss:copyingobjects}), since we will be -modifying them. Let ``frameseta'' and ``framesetb'' be pointers to -these copies. Since we want to convert between the base Frames of -these FrameSets (\emph{i.e.}\ their data grid coordinates), the next -step is to make these Frames current. This is simply done by inverting -both FrameSets, which interchanges their base and current -Frames. \htmlref{astInvert}{astInvert} will perform this task: - -\small -\begin{terminalv} -astInvert( frameseta ); -astInvert( framesetb ); -\end{terminalv} -\normalsize - -To identify the required conversion, we now use \htmlref{astConvert}{astConvert}, supplying -a suitable domain search path with which we would like our two images -to be registered: - -\small -\begin{terminalv} -cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID" ); -if ( cvt == AST__NULL ) { - <no conversion was possible> -} else { - <conversion was possible> -} -\end{terminalv} -\normalsize - -The effects of this are: - -\begin{enumerate} -\item astConvert first attempts to register the two images on the -celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it -searches for a celestial coordinate system, although not necessarily -the same one, attached to each image. If it finds a suitable pair of -coordinate systems, it then registers the images by matching -corresponding positions on the sky. - -\item If this fails, astConvert next tries to match positions in the -PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two -images will then be registered so that their corresponding pixel -positions correspond. If the PIXEL domain is offset from the data grid -(as typically happens in data reduction systems which implement a -``pixel origin''), then this will be correctly accounted for. - -\item If this also fails, the GRID domain is finally used. This will -result in image registration by matching corresponding points in the -data grids used by both images. This means they will be -aligned so that the first element their data arrays correspond. - -\item If all of the above fail, astConvert will return the value -AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned. -\end{enumerate} - -The resulting ``cvt'' FrameSet may then be used directly -(\secref{ss:convertingskyframes}) to convert between positions in the -data grid of the first image and corresponding positions in the data -grid of the second image. - -To determine which domain was used to achieve registration, -we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by -astConvert to indicate which intermediate Frames were used. We -can therefore simply invert either FrameSet (to make its base Frame -become the current one) and then enquire the \htmlref{Domain}{Domain} value: - -\small -\begin{terminalv} -const char *domain; - -... - -astInvert( frameseta ); -domain = astGetC( frameseta, "Domain" ); -\end{terminalv} -\normalsize - -If conversion was successful, the result will be one of the strings -``SKY'', ``PIXEL'' or ``GRID''. - -\subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System} - -As discussed earlier (\secref{ss:baseandcurrent}), an important -application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to -be attached to entities such as images in order to calibrate them. In -addition, one of the main objectives of AST is to simplify the -propagation of such information through successive stages of data -processing, so that it remains consistent with the associated image -data. - -In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with -the image's data grid coordinates and its other Frames (if any) with -the various alternative world coordinate systems associated with the -image. If the data processing being performed does not change the -relationship between the image's data grid coordinates and any of the -associated world coordinate systems, then propagation of the WCS -information is straightforward and simply involves copying the -FrameSet associated with the image. - -If any of these relationships change, however, then corresponding -changes must be made to the way Frames within the FrameSet are -inter-related. By far the most common case occurs when the image -undergoes some geometrical transformation resulting in ``re-gridding'' -on to another data grid, but the same principles can be applied to any -re-definition of a coordinate system. - -To pursue the re-gridding example, we would need to modify our -FrameSet to account for the fact that the image's data grid coordinate -system (corresponding to the FrameSet's base Frame) has -changed. Looking at the steps needed in detail, we might proceed as -follows: - -\begin{enumerate} -\item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the -original data grid coordinate system and the new one. - -\item Obtain a Frame to represent the new data grid coordinate system -(we could re-use the original base Frame here, using \htmlref{astGetFrame}{astGetFrame} to -obtain a pointer to it). - -\item Add the new Frame to the FrameSet, related to the original base -Frame by the new Mapping. This Frame now represents the new data grid -coordinate system and is correctly related to all the other Frames -present.\footnote{This is because any transformation to or from this -new Frame must go \emph{via} the base Frame representing the original -data grid coordinate system, which we assume was correctly related to -all the other Frames present.} - -\item Remove the original base Frame (representing the old data grid -coordinate system). - -\item Make the new Frame the base Frame and restore the original -current Frame. -\end{enumerate} - - The effect of these steps is to change the relationship between the - base Frame and all the other Frames present. It is as if a new Mapping - has been interposed between the Frame we want to alter and all the - other Frames within the FrameSet (Figure~\ref{fig:fsremap}). - \begin{figure}[hbtp] - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/fsremap} -\caption[Interposing a Mapping into a FrameSet]{The effect - of \htmlref{astRemapFrame}{astRemapFrame} is to interpose a Mapping between - a nominated Frame within a FrameSet and the remaining contents of the - FrameSet. This effectively ``re-defines'' the coordinate system - represented by the affected Frame. It may be used to compensate (say) - for geometrical changes made to an associated image. The - inter-relationships between all the other Frames within the FrameSet - remain unchanged.} - \label{fig:fsremap} - \end{center} - \end{figure} - -Performing the steps above is rather lengthy, however, so the -astRemapFrame function is provided to perform all of these operations -in one go. A practical example of its use is given below -(\secref{ss:wcsprocessingexample}). - -\subsection{\label{ss:wcsprocessingexample}Example---Binning an Image} - -As an example of using \htmlref{astRemapFrame}{astRemapFrame}, consider a case where the pixels -of a 2-dimensional image have been binned 2$\times$2, so as to reduce -the image size by a factor of two in each dimension. We must now -modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the -image. Much the same process would be needed for any other geometrical -change the image might undergo. - -We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the -data grid coordinates in the original image to those in the new one: - -\small -\begin{terminalv} -AstWinMap *winmap; -double ina[ 2 ] = { 0.5, 0.5 }; -double inb[ 2 ] = { 2.5, 2.5 }; -double outa[ 2 ] = { 0.5, 0.5 }; -double outb[ 2 ] = { 1.5, 1.5 }; - -... - -winmap = astWinMap( 2, ina, inb, outa, outb, "" ); -\end{terminalv} -\normalsize - -Here, we have simply set up arrays containing the data grid -coordinates of the bottom left and top right corners of the first -element in the output image (``outa'' and ``outb'') and the -corresponding coordinates in the input image (``ina'' and -``inb''). \htmlref{astWinMap}{astWinMap} then creates a WinMap which performs the required -transformation. We do not need to know the size of the image. - -We can then pass this WinMap to astRemapFrame. This modifies the -relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in -the FrameSet, so that the base Frame represents the data grid -coordinate system of the new image rather than the old one: - -\small -\begin{terminalv} -AstFrameSet *frameset; - -... - -astRemapFrame( frameset, AST__BASE, winmap ); -\end{terminalv} -\normalsize - -Any other coordinate systems described by the FrameSet, no matter how -many of these there might be, are now correctly associated with the -new image. - -\subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets} - -When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into -which you can place any combination of Frames and Mappings that you -wish. There are relatively few constraints on this process and no -checks are performed to see whether the FrameSet you construct makes -physical sense. It is quite possible, for example, to construct a -FrameSet containing two identical SkyFrames which are inter-related by -a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes -no sense, because applying a non-unit Mapping to any set of celestial -coordinates cannot yield positions that are still in the original -coordinate system. If you use such a FrameSet to perform coordinate -conversions, you are likely to get unpredictable results because the -information in the FrameSet is corrupt. - -It is, of course, your responsibility as a programmer to ensure the -validity of any information which you insert into a -FrameSet. Normally, this is straightforward and simply consists of -formulating your problem correctly (a diagram can often help to -clarify how coordinate systems are inter-related) and writing the -appropriate bug-free code to construct the FrameSet. However, once you -start to modify an existing FrameSet, there are new opportunities for -corrupting it! - -Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a -\htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute -simply by using \htmlref{astSet}{astSet} on the FrameSet, as follows: - -\small -\begin{terminalv} -astSet( frameset, "Equinox=J2010" ); -\end{terminalv} -\normalsize - -The effect of this will be to change the celestial coordinate system -which the current Frame represents. You can see, however, that this -has the potential to make the FrameSet corrupt unless corresponding -changes are also made to the Mapping which relates this SkyFrame to -the other Frames within the FrameSet. In fact, it is a general rule -that any change to a FrameSet which affects its current Frame can -potentially require corresponding changes to the FrameSet's Mappings -in order to maintain its overall integrity. - -Fortunately, once you have stored valid information in a FrameSet, AST -will look after these details for you automatically, so that the -FrameSet's integrity is maintained. In the example above, it would do -this by appropriately re-mapping the current Frame (as if -\htmlref{astRemapFrame}{astRemapFrame} had been used---\secref{ss:remapframe}) in response to -the use of astSet. One way of illustrating this process is as follows: - -\small -\begin{terminalv} -AstSkyFrame *skyframe; - -... - -skyframe = astSkyFrame( "" ); -frameSet = astFrameSet( skyframe ); -astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe ); -\end{terminalv} -\normalsize - -This constructs a trivial FrameSet whose base and current Frames are -both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this -as a ``pipe'' connecting two coordinate systems. At present, these two -systems represent identical ICRS coordinates, so the FrameSet -implements a unit Mapping. We can change the coordinate system on the -current end of this pipe as follows: - -\small -\begin{terminalv} -astSet( frameset, "System=Ecliptic, Equinox=J2010" ); -\end{terminalv} -\normalsize - -and the Mapping which the FrameSet implements would change -accordingly. To change the coordinate system on the base end of the -pipe, we might use: - -\small -\begin{terminalv} -astInvert( frameset ); -astSet( frameset, "System=Galactic" ); -astInvert( frameset ); -\end{terminalv} -\normalsize - -The FrameSet would then convert between galactic and ecliptic -coordinates. - -Note that astSet is not the only function which has this effect: -\htmlref{astClear}{astClear} behaves similarly, as also does \htmlref{astPermAxes}{astPermAxes} -(\secref{ss:permutingaxes}). If you need to circumvent this mechanism -for any reason, this can be done by going behind the scenes and -obtaining a pointer directly to the Frame you wish to modify. Consider -the following, for example: - -\small -\begin{terminalv} -skyframe = astGetFrame( frameset, AST__CURRENT ); -astSet( skyframe, "Equinox=J2010" ); -skyframe = astAnnul( skyframe ); -\end{terminalv} -\normalsize - -Here, astSet is applied to the SkyFrame pointer rather than the -FrameSet pointer, so the usual checks on FrameSet integrity do not -occur. The SkyFrame's Equinox attribute will therefore be modified -without any corresponding change to the FrameSet's Mappings. In this -case you must take responsibility yourself for maintaining the -FrameSet's integrity, perhaps through appropriate use of -astRemapFrame. - -\subsection{Merging FrameSets} - - As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet} - (\secref{ss:addingframes}), it is also possible to add complete sets of - inter-related Frames which are contained within another - FrameSet. This, of course, corresponds to the process of merging two - FrameSets (Figure~\ref{fig:fsmerge}). - \begin{figure}[hbtp] - \begin{center} - \includegraphics[width=0.7\textwidth]{sun211_figures/fsmerge} - \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using - \htmlref{astAddFrame}{astAddFrame}. FrameSet~B is being added to FrameSet~A by supplying a - new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1) - and the current Frame of B. In the merged FrameSet, the Frames - contributed by B will be re-numbered to become Frames~4, 5 and 6. The - base Frame will remain unchanged, but the current Frame of B becomes - the new current Frame. Note that FrameSet~B itself is not - altered by this process.} - \label{fig:fsmerge} - \end{center} - \end{figure} - - - -This process is performed by adding one FrameSet to another using -astAddFrame, in much the same manner as when adding a new Frame to an -existing FrameSet (\secref{ss:addingframes}). It is simply a matter of -providing a FrameSet pointer, instead of a Frame pointer, for the 4th -argument. In performing the merger you must, as usual, supply a -Mapping, but in this case the Mapping should relate the current Frame -of the FrameSet being added to one of the Frames already present. For -example, you might perform the merger shown in -Figure~\ref{fig:fsmerge} as follows: - -\small -\begin{terminalv} -AstMapping *mapping; - -... - -astAddFrame( frameseta, 1, mapping, framesetb ); -\end{terminalv} -\normalsize - -The Frames acquired by ``frameseta'' from the FrameSet being added -(``framesetb'') are re-numbered so that they retain their original -order and follow on consecutively after the Frames that were already -present, whose indices remain unchanged. The base Frame of -``frameseta'' remains unchanged, but the current Frame of -``framesetb'' becomes its new current Frame. All the -inter-relationships between Frames in both FrameSets remain in place -and are preserved in the merged FrameSet. - -Note that while this process modifies the first FrameSet -(``frameseta''), it leaves the original contents of the one being -added (``framesetb'') unchanged. - -%\cleardoublepage -%\section{\label{ss:searching}TBW - Searching for Coordinate Systems} - -\cleardoublepage -\section{\label{ss:channels}Saving and Restoring Objects (Channels)} - -Facilities are provided by the AST library for performing input and -output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible -to write any Object into various external representations for -storage, and then to read these representations back in, so as to -restore the original Object. Typically, an Object would be written by -one program and read back in by another. - -We refer to ``external representations'' in the plural because AST is -designed to function independently of any particular data storage -system. This means that Objects may need converting into a number of -different external representations in order to be compatible with -(say) the astronomical data storage system in which they will reside. - -In this section, we discuss the basic I/O facilities which support -external representations based on a textual format referred to as the AST -``native format''. These are implemented using a new kind of Object---a -\htmlref{Channel}{Channel}. We will examine later how to use other representations, based on -an XML format or on the use of FITS headers, for storing Objects. These -are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan} -(\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}). - -\subsection{The Channel Model} - -The best way to start thinking about a \htmlref{Channel}{Channel} is like a C file -stream, and to think of the process of creating a Channel as that -of opening a file and obtaining a FILE pointer. Subsequently, you can -read and write Objects \emph{via} the Channel. - -This analogy is not quite perfect, however, because a Channel has, in -principle, two ``files'' attached to it. One is used when reading, and -the other when writing. These are termed the Channel's \emph{source} -and \emph{sink} respectively. In practice, the source and sink may -both be the same, in which case the analogy with the C file stream is -correct, but this need not always be so. It is not necessarily so with -the basic Channel, as we will now see (\secref{ss:creatingachannel}). - -\subsection{\label{ss:creatingachannel}Creating a Channel} - -The process of creating a \htmlref{Channel}{Channel} is straightforward. As you -might expect, it uses the constructor function \htmlref{astChannel}{astChannel}: - -\small -\begin{terminalv} -#include "ast.h" -AstChannel *channel; - -... - -channel = astChannel( NULL, NULL, "" ); -\end{terminalv} -\normalsize - -The first two arguments to astChannel specify the external source and -sink that the Channel is to use. There arguments are pointers to C -functions and we will examine their use in more detail later -(\secref{ss:channelsource} and \secref{ss:channelsink}). - -In this very simple example we have supplied NULL pointers for both -the source and sink functions. This requests the default behaviour, -which means that textual input will be read from the program's -standard input stream (typically, this means your keyboard) while -textual output will go to the standard output stream (typically -appearing on your screen). On UNIX systems, of course, either of these -streams can easily be redirected to files. This default behaviour can be -changed by assigning values to the Channel's \htmlref{SinkFile}{SinkFile} and/or \htmlref{SourceFile}{SourceFile} -attributes. These attributes specify the paths to text files that are to -be used in place of the standard input and output streams. - -\subsection{\label{ss:writingtoachannel}Writing Objects to a Channel} - -The process of saving Objects is very straightforward. You can -simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{astWrite}{astWrite} -function, as follows: - -\small -\begin{terminalv} -int nobj; -AstObject *object; - -... - -nobj = astWrite( channel, object ); -\end{terminalv} -\normalsize - -The effect of this will be to produce a textual description of the -Object which will appear, by default, on your program's standard -output stream. Any class of Object may be converted into text in this -way. - -astWrite returns a count of the number of Objects written. Usually, -this will be one, unless the Object supplied cannot be -represented. With a basic Channel all Objects can be represented, so a -value of one will always be returned unless there has been an -error. We will see later, however, that more specialised forms of -Channel may impose restrictions on the kind of Object you can write -(\secref{ss:foreignfitslimitations}). In such cases, astWrite may -return zero to indicate that the Object was not acceptable. - -\subsection{\label{ss:readingfromachannel}Reading Objects from a Channel} - -Before discussing the format of the output produced above -(\secref{ss:writingtoachannel}), let us consider how to read it back, -so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first -need to save the output in a file. We can do that either by using the -\htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output -to a file using a shell command like: - -\small -\begin{terminalv} -program1 >file -\end{terminalv} -\normalsize - -Within a subsequent program, we can read this Object back in by -using the \htmlref{astRead}{astRead} function, having first created a suitable -\htmlref{Channel}{Channel}: - -\small -\begin{terminalv} -object = astRead( channel ); -\end{terminalv} -\normalsize - -By default, this function will read from the standard input stream -(the default source for a basic Channel), so we would need to ensure -that our second program reads its input from the file in which the -Object description is stored. On UNIX systems, we could again use a -shell redirection command such as: - -\small -\begin{terminalv} -program2 <file -\end{terminalv} -\normalsize - -Alternatively, we could have assigned a value to the SinkFile attribute -before invoking -astRead. - -\subsection{Saving and Restoring Multiple Objects} - -I/O operations performed on a basic \htmlref{Channel}{Channel} are sequential. This -means that if you write more than one \htmlref{Object}{Object} to a Channel, -each new Object's textual description is simply appended to the -previous one. You can store any number of Objects in this way, -subject only to the storage space you have available. - -After you read an Object back from a basic Channel, the -Channel is ``positioned'' at the end of that Object's -textual description. If you then perform another read, you will -read the next Object's textual description and therefore -retrieve the next Object. This process may be repeated to read -each Object in turn. When there are no more Objects to be -read, \htmlref{astRead}{astRead} will return the value AST\_\_NULL to indicate an -\emph{end-of-file}. - -\subsection{\label{ss:validatinginput}Validating Input} - -The pointer returned by \htmlref{astRead}{astRead} (\secref{ss:readingfromachannel}) could -identify any class of \htmlref{Object}{Object}---this is determined entirely by the -external data being read. If it is necessary to test for a particular -class (say a \htmlref{Frame}{Frame}), this may be done as follows using the appropriate -member of the \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$} family of functions: - -\small -\begin{terminalv} -int ok; - -... - -ok = astIsAFrame( object ); -\end{terminalv} -\normalsize - -Note, however, that this will accept any Frame, so would be equally -happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}. An alternative validation -strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute -and then test this character string, as follows: - -\small -\begin{terminalv} -#include <string.h> - -... - -ok = !strcmp( astGetC( object, "Class" ), "Frame" ); -\end{terminalv} -\normalsize - -This would only accept a basic Frame and would reject a SkyFrame. - -\subsection{Storing an ID String with an Object} - -Occasionally, you may want to store a number of Objects and later -retrieve them and use each for a different purpose. If the Objects are -of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish -them when you read them back -(\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the -order in which they are stored is a possible solution, this becomes -complicated if some of the Objects are optional and may not always be -present. It also makes extending your data format in future more -difficult. - -To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident} -attribute, both of which allows you, in effect, to attach a textual -identification label to it. You simply set the ID or Ident attribute before -writing the Object: - -\small -\begin{terminalv} -astSet( object, "ID=Calibration" ); -nobj = astWrite( channel, object ); -\end{terminalv} -\normalsize - -You can then test its value after you read the Object back: - -\small -\begin{terminalv} -object = astRead( channel ); -if ( !strcmp( astGetC( object, "ID" ), "Calibration" ) ) { - <the Calibration Object has been read> -} else { - <some other Object has been read> -} -\end{terminalv} -\normalsize - -The only difference between the ID and Ident attributes is that the ID -attribute is unique to a particular Object and is lost if, for example, -you make a copy of the Object. The Ident attrubute, on the other hand, is -transferred to the new Object when a copy is made. Consequently, it is -safest to set the value of the ID attribute immediately before you -perform the write. - -\subsection{\label{ss:textualoutputformat}The Textual Output Format} - -Let us now examine the format of the textual output produced by -writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel} -(\secref{ss:writingtoachannel}). To give a concrete example, suppose -the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows: - -\small -\begin{terminalv} -AstSkyFrame *skyframe; - -... - -nobj = astWrite( channel, skyframe ); -\end{terminalv} -\normalsize - -The output should then look like the following: - -\small -\begin{terminalv} - Begin SkyFrame # Description of celestial coordinate system -# Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system - Naxes = 2 # Number of coordinate axes -# Domain = "SKY" # Coordinate system domain -# Lbl1 = "Right Ascension" # Label for axis 1 -# Lbl2 = "Declination" # Label for axis 2 -# Uni1 = "hh:mm:ss.s" # Units for axis 1 -# Uni2 = "ddd:mm:ss" # Units for axis 2 -# Dir1 = 0 # Plot axis 1 in reverse direction (hint) - Ax1 = # Axis number 1 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - Ax2 = # Axis number 2 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - IsA Frame # Coordinate system description - System = "FK4-NO-E" # Celestial coordinate system type - Epoch = 1958 # Besselian epoch of observation -# Eqnox = 1950 # Besselian epoch of mean equinox - End SkyFrame -\end{terminalv} -\normalsize - -You will notice that this output is designed both for a human reader, -in that it is formatted, and also to be read back by a computer in -order to reconstruct the SkyFrame. In fact, this is precisely the way -that \htmlref{astShow}{astShow} works (\secref{ss:displayingobjects}), this function being -roughly equivalent to the following use of a Channel: - -\small -\begin{terminalv} -channel = astChannel( NULL, NULL, "" ); -(void) astWrite( channel, object ); -channel = astAnnul( channel ); -\end{terminalv} -\normalsize - -Some lines of the output start with a ``\verb?#?'' comment character, -which turns the rest of the line into a comment. These lines will be -ignored when read back in by \htmlref{astRead}{astRead}. They typically contain default -values, or values that can be derived in some way from the other data -present, so that they do not actually need to be stored in order to -reconstruct the original Object. They are provided purely for human -information. The same comment character is also used to append -explanatory comments to most output lines. - -It is not sensible to attempt a complete description of this output -format because every class of Object is potentially different and each -can define how its own data should be represented. However, there are -some basic rules, which mean that the following common features will -usually be present: - -\begin{enumerate} -\item Each Object is delimited by matching ``Begin'' and ``End'' -lines, which also identify the class of Object involved. - -\item Within each Object description, data values are represented -by a simple ``keyword~$=$~value'' syntax, with one value to a line. - -\item Lines beginning ``IsA'' are used to mark the divisions between -data belonging to different levels in the class hierarchy -(\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data -associated with the Frame class and the start of data associated with -some derived class (a SkyFrame in the above example). ``IsA'' lines -may be omitted if associated data values are absent and no confusion -arises. - -\item Objects may contain other Objects as data. This is -indicated by an absent value, with the description of the data -Object following on subsequent lines. - -\item Indentation is used to clarify the overall structure. -\end{enumerate} - -Beyond these general principles, the best guide to what a particular -line of output represents will generally be the comment which -accompanies it together with a general knowledge of the class of -Object being described. - -\subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output} - -It is not always necessary for the output from \htmlref{astWrite}{astWrite} -(\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has -attributes that allow the amount of detail in the output to be -controlled. - -The first of these is the integer attribute \htmlref{Full}{Full}, which controls the -extent to which optional, commented out, output lines are produced. By -default, Full is zero, and this results in the standard style of -output (\secref{ss:textualoutputformat}) where default values that may -be helpful to humans are included. To suppress these optional lines, -Full should be set to $-$1. This is most conveniently done when the -Channel is created, so that: - -\small -\begin{terminalv} -channel = astChannel( NULL, NULL, "Full=-1" ); -(void) astWrite( channel, skyframe ); -channel = astAnnul( channel ); -\end{terminalv} -\normalsize - -would result in output containing only the essential information, such -as: - -\small -\begin{terminalv} - Begin SkyFrame # Description of celestial coordinate system - Naxes = 2 # Number of coordinate axes - Ax1 = # Axis number 1 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - Ax2 = # Axis number 2 - Begin SkyAxis # Celestial coordinate axis - End SkyAxis - IsA Frame # Coordinate system description - System = "FK4-NO-E" # Celestial coordinate system type - Epoch = 1958 # Besselian epoch of observation - End SkyFrame -\end{terminalv} -\normalsize - -In contrast, setting Full to $+$1 will result in additional output -lines which will reveal every last detail of the \htmlref{Object}{Object}'s -construction. Often this will be rather more than you want, especially -for more complex Objects, but it can sometimes help when debugging -programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail: - -\small -\begin{terminalv} - Begin SkyFrame # Description of celestial coordinate system -# RefCnt = 1 # Count of active Object pointers -# Nobj = 1 # Count of active Objects in same class - IsA Object # Astrometry Object -# Nin = 2 # Number of input coordinates -# Nout = 2 # Number of output coordinates -# Invert = 0 # Mapping not inverted -# Fwd = 1 # Forward transformation defined -# Inv = 1 # Inverse transformation defined -# Report = 0 # Don't report coordinate transformations - IsA Mapping # Mapping between coordinate systems -# Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" # Title of coordinate system - Naxes = 2 # Number of coordinate axes -# Domain = "SKY" # Coordinate system domain -# Lbl1 = "Right Ascension" # Label for axis 1 -# Lbl2 = "Declination" # Label for axis 2 -# Sym1 = "RA" # Symbol for axis 1 -# Sym2 = "Dec" # Symbol for axis 2 -# Uni1 = "hh:mm:ss.s" # Units for axis 1 -# Uni2 = "ddd:mm:ss" # Units for axis 2 -# Dig1 = 7 # Individual precision for axis 1 -# Dig2 = 7 # Individual precision for axis 2 -# Digits = 7 # Default formatting precision -# Fmt1 = "hms.1" # Format specifier for axis 1 -# Fmt2 = "dms" # Format specifier for axis 2 -# Dir1 = 0 # Plot axis 1 in reverse direction (hint) -# Dir2 = 1 # Plot axis 2 in conventional direction (hint) -# Presrv = 0 # Don't preserve target axes -# Permut = 1 # Axes may be permuted to match -# MinAx = 2 # Minimum number of axes to match -# MaxAx = 2 # Maximum number of axes to match -# MchEnd = 0 # Match initial target axes -# Prm1 = 1 # Axis 1 not permuted -# Prm2 = 2 # Axis 2 not permuted - Ax1 = # Axis number 1 - Begin SkyAxis # Celestial coordinate axis -# RefCnt = 1 # Count of active Object pointers -# Nobj = 2 # Count of active Objects in same class - IsA Object # Astrometry Object -# Label = "Angle on Sky" # Axis Label -# Symbol = "delta" # Axis symbol -# Unit = "ddd:mm:ss" # Axis units -# Digits = 7 # Default formatting precision -# Format = "dms" # Format specifier -# Dirn = 1 # Plot in conventional direction - IsA Axis # Coordinate axis -# Format = "dms" # Format specifier -# IsLat = 0 # Longitude axis (not latitude) -# AsTime = 0 # Display values as angles (not times) - End SkyAxis - Ax2 = # Axis number 2 - Begin SkyAxis # Celestial coordinate axis -# RefCnt = 1 # Count of active Object pointers -# Nobj = 2 # Count of active Objects in same class - IsA Object # Astrometry Object -# Label = "Angle on Sky" # Axis Label -# Symbol = "delta" # Axis symbol -# Unit = "ddd:mm:ss" # Axis units -# Digits = 7 # Default formatting precision -# Format = "dms" # Format specifier -# Dirn = 1 # Plot in conventional direction - IsA Axis # Coordinate axis -# Format = "dms" # Format specifier -# IsLat = 0 # Longitude axis (not latitude) -# AsTime = 0 # Display values as angles (not times) - End SkyAxis - IsA Frame # Coordinate system description - System = "FK4-NO-E" # Celestial coordinate system type - Epoch = 1958 # Besselian epoch of observation -# Eqnox = 1950 # Besselian epoch of mean equinox - End SkyFrame -\end{terminalv} -\normalsize - -\subsection{\label{ss:channelcommenting}Controlling Commenting} - -Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the -boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments -are appended to describe the purpose of each value. Comment has the -value 1 by default but, if set to zero, will suppress these -comments. This is normally appropriate only if you wish to minimise -the amount of output, for example: - -\small -\begin{terminalv} -astSet( channel, "Full=-1, Comment=0" ); -nobj = astWrite( channel, skyframe ); -\end{terminalv} -\normalsize - -might result in the following more compact output: - -\small -\begin{terminalv} - Begin SkyFrame - Naxes = 2 - Ax1 = - Begin SkyAxis - End SkyAxis - Ax2 = - Begin SkyAxis - End SkyAxis - IsA Frame - System = "FK4-NO-E" - Epoch = 1958 - End SkyFrame -\end{terminalv} -\normalsize - -\subsection{Editing Textual Output} - -The safest advice about editing the textual output from \htmlref{astWrite}{astWrite} (or -\htmlref{astShow}{astShow}) is ``don't!''---unless you know what you are doing. - -Having given that warning, however, it is sometimes possible to make -changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from -scratch, and to read the results back in to construct new -Objects. Normally, simple changes to numerical values are safest, but -be aware that this is a back door method of creating Objects, so -you are on your own! There are a number of potential pitfalls. In -particular: - -\begin{itemize} -\item \htmlref{astRead}{astRead} is intended for retrieving data written by astWrite and -not for reading data input by humans. As such, the data validation -provided is very limited and is certainly not foolproof. This makes it -quite easy to construct Objects that are internally inconsistent by -this means. In contrast, the normal programming interface incorporates -numerous checks designed to make it impossible to construct invalid -Objects. You should not necessarily think you have found a bug if your -changes to an Object's textual description fail to produce the results -you expected! - -\item In many instances the names associated with values in textual -output will correspond with Object attributes. Sometimes, however, -these names may differ from the attribute name. This is mainly because -of length restrictions imposed by other common external formats, such -as FITS headers. Some of the names used do not correspond with -attributes at all. - -\item It is safest to change single numerical or string values. -Beware of changing the size or shape of Objects (\emph{e.g.}\ the -number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others -stored elsewhere within the Object and changing them in a haphazard -fashion will not produce useful results. - -\item Be wary about un-commenting default values. Sometimes this will -work, but often these values are derived from other Objects stored -more deeply in the structure and the proper place to insert a new -value is not where the default itself appears. -\end{itemize} - -\subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text} - -By default, when you use \htmlref{astRead}{astRead} to read from a basic \htmlref{Channel}{Channel} -(\secref{ss:readingfromachannel}), it is assumed that you are reading a -stream of text containing only AST Objects, which follow each other -end-to-end. If any extraneous input data are encountered which do not -appear to form part of the textual description of an \htmlref{Object}{Object}, then an -error will result. In particular, the first input line must identify -the start of an Object description, so you cannot start reading half -way through an Object. - -Sometimes, however, you may want to store AST Object descriptions -intermixed with other textual data. You can do this by setting the -Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every -read to skip over extraneous data until the start of a new AST Object -description, if any, is found. So long as your other data do not mimic -the appearance of an AST Object description, the two sets of data can -co-exist. - -For example, by setting Skip to 1, the following complete C program -will read all the AST Objects whose descriptions appear in the source -of this document, ignoring the other text. \htmlref{astShow}{astShow} is used to display -those found: - -\small -\begin{terminalv} -#include "ast.h" -main() { - AstChannel *channel; - AstObject *object; - - channel = astChannel( NULL, NULL, "Skip=1" ); - while ( ( object = astRead( channel ) ) != AST__NULL ) { - astShow( object ); - object = astAnnul( object ); - } - channel = astAnnul( channel ); -} -\end{terminalv} -\normalsize - -\subsection{\label{ss:channelsource}Reading Objects from Files} - -Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel} -in reading and writing Objects through a program's standard input and -output streams. We will now consider how to access Objects stored in -files more directly. - -The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of -the Channel. For instance, the following will read a pair of Objects from -a text file called ``fred.txt'': - -\small -\begin{terminalv} -astSet( channel, "SourceFile=fred.txt" ); -obj1 = astRead( channel ); -obj2 = astRead( channel ); -astClear( channel, "SourceFile" ); -\end{terminalv} -\normalsize - -Note, the act of clearing the attribute tells AST that no more Objects -are to be read from the file and so the file is then closed. If the -attribute is not cleared, the file will remain open and further Objects -can be read from it. The file will always be closed when the Channel is -deleted. - -This simple approach will normally be sufficient. However, because the -AST library is designed to be used from more than one language, it has -to be a little careful about reading and writing to files. This is due -to incompatibilities that may exist between the file I/O facilities -provided by different languages. If such incompatibilities prevent the -above simple system being used, we need to adopt a system that off-loads -all file I/O to external code. - -What this means in practice is that if the above simple approach cannot -be used, you must instead provide some simple C -functions that perform the actual transfer of data to and from files -and similar external data stores. The functions you provide are -supplied as the source and/or sink function arguments to \htmlref{astChannel}{astChannel} -when you create a Channel (\secref{ss:creatingachannel}). An example is -the best way to illustrate this. - -Consider the following simple function called Source. It reads a -single line of text from a C input stream and returns a pointer to it, -or NULL if there is no more input: - -\small -\begin{terminalv} -#include <stdio.h> -#define LEN 200 -static FILE *input_stream; - -const char *Source( void ) { - static char buffer[ LEN + 2 ]; - return fgets( buffer, LEN + 2, input_stream ); -} -\end{terminalv} -\normalsize - -Note that the input stream is a static variable which we will also -access from our main program. This might look something like this -(omitting error checking for brevity): - -\small -\begin{terminalv} -/* Open the input file. */ -input_stream = fopen( "infile.ast", "r" ); - -/* Create a Channel and read an Object from it. */ -channel = astChannel( Source, NULL, "" ); -object = astRead( channel ); - -... - -/* Annul the Channel and close the file when done. */ -channel = astAnnul( channel ); -(void) fclose( input_stream ); -\end{terminalv} -\normalsize - -Here, we first open the required input file, saving the resulting FILE -pointer. We then pass a pointer to our Source function as the first -argument to astChannel when creating a new Channel. When we read -an \htmlref{Object}{Object} from this Channel with \htmlref{astRead}{astRead}, the Source -function will be called to obtain the textual data from the file, the -end-of-file being detected when this function returns NULL. - -Note, if a value is set for the SourceFile attribute, -the astRead function will ignore any source function -specified when the Channel was created. - -\subsection{\label{ss:channelsink}Writing Objects to Files} - -As for reading, writing Objects to files can be done in two different ways. -Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}. -For instance, the following will write a pair of Objects to a text file -called ``fred.txt'': - -\small -\begin{terminalv} -astSet( channel, "SinkFile=fred.txt" ); -nobj = astWrite( channel, object1 ); -nobj = astWrite( channel, object2 ); -astClear( channel, "SinkFile" ); -\end{terminalv} -\normalsize - -Note, the act of clearing the attribute tells AST that no more output -will be written to the file and so the file is then closed. If the -attribute is not cleared, the file will remain open and further Objects -can be written to it. The file will always be closed when the Channel is -deleted. - -If the details of the language's I/O system on the computer you are using -means that the above approach cannot be used, then we can write a Sink function, -that writes a line of output text to a file, and use it in basically the same -way as the Source function in the previous section (\secref{ss:channelsource}): - -\small -\begin{terminalv} -static FILE *output_stream; - -void Sink( const char *line ) { - (void) fprintf( output_stream, "%s\n", line ); -} -\end{terminalv} -\normalsize - -Note that we must supply the final newline character ourselves. - -In this case, our main program would supply a pointer to this Sink -function as the second argument to \htmlref{astChannel}{astChannel}, as follows: - -\small -\begin{terminalv} -/* Open the output file. */ -output_stream = fopen( "outfile.ast", "w" ); - -/* Create a Channel and write an Object to it. */ -channel = astChannel( Source, Sink, "" ); -nobj = astWrite( channel, object ); - - ... - -/* Annul the Channel and close the file when done. */ -channel = astAnnul( channel ); -(void) fclose( output_stream ); -\end{terminalv} -\normalsize - -Note that we can specify a source and/or a sink function for the -Channel, and that these may use either the same file, or different -files according to whether we are reading or writing. AST has no -knowledge of the underlying file system, nor of file positioning. It -just reads and writes sequentially. If you wish, for example, to -reposition a file at the beginning in between reads and writes, then -this can be done directly (and completely independently of AST) using -standard C functions. - -If an error occurs in your source or sink function, you can -communicate this to the AST library by setting its error status to any -error value using \htmlref{astSetStatus}{astSetStatus} (\secref{ss:errordetection}). This will -immediately terminate the read or write operation. - -Note, if a value is set for the SinkFile attribute, -the \htmlref{astWrite}{astWrite} function will ignore any sink function -specified when the Channel was created. - -\subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places} - -It should be obvious from the above (\secref{ss:channelsource} and -\secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink functions -provide a flexible means of intercepting textual data that describes -AST Objects as it flows in and out of your program. In fact, you might -like to regard a Channel simply as a filter for converting AST Objects -to and from a stream of text which is then handled by your source and -sink functions, where the real I/O occurs. - -This gives you the ability to store AST Objects in virtually any data -system, so long as you can convert a stream of text into something -that can be stored (it need no longer be text) and retrieve it -again. There is generally no need to retain comments. Other -possibilities, such as inter-process and network communication, could -also be implemented \emph{via} source and sink functions in basically -the same way. - -\cleardoublepage -\section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)} - -A FITS header is a sequence of 80-character strings, formatted -according to particular rules defined by the Flexible Image Transport -\htmlref{System}{System} -(FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/} -is a widely-used standard for data interchange in astronomy and has -also been adopted as a data processing format in some astronomical -data reduction systems. The individual 80-character strings in a FITS -header are usually called \emph{cards} or \emph{header cards} (for -entirely anachronistic reasons). - -A sequence of FITS cards appears as a header at the start of every -FITS data file, and sometimes also at other points within it, and is -used to provide ancillary information which qualifies or describes the -main array of data stored in the file. As such, FITS headers are prime -territory for storing information about the coordinate systems -associated with data held in FITS files. - -In this section, we will examine how to store information in FITS -headers directly in the form of AST Objects---a process which is -supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our -discussion here will turn out to be a transitional step that -emphasises the similarities between a FitsChan and a Channel -(\secref{ss:channels}). At the same time, it will prepare us for the -next section (\secref{ss:foreignfits}), where we will examine how to -use a FitsChan to tackle some of the more difficult problems that FITS -headers can present. - -\subsection{\label{ss:nativeencoding}The Native FITS Encoding} - -As it turns out, we are not the first to have thought of storing WCS -information in FITS headers. In fact, the original FITS standard (1981 -vintage) defined a set of header keywords for this purpose which have -been widely used, although they have proved too limited for many -practical purposes. - -At the time of writing, a number of different ways of using FITS -headers for storing WCS information are in use, most (although not -all) based on the original standard. We will refer to these -alternative ways of storing the information as FITS \emph{encodings} -but will defer a discussion of their advantages and limitations until -the next section (\secref{ss:foreignfits}). - -Here, we will examine how to store AST Objects directly in FITS -headers. In effect, this defines a new encoding, which we will term -the \emph{native encoding}. This is a special kind of encoding, -because not only does it allow us to associate conventional -WCS calibration information with FITS data, but it also allows any other -information that can be expressed in terms of AST Objects to be stored -as well. In fact, the native encoding provides us with facilities -roughly analogous to those of the \htmlref{Channel}{Channel} -(\secref{ss:channels})---\emph{i.e.}\ a lossless way of -transferring AST Objects from program to program---but based on FITS -headers instead of free-format text. - -\subsection{The FitsChan Model} - -I/O between AST Objects and FITS headers is supported by a specialised -form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which -may hold any number, including zero, of FITS header cards. This buffer -forms a workspace in which you can assemble FITS cards and manipulate -them before writing them out to a file. - -By default, when a FitsChan is first created, it contains no cards and -there are five ways of inserting cards into it: - -\begin{enumerate} -\item You may add cards yourself, one at a time, using \htmlref{astPutFits}{astPutFits} -(\secref{ss:addingfitscards}). - -\item You may add cards yourself, supplying all cards concatenated into a -single string, using \htmlref{astPutCards}{astPutCards} -(\secref{ss:addingmulticards}). - -\item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{astWrite}{astWrite}), -which will have the effect of creating new cards within the FitsChan -which describe the Object (\secref{ss:writingnativefits}). - -\item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan. -The value should be the path to a text file holding a set of FITS header -cards, one per line. When the SourceFile value is set (using -astSetC or \htmlref{astSet}{astSet}), -the file is opened and the headers copied from it into the FitsChan. -The file is then immediately closed. - -\item You may specify a source function which reads data from some -external store of FITS cards, just like the source associated with a -basic Channel (\secref{ss:channelsource}). If you supply a source -function, it will be called when the FitsChan is created in order to -fill it with an initial set of cards (\secref{ss:fitssourceandsink}). -\end{enumerate} - -There are also four ways of removing cards from a FitsChan: - -\begin{enumerate} -\item You may delete cards yourself, one at a time, using \htmlref{astDelFits}{astDelFits} -(\secref{ss:findingandchangingfits}). - -\item You may read an AST Object from the FitsChan (using \htmlref{astRead}{astRead}), -which will have the effect of removing those cards from the FitsChan -which describe the Object (\secref{ss:readingnativefits}). - -\item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When -the FitsChan is deleted, any remaining headers are written out to a text -file with path equal to the value of the SinkFile attribute. - -\item Alternatively, you may specify a sink function which writes data to some -external store of FITS cards, just like the sink associated with a -basic Channel (\secref{ss:channelsink}). If you supply a sink function, -it will be called when the FitsChan is deleted in order to write out -any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note, -the sink function is not called if the SinkFile attribute has been set. -\end{enumerate} - -Note, in particular, that reading an AST Object from a FitsChan is -\emph{destructive}. That is, it deletes the FITS cards that describe the -Object. The reason for this is explained in -\secref{ss:destructiveread}. - -In addition to the above, you may also read individual cards from a -FitsChan using the function \htmlref{astFindFits}{astFindFits} (which is not -destructive). This is the main means of writing out FITS cards if you -have not supplied a sink function. astFindFits also provides a means -of searching for particular FITS cards (by keyword, for example) and -there are other facilities for overwriting cards when required -(\secref{ss:findingandchangingfits}). - -\subsection{\label{ss:creatingafitschan}Creating a FitsChan} - -The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{astFitsChan}{astFitsChan}, is straightforward to -use: - -\small -\begin{terminalv} -#include "ast.h" -AstFitsChan *fitschan; - -... - -fitschan = astFitsChan( NULL, NULL, "Encoding=NATIVE" ); -\end{terminalv} -\normalsize - -Here, we have omitted any source or sink functions by supplying NULL -pointers for the first two arguments. -We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to -NATIVE. This indicates that we will be using the native encoding -(\secref{ss:nativeencoding}) to store and retrieve Objects. If this -was left unspecified, the default would depend on the FitsChan's -contents. An attempt is made to use whatever encoding appears to have -been used previously. For an empty FitsChan, the default is NATIVE, -but it does no harm to be sure. - -\subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan} - -Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a -mechanism is needed for addressing them. This allows you to specify -where new cards are to be added, for example, or which card is to be -deleted. - -This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which -gives the index of the \emph{current card} in the FitsChan. You can -nominate any card you like to be current, simply by setting a new -value for the Card attribute, for example: - -\small -\begin{terminalv} -int icard; - -... - -astSetI( fitschan, "Card", icard ) -\end{terminalv} -\normalsize - -where ``icard'' contains the index of the card on which you wish to -operate next. Some functions will update the Card attribute as a -means of advancing through the sequence of cards, when reading them -for example, or to indicate which card matches a search criterion. - -The default value for Card is one, which is the index of the first -card. This means that you can ``rewind'' a FitsChan to access its -first card by clearing the Card attribute: - -\small -\begin{terminalv} -astClear( fitschan, "Card" ); -\end{terminalv} -\normalsize - -The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard} -attribute. This is a read-only attribute whose value is automatically -updated as you add or remove cards. It means you can address all the -cards in sequence using a loop such as the following: - -\small -\begin{terminalv} -int ncard; - -... - -ncard = astGetI( fitschan, "Ncard" ); -for ( icard = 1; icard <= ncard; icard++ ) { - astSetI( fitschan, "Card", icard ); - <access the current card> -} -\end{terminalv} -\normalsize - -However, it is usually possible to write slightly tidier loops based -on the \htmlref{astFindFits}{astFindFits} function described later -(\secref{ss:extractingfitscards} and -\secref{ss:findingandchangingfits}). - -If you set the Card attribute to a value larger than Ncard, the -FitsChan is regarded as being positioned at its \emph{end-of-file}. In -this case there is no current card and an attempt to obtain a value -for the Card attribute will always return the value Ncard~$+$~1. When -a FitsChan is empty, it is always at the end-of-file. - -\subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan} - -Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you -can write any AST \htmlref{Object}{Object} to it in the native encoding using the -\htmlref{astWrite}{astWrite} function. Let us assume we are writing a -\htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet}, -but for purposes of illustration a SkyFrame contains a more manageable -amount of data.} as follows: - -\small -\begin{terminalv} -AstSkyFrame *skyframe; -int nobj; - -... - -nobj = astWrite( fitschan, skyframe ); -\end{terminalv} -\normalsize - -Since we have selected the native encoding -(\secref{ss:nativeencoding}), there are no restrictions on the class -of Object we may write, so astWrite should always return a value of -one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel} -(\secref{ss:writingtoachannel}), this write operation will not produce -any output from our program. The FITS headers produced are simply -stored inside the FitsChan. - -After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to -reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card} -attribute will point at the card immediately after the last one -written. Since our FitsChan was initially empty, the Card attribute -will, in this example, point at the end-of-file -(\secref{ss:addressingfitscards}). - -The FITS standard imposes a limit of 68 characters on the length of -strings which may be stored in a single header card. Sometimes, a -description of an AST Object involves the use of strings which exceed -this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If -this occurs, the long string will be split over two or more header cards. -Each ``continuation'' card will have the keyword \texttt{CONTINUE} in -columns 1 to 8, and will contain a space in column 9 (instead of the -usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of -each of the strings (except the last one) to indicate that the string is -continued on the next card. - -Note, this splitting of long strings over several cards only occurs when -writing AST Objects to a FitsChan using the astWrite function and the -\emph{native} encoding. If a long string is stored in a FitsChan using -(for instance) the \htmlref{astPutFits}{astPutFits} or \htmlref{astPutCards}{astPutCards} function, it will simply be truncated. - - -\subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan} - -To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame} -above (\secref{ss:writingnativefits}), we must write a simple loop to -extract each card in turn and print it out. We must also remember to -rewind the FitsChan first, \emph{e.g.}\ using \htmlref{astClear}{astClear}. The following -loop would do: - -\small -\begin{terminalv} -#include <stdio.h> -char card[ 81 ]; - -... - -astClear( fitschan, "Card" ); -while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); -\end{terminalv} -\normalsize - -Here, we have used the \htmlref{astFindFits}{astFindFits} function to find a FITS card by -keyword. It is given a keyword template of ``\%f'', which matches any -FITS keyword, so it always finds the current card, which it -returns. Its fourth argument is set to 1, to indicate that the \htmlref{Card}{Card} -attribute should be incremented afterwards so that the following card -will be found the next time around the loop. astFindFits returns zero -when it reaches the end-of-file and this terminates the loop. - -If we were storing the FITS headers in an output FITS file instead of -printing them out, we might use a loop like this but replace -``printf'' with a suitable data storage operation. This would only be -necessary if we had not provided a sink function for the FitsChan -(\secref{ss:fitssourceandsink}). - -\subsection{The Native FitsChan Output Format} - -If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote -earlier (\secref{ss:writingnativefits}), we should obtain something -like the following: - -\small -\begin{terminalv} -COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST -COMMENT AST Beginning of AST data for SkyFrame object AST -COMMENT AST ................................................................ AST -BEGAST_A= 'SkyFrame' / Description of celestial coordinate system -NAXES_A = 2 / Number of coordinate axes -AX1_A = ' ' / Axis number 1 -BEGAST_B= 'SkyAxis ' / Celestial coordinate axis -ENDAST_A= 'SkyAxis ' / End of object definition -AX2_A = ' ' / Axis number 2 -BEGAST_C= 'SkyAxis ' / Celestial coordinate axis -ENDAST_B= 'SkyAxis ' / End of object definition -ISA_A = 'Frame ' / Coordinate system description -SYSTEM_A= 'FK4-NO-E' / Celestial coordinate system type -EPOCH_A = 1958.0 / Besselian epoch of observation -ENDAST_C= 'SkyFrame' / End of object definition -COMMENT AST ................................................................ AST -COMMENT AST End of AST data for SkyFrame object AST -COMMENT AST ---------------------------------------------------------------- AST -\end{terminalv} -\normalsize - -As you can see, this resembles the information that would be written -to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame -(\secref{ss:textualoutputformat}), except that it has been formatted -into 80-character header cards according to FITS conventions. - -There are also a number of other differences worth noting: - -\begin{enumerate} -\item There is no unnecessary information about default values -provided for the benefit of the human reader. This is because the \htmlref{Full}{Full} -attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this -information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You -can restore the information if you wish by setting Full to 0 or $+$1, -in which case additional COMMENT cards will be generated to hold it. - -\item The information is not indented, because FITS does not allow -this. However, if you change the Full attribute to 0 or $+$1, comments -will be included that are intended to help break up the sequence of -headers and highlight its structure. This will probably only be of use -if you are attempting to track down a problem by examining the FITS -cards produced in detail. - -\item The FITS keywords which appear to the left of the ``$=$'' signs -have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to -them. This is done in order to make each keyword unique. -\end{enumerate} - -This last point is worth further comment and is necessary because the -FITS standard only allows for certain keywords (such as COMMENT and -HISTORY) to appear more than once. \htmlref{astWrite}{astWrite} therefore appends an -arbitrary sequence of two characters to each new keyword it generates -in order to ensure that it does not duplicate any already present in -the FitsChan. - -The main risk from not following this convention is that some software -might ignore (say) all but the last occurrence of a keyword before -passing the FITS headers on. Such an event is unlikely, but would -obviously destroy the information present, so astWrite enforces the -uniqueness of the keywords it uses. The extra characters added are -ignored when the information is read back. - -As with a basic Channel, you can also suppress the comments produced -in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to -zero (\secref{ss:channelcommenting}). However, FITS headers are -traditionally generously commented, so this is not recommended. - -\subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan} - -To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back -as Objects for example, you should use the \htmlref{astPutFits}{astPutFits} function. You -can insert a card in front of the current one as follows: - -\small -\begin{terminalv} -astPutFits( fitschan, card, 0 ); -\end{terminalv} -\normalsize - -where the third argument of zero indicates that the current card -should not be overwritten. Note that facilities are not provided by -AST for formatting the card contents. - -After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the -original Card, or at the end-of-file if the FitsChan was originally -empty. Entering a sequence of cards is therefore straightforward. If -``cards'' is an array of pointers to strings containing FITS header -cards and ``ncards'' is the number of cards, then a loop such as the -following will insert the cards in sequence into a FitsChan: - -\small -\begin{terminalv} -#define MAXCARD 100 -char *cards[ MAXCARD ]; -int ncard; - -... - -for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); -\end{terminalv} -\normalsize - -The string containing a card need not be null terminated if it is at -least 80 characters long (we have not allocated space for the strings -themselves in this brief example). - -Note that astPutFits enforces the validity of a FitsChan by rejecting -any cards which do not adhere to the FITS standard. If any such cards -are detected, an error will result. - -\subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan} - -If you have all your cards concatenated together into a single long string, -each occupying 80 characters (with no delimiters), you can insert them -into a \htmlref{FitsChan}{FitsChan} in a single call using -\htmlref{astPutCards}{astPutCards}. -This call first empties the supplied FitsChan of any existing cards, then -inserts the new cards, and finally rewinds the FitsChan so that a -subsequent call to -\htmlref{astRead}{astRead} -will start reading from the first supplied card. The -astPutCards function uses \htmlref{astPutFits}{astPutFits} -internally to interpret and store each individual card, and so the -caveats in \secref{ss:addingfitscards} should be read. - -For instance, if you are using the CFITSIO library for access to FITS -files, you can use the CFITSIO fits\_hdr2str function to obtain a string suitable -for passing to astPutCards: - -\small -\begin{terminalv} - - -if( !fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) ) - fitschan = astFitsChan( NULL, NULL, "" ); - astPutCards( fitschan, header ); - header = free( header ); - wcsinfo = astRead( fitschan ); - - ... -} -\end{terminalv} -\normalsize - - - -\subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan} - -Once you have stored a FITS header description of an \htmlref{Object}{Object} in a -\htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}), -you can read it back using \htmlref{astRead}{astRead} in much the same way as with a -basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments -about validating the Object you read also apply -(\secref{ss:validatinginput}). If you have just written to the -FitsChan, you must remember to rewind it first: - -\small -\begin{terminalv} -AstObject *object; - -... - -astClear( fitschan, "Card" ); -object = astRead( fitschan ); -\end{terminalv} -\normalsize - -An important feature of a FitsChan is that read operations are -destructive. This means that if an Object description is found, it -will be consumed by astRead which will remove all the cards involved, -including associated COMMENT cards, from the FitsChan. Thus, if you -write an Object to a FitsChan, rewind, and read the same Object back, -you should end up with the original FitsChan contents. If you need to -circumvent this behaviour for any reason, it is a simple matter to -make a copy of a FitsChan using \htmlref{astCopy}{astCopy} -(\secref{ss:copyingobjects}). If you then read from the copy, the -original FitsChan will remain untouched. - -After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the -card immediately following the last card read, or the end-of-file of -there are no more cards. - -Since the \emph{native} encoding is being used, any long strings involved -in the object description will have been split into two or more adjacent -contuation cards when the Object was stored in the header using function -\htmlref{astWrite}{astWrite}. The astRead function reverses this process by concatenating any -such adjacent continuation cards to re-create the original long string. - - -\subsection{Saving and Restoring Multiple Objects in a FitsChan} - -When using the native FITS encoding, multiple Objects may be stored -and all I/O operations are sequential. This means that you can simply -write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation, -the \htmlref{Card}{Card} attribute will be updated so that the next write appends the -next \htmlref{Object}{Object} description to the previous one. - -If you then rewind the FitsChan, you can read the Objects back in the -original order. Reading them back will, of course, remove their -descriptions from the FitsChan (\secref{ss:readingnativefits}) but the -behaviour of the Card attribute is such that successive reads will -simply return each Object in sequence. - -The only thing that may require care, given that a FitsChan can always -be addressed randomly by setting its Card attribute, is to avoid -writing one Object on top of another. For obvious reasons, the Object -descriptions in a FitsChan must remain separate if they are to make -sense when read back. - -\subsection{Mixing Native Objects with Other FITS Cards} - -Of course, any real FITS header will contain other information besides -AST Objects, if only the mandatory FITS cards that must accompany all -FITS data. When FITS headers are read in from a real dataset, -therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with -many other cards. - -Because this is the normal state of affairs, the boolean (integer) -\htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when -you read an Object From a FitsChan, any irrelevant cards will simply -be skipped over until the start of the next Object description, if -any, is found. If you start reading part way through an Object -description, no error will result. The remainder of the description -will simply be skipped. - -Setting Skip to zero will change this behaviour to resemble that of a -basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data -are not permitted by default, but this will probably rarely be useful. - -\subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan} - -You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by -keyword, using the function \htmlref{astFindFits}{astFindFits}. This performs a search, -starting at the current card, until it finds a card whose keyword -matches the template you supply, or the end-of-file is reached. - -If a suitable card is found, astFindFits optionally returns the card's -contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to -identify the card found, or the one following it. The way you want the -Card attribute to be set is indicated by the final boolean (int) -argument to astFindFits. A value of one is returned to indicate -success. If a suitable card cannot be found, astFindFits returns a -value of zero to indicate failure and sets the FitsChan's Card -attribute to the end-of-file. - -Requesting that the Card attribute be set to indicate the card that -astFindFits finds is useful if you want to replace that card with a -new one, as in this example: - -\small -\begin{terminalv} -char newcard[ 81 ]; - -... - -(void) astFindFits( fitschan, "AIRMASS", NULL, 0 ); -astPutFits( fitschan, newcard, 1 ); -\end{terminalv} -\normalsize - -Here, astFindFits is used to search for a card with the keyword -AIRMASS, with a NULL pointer being given to indicate that we do not -want the card's contents returned. If the card is found, \htmlref{astPutFits}{astPutFits} -then overwrites it with a new card. Otherwise, the Card attribute -ends up pointing at the end-of-file and the new card is simply -appended to the end of the FitsChan. - -A similar approach can be used to delete selected cards from a -FitsChan using \htmlref{astDelFits}{astDelFits}, which deletes the current card: - -\small -\begin{terminalv} -if ( astFindFits( fitschan, "BSCALE", NULL, 0 ) ) astDelFits( fitschan ); -\end{terminalv} -\normalsize - -This deletes the first card, if any, with the BSCALE keyword. - -Requesting that astFindFits increments the Card attribute to identify -the card following the one found is more useful when writing loops. -For example, the following loop extracts each card whose keyword -matches the template ``CD\%6d'' (that is, ``CD'' followed by six -decimal digits): - -\small -\begin{terminalv} -while ( astFindFits( fitschan, "CD%6d", card, 1 ) { - <process the card's contents> -} -\end{terminalv} -\normalsize - -For further details of keyword templates, see the description of -astFindFits in \appref{ss:functiondescriptions}. - -\subsection{\label{ss:fitssourceandsink}Source and Sink Functions for FitsChans} - -The use of source and sink functions with a \htmlref{FitsChan}{FitsChan} is optional. This -is because you can always arrange to explicitly fill a FitsChan with -FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards}) -and you can also extract any -cards that remain and write them out yourself -(\secref{ss:extractingfitscards}) before you delete the FitsChan. - -If you choose to use these functions, however, they behave in a very -similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource} -and \secref{ss:channelsink}). You supply pointers to these functions, -as arguments to the constructor function \htmlref{astFitsChan}{astFitsChan} when you create -the FitsChan (\secref{ss:creatingafitschan}). The source function is -invoked implicitly at this point to fill the FitsChan with FITS cards -and the FitsChan is then rewound, so that the first card becomes -current. The sink function is automatically invoked later, when the -FitsChan is deleted, in order to write out any cards that remain in -it. - -The only real difference between the source and sink functions for a -FitsChan and a basic Channel is that FITS cards are limited in length -to 80~characters, so the choice of buffer size is simplified. The -``Source'' and ``Sink'' functions in \secref{ss:channelsource} and -\secref{ss:channelsink} could therefore be used to access FITS headers -stored in text files simply by changing LEN to be 80. If you were not -accessing a text file, however, appropriate changes to the I/O -statements would be needed since the separating newline characters -would be absent. The details obviously depend on the format of the -file you are handling, which need not necessarily be a true FITS file. - - -\cleardoublepage -\section{\label{ss:foreignfits}Using Foreign FITS Encodings} - -We saw in the previous section (\secref{ss:nativefits}) how to store -and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a -\htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to -NATIVE. However, the Objects we wrote could then only be read back by -other programs that use AST. - -In practice, we will also encounter FITS headers containing WCS -information written by other software systems. We will probably also -need to write FITS headers in a format that can be understood by these -systems. Indeed, this interchange of data is one of the main reasons -for the existence of FITS, so in this section we will examine how to -accommodate these requirements. - -\subsection{\label{ss:foreignencodings}The Foreign FITS Encodings} - -As mentioned previously (\secref{ss:nativeencoding}), there are a -number of conventions currently in use for storing WCS information in -FITS headers, which we call \emph{encodings}. Here, we are concerned -with those encodings defined by software systems other than AST, which -we term \emph{foreign encodings}. - -Currently, AST supports six foreign encodings, which may be selected -by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the -following (character string) values: - -\begin{quote} -\begin{description} -\item[DSS]\mbox{}\\ -This encoding stores WCS information using the convention developed at -the Space Telescope Science Institute for the Digitised Sky Survey -(DSS) astrometric plate calibrations. DSS images which use this -convention are widely available and it is understood by a number of -important and well-established astronomy applications. - -However, the calibration model used (based on a polynomial fit) is not -easily applicable to other types of data and creating the polynomial -coefficients needed to calibrate your own images can prove -difficult. For this reason, the DSS encoding is probably best viewed -as a ``read-only'' format. It is possible, however, to read in WCS -information using this encoding and then to write it back out again, -so long as only minor changes have been made. - -\item[FITS-WCS]\mbox{}\\ -This encoding is very important because it is based on a new FITS standard -which should, for the first time, address the problem of celestial coordinate -systems in a proper manner, by considerably extending the original FITS -standard. - -The conventions used are described in a series of papers by -E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the -``FITS-WCS papers''. They are described at -\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers -in this series have been agreed, this encoding should be understood by any -FITS-WCS compliant software and it is likely to be adopted widely for FITS -data in future. For details of the coverage of these conventions provided -by the FitsChan class, see \appref{ss:fitswcscoverage}. - -\item[FITS-IRAF]\mbox{}\\ -This encoding is based on the conventions described in the document -``World Coordinate Systems Representations Within the FITS Format'' by R.J. -Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from -fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed -by the IRAF data analysis facility, so its use will facilitate data -exchange with IRAF. This encoding is in effect a sub-set of the current -FITS-WCS encoding. - -\item[FITS-PC]\mbox{}\\ -This encoding is based on a previous version of the proposed new FITS WCS -standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe -axis rotation and scaling. Versions of AST prior to V1.5 used this scheme -for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j} -keywords instead.\footnote{There are many other differences between the -previous and the current FITS-WCS encodings. The keywords to describe -axis rotation and scaling is used purely as a label to identify the -scheme.} The FITS-PC encoding is included in AST V1.5 only to allow -FITS-WCS data created with previous versions to be read. It should not, -in general, be used to create new data sets. - -\item[FITS-AIPS]\mbox{}\\ -This encoding is based on the conventions described in the document -``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th -September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu -/fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS -data analysis facility, so its use will facilitate data exchange with -AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to -describe axis rotation and scaling. - -\item[FITS-AIPS++]\mbox{}\\ -Encodes coordinate system information in FITS -header cards using the conventions used by the AIPS++ project. -This is an extension of FITS-AIPS which includes some of the -features of FITS-PC and FITS-IRAF. -\end{description} -\end{quote} - -For more detail about the above encodings, see the description of the -Encoding attribute in \appref{ss:attributedescriptions}. - -\subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings} - -The foreign encodings available for storing WCS information in FITS -headers have a number of limitations when compared with the native -encoding of AST Objects (\secref{ss:nativefits}). The main ones are: - -\begin{enumerate} -\item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented -using a foreign FITS encoding. This should not come as a surprise, -because the purpose of storing WCS information in FITS headers is to -attach coordinate systems to an associated array of data. Since the -FrameSet is the AST Object designed for the same purpose -(\secref{ss:baseandcurrent}), there is a natural correspondence. - -The way in which a FrameSet is translated to and from the foreign -encoding also follows from this correspondence. The FrameSet's base -\htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS -data. These are the same as FITS pixel coordinates, in which the first -pixel (in 2 dimensions) has coordinates (1,1) at its -centre. Similarly, the current Frame of the FrameSet identifies the -FITS world coordinate system associated with the data. - -\item You may store a representation of only a single FrameSet in any -individual set of FITS header cards (\emph{i.e.}\ in a single -\htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may -over-write the previous one or generate an invalid representation of -your WCS information. - -This is mainly a consequence of the use of fixed FITS keywords by -foreign encodings and the fact that you cannot, in general, have -multiple FITS cards with the same keyword. - -\item In general, it will not be possible to store every possible -FrameSet that you might construct. Depending on the encoding, only -certain FrameSets that conform to particular restrictions can be -represented and, even then, some of their information may be lost. See -the description of the \htmlref{Encoding}{Encoding} attribute in -\appref{ss:attributedescriptions} for more details of these -limitations. -\end{enumerate} - -It should be understood that using foreign encodings to read and write -information held in AST Objects is essentially a process of converting -the data format. As such, it potentially suffers from the same -problems faced by all such processes, \emph{i.e.}\ differences between -the AST data model and that of the foreign encoding may cause some -information to be lost. Because the AST model is extremely flexible, -however, any data loss can largely be eliminated when reading. -Instead, this effect manifests itself in the form of the above -encoding-dependent restrictions on the kind of AST Objects which may -be written. - -One of the aims of the AST library, of course, is to insulate you from -the details of these foreign encodings and the restrictions they -impose. We will see shortly, therefore, how AST provides a mechanism -for determining whether your WCS information satisfies the necessary -conditions and allows you to make an automatic choice of which -encoding to use. - -\subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input} - -Let us now examine the practicalities of extracting WCS information -from a set of FITS header cards which have been written by some other -software system. We will pretend that our program does not know which -encoding has been used for the WCS information and must discover this -for itself. In order to have a concrete example, however, we will use -the following set of cards. These use the FITS-AIPS encoding and -contain a typical mix of other FITS cards which are irrelevant to the -WCS information in which we are interested: - -\small -\begin{terminalv} -SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 -BITPIX = -32 / Bits per pixel. -NAXIS = 2 / Number of dimensions -NAXIS1 = 300 / Length of x axis. -NAXIS2 = 300 / Length of y axis. -CTYPE1 = 'GLON-ZEA' / X-axis type -CTYPE2 = 'GLAT-ZEA' / Y-axis type -CRVAL1 = -149.56866 / Reference pixel value -CRVAL2 = -19.758201 / Reference pixel value -CRPIX1 = 150.500 / Reference pixel -CRPIX2 = 150.500 / Reference pixel -CDELT1 = -1.20000 / Degrees/pixel -CDELT2 = 1.20000 / Degrees/pixel -CROTA1 = 0.00000 / Rotation in degrees. -SURVEY = 'COBE DIRBE' -BUNITS = 'MJy/sr ' / -ORIGIN = 'CDAC ' / Cosmology Data Analysis Center -TELESCOP= 'COBE ' / COsmic Background Explorer satellite -INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] -PIXRESOL= 9 / Quad tree pixel resolution [6, 9] -DATE = '27/09/94' / FITS file creation date (dd/mm/yy) -DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) -COMMENT COBE specific keywords -DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) -DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) -\end{terminalv} -\normalsize - -The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into -it. If ``cards'' is an array of pointers to character strings holding -the header cards and ``ncards'' is the number of cards, this could be -done as follows: - -\small -\begin{terminalv} -#include "ast.h" -#define MAXCARD 100 -AstFitsChan *fitschan; -char *cards[ MAXCARD ]; -int icard, ncard; - -... - -fitschan = astFitsChan( NULL, NULL, "" ); -for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 ); -\end{terminalv} -\normalsize - -Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the -FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to -use the native encoding. This is because we are pretending not to know -which encoding to use and want AST to determine this for us. By -leaving the Encoding attribute un-set, its default value will adjust -to whichever encoding AST considers to be most appropriate, according -to the FITS header cards present. For details of how this choice is -made, see the description of the Encoding attribute in -\appref{ss:attributedescriptions}. - -This approach has the obvious advantages of making our program simpler -and more flexible and of freeing us from having to know about the -different encodings available. As a bonus, it also means that the -program will be able to read any new encodings that AST may support in -future, without needing to be changed. - -At this point, we could enquire the default value of the Encoding -attribute, which indicates which encoding AST intends to use, as -follows: - -\small -\begin{terminalv} -const char *encode; - -... - - -encode = astGetC( fitschan, "Encoding" ); -\end{terminalv} -\normalsize - -The result of this enquiry would be the string ``FITS-AIPS''. Note -that we could also have set the FitsChan's Encoding attribute -explicitly, such as when creating it: - -\small -\begin{terminalv} -fitschan = astFitsChan( NULL, NULL, "Encoding=FITS-AIPS" ); -\end{terminalv} -\normalsize - -If we tried to read information using this encoding -(\secref{ss:readingforeignfits}), but failed, we could then change the -encoding and try again. This would allow our program to take control -of how the optimum choice of encoding is arrived at. However, it would -also involve using explicit knowledge of the encodings available and -this is best avoided if possible. - -\subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header} - -Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined -how the WCS information is encoded -(\secref{ss:identifyingfitsencoding}), the next step is to read an AST -\htmlref{Object}{Object} from the FitsChan using \htmlref{astRead}{astRead}. We must also remember to -rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card} -attribute, which defaults to 1: - -\small -\begin{terminalv} -AstObject *wcsinfo; - -... - -astClear( fitschan, "Card" ); -wcsinfo = astRead( fitschan ); -\end{terminalv} -\normalsize - -If the pointer returned by astRead is not equal to AST\_\_NULL, then -an Object has been read successfully. Otherwise, there was either no -information to read or the choice of FITS encoding -(\secref{ss:identifyingfitsencoding}) was inappropriate. - -At this point you might like to indulge in a little data validation -along the lines described in \secref{ss:validatinginput}, for example: - -\small -\begin{terminalv} -if ( !strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) { - <the Object is a FrameSet, so use it> -} else { - <something unexpected was read> -} -\end{terminalv} -\normalsize - -If a foreign encoding has definitely been used, then the Object will -automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so -this stage can be omitted. However, if the native encoding -(\secref{ss:nativeencoding}) might have been employed, which is a -possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then -any class of Object might have been read and a quick check would be -worthwhile. - -If you used \htmlref{astShow}{astShow} (\secref{ss:displayingobjects}) to examine the -FrameSet which results from reading our example FITS header -(\secref{ss:identifyingfitsencoding}), you would find that its base -\htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its -current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These -two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which -incorporates the effects of various rotations, scalings and a -``zenithal equal area'' sky projection, so that each pixel of the FITS -image is mapped on to a corresponding sky position in galactic -coordinates. - -Because this FrameSet may be used both as a Mapping -(\secref{ss:framesetasmapping}) and as a Frame -(\secref{ss:framesetasframe}), it may be employed directly to perform -many useful operations without any need to decompose it into its -component parts. These include: - -\begin{itemize} -\item Transforming data grid (FITS pixel) coordinates into galactic -coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}). - -\item Formatting coordinate values (either pixel or galactic -coordinates) ready for display to a user -(\secref{ss:formattingaxisvalues} and \secref{ss:normalising}). - -\item Enquiring about axis labels (or other axis -information---\secref{ss:frameattributes}) which might be used, for -example, to label columns of coordinates in a table -(\secref{ss:frameaxisattributes}). - -\item Aligning the image with another image from which a similar -FrameSet has been obtained (\secref{ss:registeringimages}). - -\item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay -a variety of graphical information (including a coordinate -grid---Figure~\ref{fig:gridplot}) on the displayed image. - -\item Generating a new FrameSet which reflects any geometrical -processing you perform on the associated image data -(\secref{ss:wcsprocessingexample}). This new FrameSet could then be -written out as FITS headers to describe the modified image -(\secref{ss:writingforeignfits}). -\end{itemize} - -If the FrameSet contains other Frames (apart from the base and current -Frames), then you would also have access to information about other -coordinate systems associated with the image. - -\subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read} - -It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan} -after we have read a \htmlref{FrameSet}{FrameSet} from it -(\secref{ss:readingforeignfits}). The following would rewind our -FitsChan and display its contents: - -\small -\begin{terminalv} -#include <stdio.h> -char card[ 81 ]; - -... - -astClear( fitschan, "Card" ); -while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card ); -\end{terminalv} -\normalsize - -The output, if we started with the example FITS header in -\secref{ss:identifyingfitsencoding}, might look like this: - -\small -\begin{terminalv} -SIMPLE = T / Written by IDL: 30-Jul-1997 05:35:42.00 -BITPIX = -32 / Bits per pixel. -NAXIS = 2 / Number of dimensions -NAXIS1 = 300 / Length of x axis. -NAXIS2 = 300 / Length of y axis. -SURVEY = 'COBE DIRBE' -BUNITS = 'MJy/sr ' -ORIGIN = 'CDAC ' / Cosmology Data Analysis Center -TELESCOP= 'COBE ' / COsmic Background Explorer satellite -INSTRUME= 'DIRBE ' / COBE instrument [DIRBE, DMR, FIRAS] -PIXRESOL= 9 / Quad tree pixel resolution [6, 9] -DATE = '27/09/94' / FITS file creation date (dd/mm/yy) -DATE-MAP= '16/09/94' / Date of original file creation (dd/mm/yy) -COMMENT COBE specific keywords -DATE-BEG= '08/12/89' / date of initial data represented (dd/mm/yy) -DATE-END= '25/09/90' / date of final data represented (dd/mm/yy) -\end{terminalv} -\normalsize - -Comparing this with the original, you can see that all the FITS cards -that represent WCS information have been removed. They have -effectively been ``sucked out'' of the FitsChan by the destructive -read that \htmlref{astRead}{astRead} performs and converted into an equivalent -FrameSet. AST remembers where they were stored, however, so that if we -later write WCS information back into the FitsChan -(\secref{ss:writingforeignfits}) they will, as far as possible, go -back into their original locations. This helps to preserve the overall -layout of the FITS header. - -You can now see why astRead performs destructive reads. It is a -mechanism for removing WCS information from a FITS header while -insulating you, as a programmer, from the details of the encoding -being used. It means you can ensure that all relevant header cards -have been removed, giving you a clean slate, without having to know -which FITS keywords any particular encoding uses. - -Clearing this WCS information out of a FITS header is particularly -important when considering how to write new WCS information back after -processing (\secref{ss:writingforeignfits}). If any relevant FITS -cards are left over from the input dataset and find their way into the -new processed header, they could interfere with the new information -being written.\footnote{This can happen if a particular keyword is -present in the input header but is not used in the output header -(whether particular keywords are used can depend on the WCS -information being stored). In such a case, the original value would -not be over-written by a new output value, so would remain erroneously -present.} The destructive read mechanism ensures that this doesn't -happen. - -\subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps} - -One of the purposes of AST is to make it feasible to propagate WCS -information through successive stages of data processing, so that it -remains consistent with the associated image data. As far as possible, -this should happen regardless of the FITS encoding used to store the -original WCS information. - -If the data processing being performed does not change the -relationship between image pixel and world coordinates (whatever these -may be), then propagation of the WCS information is -straightforward. You can simply copy the FITS header from input to -output. - -If this relationship changes, however, then the WCS information must -be processed alongside the image data and a new FITS header generated -to represent it. In this case, the sequence of operations within your -program would probably be as follows: - -\begin{enumerate} -\item Read the image data and associated FITS header from the input -dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan} -(\secref{ss:identifyingfitsencoding}). - -\item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically -using a foreign FITS encoding---\secref{ss:readingforeignfits}). - -\item Process the image data and modify the FrameSet accordingly -(\emph{e.g.}~\secref{ss:wcsprocessingexample}). - -\item Write the FrameSet back into the FitsChan -(\secref{ss:writingforeignfits}). - -\item Perform any other modification of FITS header cards your program -may require. - -\item Write the FitsChan contents (\emph{i.e.}\ processed header -cards) and image data to the output dataset. -\end{enumerate} - -In stage (2), the original WCS information will be removed from the -FitsChan by a destructive read. Later, in stage (4), new WCS -information is written to replace it. This is the process which we -consider next (\secref{ss:writingforeignfits}). - -\subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header} - -Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back -into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS -encoding to use. Unfortunately, we cannot simply depend on the -default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the -input information (\secref{ss:identifyingfitsencoding}), because the -destructive action of reading the WCS data -(\secref{ss:destructiveread}) will have altered the FitsChan's -contents. This, in turn, will have changed the choice of default -encoding, probably causing it to revert to NATIVE. - -We will return to the question of the optimum choice of encoding -below. For now, let's assume that we want to use the same encoding -for output as we used for input. Since we enquired what that was -before we read the input WCS data from the FitsChan -(\secref{ss:identifyingfitsencoding}), we can now set that value -explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at -the same time (because the write will fail if the FitsChan is not -rewound). \htmlref{astWrite}{astWrite} can then be used to write the output WCS -information into the FitsChan: - -\small -\begin{terminalv} -int nobj; - -... - -astSet( fitschan, "Card=1, Encoding=%s", encode ); -nobj = astWrite( fitschan, wcsinfo ); -\end{terminalv} -\normalsize - -The value returned by astWrite (assigned to ``nobj'') indicates how -many Objects were written. This will either be 1 or zero. A value of -zero is used to indicate that the information could not be encoded in -the form you requested. If this happens, nothing will have been -written. - -If your choice of encoding proves inadequate, the probable reason is -that the changes you have made to the FrameSet have caused it to -depart from the data model which the encoding assumes. AST knows -about the data model used by each encoding and will attempt to -simplify the FrameSet you provide so as to fit into that model, thus -relieving you of the need to understand the details and limitations of -each encoding yourself.\footnote{Storing values in the FitsChan for -FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels), -before invoking -astWrite -can sometimes help to produce a successful write.} When this attempt fails, -however, you must consider what alternative encoding to use. - -Ideally, you would probably want to try a sequence of alternative -encodings, using an approach such as the following: - -\small -\begin{terminalv} -/* 1. */ -astSet( fitschan, "Card=1, Encoding=FITS-IRAF" ); -if ( !astWrite( fitschan, wcsinfo ) ) { - -/* 2. */ - astSetC( fitschan, "Encoding", encode ); - if ( !astWrite( fitschan, wcsinfo ) ) { - -/* 3. */ - astSet( fitschan, "Encoding=NATIVE" ); - (void) astWrite( fitschan, wcsinfo ); - } -} -\end{terminalv} -\normalsize - -That is: - -\begin{enumerate} -\item Start by trying the FITS-WCS encoding, on the grounds that FITS -should provide a universal interchange standard in which all WCS -information should be expressed if possible. - -\item If that fails, then try the original encoding used for the input -WCS information, on the grounds that you are at least not making the -information any harder for others to read than it originally was. - -\item If that also fails, then you are probably trying to store fairly -complex information for which you need the native encoding. Only other -AST programs will then be able to read this information, but these are -probably the only programs that will be able to do anything sensible -with it anyway. -\end{enumerate} - -An alternative approach might be to encode the WCS information in several -ways, since this gives the maximum chance that other software will be -able to read it. This approach is only possible if there is no -significant conflict between the FITS keywords used by the different -encodings\footnote{In practice, this means you should avoid mixing -FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share -many keywords.}. Adopting this approach would simply require multiple -calls to astWrite, rewinding the FitsChan and changing its Encoding value -before each one. - -Unfortunately, however, there is a drawback to duplicating WCS -information in the FITS header in this way, because any program which -modifies one version of this information and simply copies the -remainder of the header will risk producing two inconsistent sets of -information. This could obviously be confusing to subsequent -software. Whether you consider this a worthwhile risk probably depends -on the use to which you expect your data to be put. - -\cleardoublepage -\section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)} - -\htmladdnormallinkfoot{XML}{http://www.w3.org/XML/} -is fast becoming the standard format for passing structured data around -the internet, and much general purpose software has been written for -tasks such as the parsing, editing, display and transformation of XML -data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides -facilities for storing AST objects externally in the form of XML documents, -thus allowing such software to be used. - -The primary XML format used by the XmlChan class is a fairly close -transliteration of the AST native format produced by the basic Channel -class. Currently, there is no DTD or schema defining the structure of data -produced in this format by an XmlChan. The following is a native AST -representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full} -attribute set to zero so that some default attribute values are included -as extra comments): - -\small -\begin{terminalv} - Begin Frame # Coordinate system description -# Title = "1-d coordinate system" # Title of coordinate system - Naxes = 1 # Number of coordinate axes - Domain = "SCREEN" # Coordinate system domain -# Lbl1 = "Axis 1" # Label for axis 1 -# Uni1 = "cm" # Units for axis 1 - Ax1 = # Axis number 1 - Begin Axis # Coordinate axis - Unit = "cm" # Axis units - End Axis - End Frame -\end{terminalv} -\normalsize - -The corresponding XmlChan output would look like: - -\small -\begin{terminalv} - <Frame xmlns="http://www.starlink.ac.uk/ast/xml/" - desc="Coordinate system description"> - <_attribute name="Title" quoted="true" value="1-d coordinate system" - desc="Title of coordinate system" default="true"/> - <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/> - <_attribute name="Domain" quoted="true" value="SCREEN" - desc="Coordinate system domain"/> - <_attribute name="Lbl1" quoted="true" value="Axis 1" - desc="Label for axis 1" default="true"/> - <_attribute name="Uni1" quoted="true" value="cm" - desc="Units for axis 1" default="true"/> - <Axis label="Ax1" desc="Coordinate axis"> - <!--Axis number 1--> - <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/> - </Axis> - </Frame> -\end{terminalv} -\normalsize - - -Notes: - -\begin{enumerate} -\item The AST class name is used as the name for an XML element which contain -a description of an AST object. - -\item AST attributes are described by XML elements with the name -``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML -to refer to a ``name=value'' pair within an element start tag. So for -instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described -within an XML element with name ``\_attribute'' in which the XML attribute -``name'' has the value ``Title'', and the XML attribute ``value'' has the -value ``1-d coordinate system''. The moral is always to be clear clear -about the context (AST or XML) in which the word \emph{attribute} is being -used! - -\item The XML includes comments both as XML attributes with the name ``desc'', -and as separate comment tags. - -\item Elements which describe default values are identified by the fact -that they have an XML attribute called ``default'' set to the value -``true''. These elements are ignored when being read back into an XmlChan. - -\item The outer-most XML element of an AST object will set the default -namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be -inherited by all nested elements. - -\end{enumerate} - - -The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full -attributes (inherited from the base Channel class) to zero and -1, -resulting in terse output by default. With the default values for these -attributes, the above XML is reduced to the following: - -\small -\begin{terminalv} - <Frame xmlns="http://www.starlink.ac.uk/ast/xml/"> - <_attribute name="Naxes" value="1"/> - <_attribute name="Domain" quoted="true" value="SCREEN"/> - <Axis label="Ax1"> - <_attribute name="Unit" quoted="true" value="cm"/> - </Axis> - </Frame> -\end{terminalv} -\normalsize - - -The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel -class. If Skip is zero (the default) then an error will be reported if the text -supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If -Skip is non-zero, then initial text is skipped over without error until -the start of an AST object is found. this allows an AST object to be -located within a larger XML document. - -\subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions} -The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML -documents which use a restricted subset of an early draft (V1.20) of the -IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X -finally adopted by the IVOA differs in several significant respects from -V1.20, and so the STC-X support currently provided by AST is mainly of -historical interest. Note, AST also supports the alternative ``STC-S'' -linear string description of the STC model (see \secref{ss:stcschans}). - -STC-X V1.20 is documented at -\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current -version is documented at -\url{http://www.ivoa.net/Documents/latest/STC-X.html}. - -When an STC-X document is read using an XmlChan, the read operation -produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of -\htmlref{Region}{Region}. Specifically, each such Object will be an instance of -\htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or -\htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the -\htmlref{XmlFormat}{XmlFormat} attribute for further details. - -\cleardoublepage -\section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)} - -The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing -IVOA ``STC-S'' descriptions. STC-S (see -\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string -syntax that allows simple specification of the STC metadata describing a -region in an astronomical coordinate system. AST supports a -subset of the STC-S specification, allowing an STC-S description of a -region within an AST-supported astronomical coordinate system to be converted -into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further -details, see the full description of the StcsChan class in -\appref{ss:classdescriptions}. - - -\cleardoublepage -\section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)} - -\subsection{The Need for Extensibility} - -However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you -will want to transform coordinates in some way that has not been -foreseen. You might want to plot a graph in some novel curvilinear -coordinate system (perhaps you already have a WCS system in your -software and just want to use AST for its graphical capabilities). -Alternatively, you might need to calibrate a complex dataset (like an -objective prism plate) where each position must be converted to world -coordinates with reference to calibration data under the control of an -elaborate algorithm. - -In such cases, it is clear that the basic pre-formed components -provided by AST for building Mappings are just not enough. What you -need is access to a programming language. However, if you write your -own software to transform coordinate values, then it must be made -available in the form of an AST class (from which you can create -Objects) before it can be used in conjunction with other AST -facilities. - -At this point you might consider writing your own AST class, but this -is not recommended. Not only would the internal conventions used by -AST take some time to master, but you might also find yourself having -to change your software whenever a new version of AST was -released. Fortunately, there is a much easier route provided by the -\htmlref{IntraMap}{IntraMap} class. - -\subsection{The IntraMap Model} - -To allow you to write your own Mappings, AST provides a special kind -of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper'' -for a coordinate transformation function written in C. You write this -function yourself and then register it with AST. This, in effect, -creates a new class from which you can create Mappings -(\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever -way your transformation function specifies. - -Because IntraMaps are Mappings, they may be used in the same way as -any other Mapping. For instance, they may be combined in series or -parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}), -they may be inverted (\secref{ss:invertingmappings}), you may enquire -about their attributes (\secref{ss:gettingattributes}), they may be -inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do, -however, have some important limitations of which you should be aware -before we go on to consider how to create them. - -\subsection{\label{ss:intramaplimitations}Limitations of IntraMaps} - -By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is -required at all. After all, why not simply write your own coordinate -transformation functions in C, wrap them up in IntraMaps and do away -with all the other Mapping classes in AST? - -The reason is not too hard to find. Any transformation function you -write is created solely by you, so it is a private extension which -does not form a permanent part of AST. If you use it to calibrate some -data and then pass that data to someone else, who has only the -standard version of AST, then they will not be able to interpret it. - -Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators -(who we assume have access to the same transformation functions), it -does not address the need for universal data exchange like other AST -Mappings do. This is where the ``Intra'' in the class name -``IntraMap'' comes from, implying private or internal usage. - -For this reason, it is unwise to store IntraMaps in datasets, unless -they will be used solely for communication between collaborating items -of software which share conventions about their use. A private -database describing coordinate systems on a graphics device might be -an example where IntraMaps would be suitable, because the data would -probably never be accessed by anyone else's software. Restricting -IntraMap usage to within a single program (\emph{i.e.} never writing -it out) is, of course, completely safe. - -If, by accident, an IntraMap should happen to escape as part of a -dataset, then the unsuspecting recipient is likely to receive an error -message when they attempt to read the data. However, AST will -associate details of the IntraMap's transformation function and its -author (if provided) with the data, so that the recipient can make an -intelligent enquiry to obtain the necessary software if this proves -essential. - -\subsection{\label{ss:transformationfunctions}Writing a Transformation Function} - -The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate -transformation function. This should have a calling interface like the -\htmlref{astTranP}{astTranP} function provided by AST (\emph{q.v.}). Here is a simple -example of a suitable transformation function which transforms -coordinates by squaring them: -\xlabel{SqrTran} - -\small -\begin{terminalv} -#include "ast.h" -#include <math.h> - -void SqrTran( AstMapping *this, int npoint, int ncoord_in, - const double *ptr_in[], int forward, int ncoord_out, - double *ptr_out[] ) { - int point, coord; - double x; - -/* Forward transformation. */ - if ( forward ) { - for ( point = 0; point < npoint; point++ ) { - for ( coord = 0; coord < ncoord_in; coord++ ) { - x = ptr_in[ coord ][ point ]; - ptr_out[ coord ][ point ] = ( x == AST__BAD ) ? AST__BAD : x * x; - } - } - -/* Inverse transformation. */ - } else { - for ( point = 0; point < npoint; point++ ) { - for ( coord = 0; coord < ncoord_in; coord++ ) { - x = ptr_in[ coord ][ point ]; - ptr_out[ coord ][ point ] = - ( x < 0.0 || x == AST__BAD ) ? AST__BAD : sqrt( x ); - } - } - } -} -\end{terminalv} -\normalsize - -As you can see, the function comes in two halves which implement the -forward and inverse coordinate transformations. The number of points -to be transformed (``npoint'') and the numbers of input and output -coordinates per point (``ncoord\_in'' and ``ncoord\_out''---in this -case both are assumed equal) are passed to the function. A pair of -loops then accesses all the coordinate values. Note that it is -legitimate to omit one or other of the forward/inverse transformations -and simply not to implement it, if it will not be required. It is also -permissible to require that the numbers of input and output -coordinates be fixed (\emph{e.g.}\ at 2), or to write the function so -that it can handle arbitrary dimensionality, as here. - -Before using an incoming coordinate, the function must first check -that it is not set to the value AST\_\_BAD, which indicates missing -data (\secref{ss:badcoordinates}). If it is, the same value is also -assigned to any affected output coordinates. The value AST\_\_BAD is -also generated if any coordinates cannot be transformed. In this -example, this can happen with the inverse transformation if negative -values are encountered, so that the square root cannot be taken. - -There are very few restrictions on what a coordinate transformation -function may do. For example, it may freely perform I/O to access any -external data needed, it may invoke other AST facilities (but beware -of unwanted recursion), \emph{etc.} Typically, you may also want to -pass information to it \emph{via}\ global variables. Remember, -however, that whatever facilities the transformation function requires -must be available in every program which uses it. - -Generally, it is not a good idea to retain context information within -a transformation function. That is, it should transform each set of -coordinates as a single point and retain no memory of the points it -has transformed before. This is in order to conform with the AST model -of a \htmlref{Mapping}{Mapping}. - -If an error occurs within a transformation function, it should use the -\htmlref{astSetStatus}{astSetStatus} function (\secref{ss:errordetection}) to set the AST -status to an error value before returning. This will alert AST to the -error, causing it to abort the current operation. The error value -AST\_\_ITFER is available for this purpose, but other values may also -be used (\emph{e.g.}\ if you wish to distinguish different types of -error). - -\subsection{\label{ss:registeringintramaps}Registering a Transformation Function} - -Having written your coordinate transformation function, the next step -is to register it with AST. Registration is performed using -\htmlref{astIntraReg}{astIntraReg}, as follows: - -\small -\begin{terminalv} -void SqrTran( AstMapping *, int, int, const double *[], int, int, double *[] ); - -const char *author, *contact, *purpose; - -... - -purpose = "Square each coordinate value"; -author = "R.F. Warren-Smith & D.S. Berry"; -contact = "http://www.starlink.ac.uk/cgi-bin/htxserver/sun211.htx/?xref_SqrTran"; - -astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact ); -\end{terminalv} -\normalsize - -Note that you should also provide a function prototype to describe the -transformation function (the implementation of the function itself -would suffice, of course). - -The first argument to astIntraReg is a name by which the -transformation function will be known. This will be used when we come -to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you use -the actual function name here and make this sufficiently unusual that -it is unlikely to clash with any other functions in most people's -software. - -The next two arguments specify the number of input and output -coordinates which the transformation function will handle. These -correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will -create. Here, we have set them both to 2, which means that we will -only be able to create IntraMaps with 2 input and 2 output coordinates -(despite the fact that the transformation function can actually handle -other dimensionalities). We will see later -(\secref{ss:variableintramapcoordinates}) how to remove this -restriction. - -The fourth argument should contain a set of flags which describe the -transformation function in a little more detail. We will return to -this shortly (\secref{ss:restrictedintramaps} \& -\secref{ss:simplifyingintramaps}). For now, we supply a value of zero. - -The remaining arguments are character strings which document the -transformation function, mainly for the benefit of anyone who is -unfortunate enough to encounter a reference to it in their data which -they cannot interpret. As explained above -(\secref{ss:intramaplimitations}), you should try and avoid this, but -accidents will happen, so you should always provide strings containing -the following: - -\begin{enumerate} -\item A short description of what the transformation function is for. -\item The name of the author. -\item Contact details, such as an e-mail or WWW address. -\end{enumerate} - -The idea is that anyone finding an IntraMap in their data, but lacking -the necessary transformation function, should be able to contact the -author and make a sensible enquiry in order to obtain it. If you -expect many enquiries, you may like to set up a World Wide Web page -and use that instead (in the example above, we use the WWW address of -the relevant part of this document). - -\subsection{Creating an IntraMap} - -Once a transformation function has been registered, creating an -\htmlref{IntraMap}{IntraMap} from it is simple: - -\small -\begin{terminalv} -AstIntraMap *intramap; - -... - -intramap = astIntraMap( "SqrTran", 2, 2, "" ); -\end{terminalv} -\normalsize - -We simply use the \htmlref{astIntraMap}{astIntraMap} constructor function and pass it the -name of the transformation function to use. This name is the same -(case sensitive) one that we associated with the function when we -registered it using \htmlref{astIntraReg}{astIntraReg} (\secref{ss:registeringintramaps}). - -You can, of course, register any number of transformation functions -and select which one to use whenever you create an IntraMap. You can -also create any number of independent IntraMaps using each -transformation function. In this sense, each transformation function -you register effectively creates a new ``sub-class'' of IntraMap, from -which you can create Objects just like any other class. However, an -error will occur if you attempt to use a transformation function that -has not yet been registered. - -The second and third arguments to astIntraMap are the numbers of input -and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for -the IntraMap that is created and they must match the corresponding -numbers given when the transformation function was registered. - -The final argument is the usual attribute initialisation string. You -may set attribute values for an IntraMap in exactly the same way as -for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see -\secref{ss:intraflag}). - -\subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Functions} - -You may not always want to use both the forward and inverse -transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit -either from the underlying coordinate transformation -function. Consider the following, for example: - -\small -\begin{terminalv} -void Poly3Tran( AstMapping *this, int npoint, int ncoord_in, - const double *ptr_in[], int forward, int ncoord_out, - double *ptr_out[] ) { - double x; - int point; - -/* Forward transformation. */ - for ( point = 0; point < npoint; point++ ) { - x = ptr_in[ 0 ][ point ]; - ptr_out[ 0 ][ point ] = ( x == AST__BAD ) ? AST__BAD : - 6.18 + x * ( 0.12 + x * ( -0.003 + x * 0.0000101 ) ); - } -} -\end{terminalv} -\normalsize - -This implements a 1-dimensional cubic polynomial transformation. Since -this is somewhat awkward to invert, however, we have only implemented -the forward transformation. When registering the function, this is -indicated via the ``flags'' argument to \htmlref{astIntraReg}{astIntraReg}, as follows: - -\small -\begin{terminalv} -void Poly3Tran( AstMapping *, int, int, const double *[], int, int, double *[] ); - -... - -astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, - purpose, author, contact ); -\end{terminalv} -\normalsize - -Here, the fifth argument has been set to the flag value AST\_\_NOINV -to indicate the lack of an inverse. If the forward transformation were -absent, we would use AST\_\_NOFOR instead. Flag values for this -argument may be combined using a bitwise OR if necessary. - -\subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates} - -In our earlier examples, we have used a fixed number of input and -output coordinates when registering a coordinate transformation -function. It is not necessary to impose this restriction, however, if -the transformation function can cope with a variable number of -coordinates (as with the example in -\secref{ss:transformationfunctions}). We indicate the acceptability of -a variable number when registering the transformation function by -supplying the value AST\_\_ANY for the number of input and/or output -coordinates, as follows: - -\small -\begin{terminalv} -astIntraReg( "SqrTran", AST__ANY, AST__ANY, SqrTran, 0, - purpose, author, contact ); -\end{terminalv} -\normalsize - -The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of -input and output coordinates. For example: - -\small -\begin{terminalv} -AstIntraMap *intramap1, *intramap2; - -... - -intramap1 = astIntraMap( "SqrTran", 1, 1, "" ); -intramap2 = astIntraMap( "SqrTran", 3, 3, "Invert=1" ); -\end{terminalv} -\normalsize - -It is possible to fix either the number of input or output coordinates -(by supplying an explicit number to \htmlref{astIntraReg}{astIntraReg}), but more subtle -restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin} -and \htmlref{Nout}{Nout} be equal, are not supported. This means that: - -\small -\begin{terminalv} -intramap = astIntraMap( "SqrTran", 1, 2, "" ); -\end{terminalv} -\normalsize - -will be accepted without error, although the transformation function -cannot actually handle such a combination sensibly. If this is -important, it would be worth adding a check within the transformation -function itself, so that the error would be detected when it came to -be used. - -\subsection{\label{ss:intraflag}Adapting a Transformation Function to Individual IntraMaps} - -In the examples given so far, our coordinate transformation functions -have not made use of the ``this'' pointer passed to them (which -identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In -practice, this will often be the case. However, the presence of the -``this'' pointer allows the transformation function to invoke any -other AST function on the IntraMap, and this permits enquiries about -its attributes. The transformation function's behaviour can therefore -be modified according to any attribute values which are set. This -turns out to be a useful thing to do, so each IntraMap has a special -\htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose. - -Consider, for instance, the case where the transformation function has -access to several alternative sets of internally-stored data which it -may apply to perform its transformation. Rather than implement many -different versions of the transformation function, you may switch -between them by setting a value for the IntraFlag attribute when you -create an instance of an IntraMap, for example: - -\small -\begin{terminalv} -intramap1 = astIntraMap( "MyTran", 2, 2, "IntraFlag=A" ); -intramap2 = astIntraMap( "MyTran", 2, 2, "IntraFlag=B" ); -\end{terminalv} -\normalsize - -The transformation function may then enquire the value of the IntraFlag -attribute (\emph{e.g.}\ using astGetC and passing it the ``this'' -pointer) and use whichever dataset is required for that particular -IntraMap. - -This approach is particularly useful when the number of possible -transformations is unbounded or not known in advance, in which case -the IntraFlag attribute may be used to hold numerical values encoded -as part of a character string (effectively using them as data for the -IntraMap). It is also superior to the use of a global switch for -communication (\emph{e.g.}\ setting an index to select the ``current'' -data before using the IntraMap), because it continues to work when -several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping}, -when you may have no control over the order in which they are used. - -\subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps} - -A notable disadvantage of IntraMaps is that they are ``black boxes'' -as far as AST is concerned. This means that they have limited ability -to participate in the simplification of compound Mappings performed, -\emph{e.g.}, by \htmlref{astSimplify}{astSimplify} (\secref{ss:simplifyingcmpmaps}), because -AST cannot know how they interact with other Mappings. In reality, of -course, they will often implement such specialised coordinate -transformations that the simplification possibilities will be rather -limited anyway. - -One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to -cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This -is important because Mappings are frequently used to relate a dataset -to some external standard (a celestial coordinate system, for -example). When inter-relating two similar datasets calibrated using -the same standard, part of the Mapping often cancels, because it is -applied first in one direction and then the other, effectively -eliminating the reference to the standard. This is often a useful -simplification and can lead to greater efficiency. - -Many transformations have this property of cancelling with their own -inverse, but not necessarily all. Consider the following -transformation function, for example: - -\small -\begin{terminalv} -void MaxTran( AstMapping *this, int npoint, int ncoord_in, - const double *ptr_in[], int forward, int ncoord_out, - double *ptr_out[] ) { - double hi, x; - int coord, point; - -/* Forward transformation. */ - if ( forward ) { - for ( point = 0; point < npoint; point++ ) { - hi = AST__BAD; - for ( coord = 0; coord < ncoord_in; coord++ ) { - x = ptr_in[ coord ][ point ]; - if ( x != AST__BAD ) { - if ( x > hi || hi == AST__BAD ) hi = x; - } - } - ptr_out[ 0 ][ point ] = hi; - } - -/* Inverse transformation. */ - } else { - for ( coord = 0; coord < ncoord_out; coord++ ) { - for ( point = 0; point < npoint; point++ ) { - ptr_out[ coord ][ point ] = ptr_in[ 0 ][ point ]; - } - } - } -} -\end{terminalv} -\normalsize - -This function takes any number of input coordinates and returns a -single output coordinate which is the maximum value of the input -coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the -input coordinates to the value of the output -coordinate.\footnote{Remember that ``ptr\_in'' identifies the original -``output'' coordinates when applying the inverse transformation and -``ptr\_out'' identifies the original ``input'' coordinates.} - -If this function is applied in the forward direction and then in the -inverse direction, it does \textbf{not} in general restore the original -coordinate values. However, if applied in the inverse direction and -then the forward direction, it does. Hence, replacing the sequence of -operations with an equivalent UnitMap is possible in the latter case, -but not in the former. - -To distinguish these possibilities, two flag values are provided for -use with \htmlref{astIntraReg}{astIntraReg} to indicate what simplification (if any) is -possible. For example, to register the above transformation function, -we might use: - -\small -\begin{terminalv} -void MaxTran( AstMapping *, int, int, const double *[], int, int, double *[] ); - -... - -astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, - purpose, author, contact ); -\end{terminalv} -\normalsize - -Here, the flag value AST\_\_SIMPIF supplied for the fifth argument -indicates that simplification is possible if the transformation is -applied in the inverse direction followed by the forward direction. To -indicate the complementary case, the flag AST\_\_SIMPFI would be used -instead. If both simplifications are possible (as with the SqrTran -function in \secref{ss:transformationfunctions}), then we would use -the bitwise OR of both values. - -In practice, some judgement is usually necessary when deciding whether -to allow simplification. For example, seen in one light our SqrTran -function (\secref{ss:transformationfunctions}) does not cancel with -its own inverse, because squaring a coordinate value and then taking -its square root can change the original value, if this was -negative. Therefore, replacing this combination with a UnitMap will -change the behaviour of a compound Mapping and should not be -allowed. Seen in another light, however, where the coordinates being -processed are intrinsically all positive, it is a permissible and -probably useful simplification. - -If such distinctions are ever important in practice, it is simple to -register the same transformation function twice with different flag -values (use a separate name for each) and then use whichever is -appropriate when creating an \htmlref{IntraMap}{IntraMap}. - -\subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps} - -It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a -\htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation function -which it uses is not stored with it. To do so is impossible, because -the function has been compiled and loaded into memory ready for -execution before AST gets to see it. However, AST does store the name -associated with the transformation function and various details about -the IntraMap itself. - - -This means that any program attempting to read the IntraMap -(\secref{ss:readingfromachannel}) cannot make use of it unless it also -has independent access to the original transformation function. If it -does not have access to this function, an error will occur at the -point where the IntraMap is read and the associated error message will -direct the user to the author of the transformation function for more -information. - -However, if the necessary transformation function is available, and -has been registered before the read operation takes place, then AST is -able to re-create the original IntraMap and will do so. Registration -of the transformation function must, of course, use the same name -(and, in fact, be identical in most particulars) as was used in the -original program which wrote the data. - -This means that a set of co-operating programs which all have access -to the same set of transformation functions and register them in -identical fashion (see \secref{ss:intramaplibrary} for how this can -best be achieved) can freely exchange data that contain IntraMaps. The -need to avoid exporting such data to unsuspecting third parties -(\secref{ss:intramaplimitations}) must, however, be re-iterated. - -\subsection{\label{ss:intramaplibrary}Managing Transformation Functions in Libraries} - -If you are developing a large suite of data reduction software, you -may have a need to use IntraMaps at various points within it. Very -probably this will occur in unrelated modules which are compiled -separately and then stored in a library. Since the transformation -functions required must be registered before they can be used, this -makes it difficult to decide where to perform this registration, -especially since any particular data reduction program may use an -arbitrary subset of the modules in your library. - -To assist with this problem, AST allows you to perform the same -registration of a transformation function any number of times, so long -as it is performed using an identical invocation of \htmlref{astIntraReg}{astIntraReg} on -each occasion (\emph{i.e.}\ all of its arguments must be -identical). This means you do not have to keep track of whether a -particular function has already been registered but could, in fact, -register it on each occasion immediately before it is required -(wherever that may be). In order that all registrations are identical, -however, it is recommended that you group them all together into a -single function, perhaps as follows: - -\small -\begin{terminalv} -void MyTrans( void ) { - - ... - - astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF, - purpose, author, contact ); - - ... - - astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV, - purpose, author, contact ); - - ... - - astIntraReg( "SqrTran", 2, 2, SqrTran, 0, - purpose, author, contact ); -} -\end{terminalv} -\normalsize - -You can then simply invoke this function wherever necessary. It is, in -fact, particularly important to register all relevant transformation -functions in this way before you attempt to read an \htmlref{Object}{Object} that might -be (or contain) an \htmlref{IntraMap}{IntraMap} -(\secref{ss:readingandwritingintramaps}). This is because you may not -know in advance which of these transformation functions the IntraMap -will use, so they must all be available in order to avoid an error. - -\cleardoublepage -\section{\label{ss:plots}Producing Graphical Output (Plots)} - -Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot}, -which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the -graphical content itself, but is a route through which plotting -operations, such as drawing lines and curves, are conveyed on to a -plotting surface to appear as visible graphics. - -\subsection{The Plot Model} - -When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose -base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or -logarithmically (as specified by the LogPlot attribues) on to a -\emph{plotting area}. This is a rectangular region in the graphical -coordinate space of the underlying graphics system and becomes the new -base Frame of the Plot. In effect, the Plot becomes attached to the -plotting surface, in rather the same way that a basic FrameSet might be -attached to (say) an image. - -The current Frame of the Plot (derived from the current Frame of the -FrameSet supplied) is used to represent a \emph{physical coordinate -system}. This is the system in which plotting operations are -performed by your program. Every plotting operation is then -transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current -and base Frames in order to appear on the plotting surface. - -An example may help here. Suppose we start with a FrameSet whose base -Frame describes the pixel coordinates of an image and whose current -Frame describes a celestial (equatorial) coordinate system. Let us -assume that these two Frames are inter-related by a Mapping within the -FrameSet which represents a particular sky projection. - -When a Plot is created from this FrameSet, we specify how the pixel -coordinates (the base Frame) maps on to the plotting surface. This -simply corresponds to telling the Plot where we have previously -plotted the image data. If we now use the Plot to plot a line with -latitude zero in our physical coordinate system, as given by the -current Frame, this line would appear as a curve (the equator) on the -plotting surface, correctly registered with the image. - -There are a number of plotting functions provided, which all work in a -similar way. Plotting operations are transformed through the Mapping -which the Plot represents before they appear on the plotting -surface.\footnote{Like any FrameSet, a Plot can be used as a -Mapping. In this case it is the inverse transformation which is used -when plotting (\emph{i.e.}\ that which transforms between the current -and base Frames).} It is possible to draw symbols, lines, axes, -entire grids and more in this way. - -%\subsection{TBW---Creating a Plot} - -\subsection{Plotting Symbols} - -The simplest form of plotting is to draw symbols (termed -\emph{markers}) at a set of points. This is performed by \htmlref{astMark}{astMark}, -which is supplied with a set of physical coordinates at which to place -the markers: - -\small -\begin{terminalv} -#include "ast.h" -#define NCOORD 2 -#define NMARK 10 -double in[ NCOORD ][ NMARK ]; -int type; - -... - -astMark( plot, NMARK, NCOORD, NMARK, in, type ); -\end{terminalv} -\normalsize - -Here, NMARK specifies how many markers to plot and NCOORD specifies -how many coordinates are being supplied for each -point.\footnote{Remember, the physical coordinate space need not -necessarily be 2-dimensional, even if the plotting surface is.} The -array ``in'' supplies the coordinates and the integer ``type'' -specifies which type of marker to plot. - -\subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves} - -There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight -line in physical coordinates can potentially turn into a curve in -graphical coordinates. We therefore start by considering how to draw -geodesic curves. These are curves which trace the path of shortest -distance between two points in physical coordinates - and are the basic drawing element in a Plot. - -In many instances, the geodesic will, in fact, be a straight line, but -this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a -celestial coordinate system, for instance, it will be a great circle -(corresponding with the behaviour of the \htmlref{astDistance}{astDistance} function which -defines the metric of the physical coordinate space). The geodesic -will, of course, be transformed into graphics coordinates before being -plotted. A geodesic curve is plotted using \htmlref{astCurve}{astCurve} as follows: - -\small -\begin{terminalv} -double start[ NCOORD ], finish[ NCOORD ]; - -... - -astCurve( plot, start, finish ); -\end{terminalv} -\normalsize - -Here, ``start'' and ``finish'' are arrays containing the starting and -finishing coordinates of the curve. The \htmlref{astOffset}{astOffset} and astDistance -functions can often be useful for computing these -(\secref{ss:distanceandoffset}). - -If you need to draw a series of curves end-to-end (when drawing a -contour line, for example), then a more efficient alternative is to -use \htmlref{astPolyCurve}{astPolyCurve}. This has the same effect as a sequence of -invocations of astCurve, but allows you to supply a whole set of -points at one time. astPolyCurve then joins them, in sequence, using -geodesic curves: - -\small -\begin{terminalv} -#define NPOINT 100 -double coords[ NCOORD ][ NPOINT ]; - -... - -astPolyCurve( plot, NPOINT, NCOORD, NPOINT, coords ); -\end{terminalv} -\normalsize - -Here, NPOINT specifies how many points are to be joined and NCOORD -specifies how many coordinates are being supplied for each point. The -array ``coords'' supplies the coordinates of the points in the Plot's -physical coordinate system. - -\subsection{Plotting Curves Parallel to Axes} - -As there is no \htmlref{Plot}{Plot} function to draw a ``straight line'', drawing axes -and grid lines to represent coordinate systems requires a slightly -different approach. The problem is that for some coordinate systems, -these grid lines will not be geodesics, so \htmlref{astCurve}{astCurve} and \htmlref{astPolyCurve}{astPolyCurve} -(\secref{ss:plottinggeodesics}) cannot easily be used (you would have -to resort to approximating grid lines by many small elements). Lines -of constant celestial latitude provide an example of this, with the -exception of the equator which is a geodesic. - -The \htmlref{astGridLine}{astGridLine} function allows these curves to be drawn, as follows: - -\small -\begin{terminalv} -int axis; -double length; - -... - -astGridLine( plot, axis, start, length ); -\end{terminalv} -\normalsize - -Here, ``axis'' specifies which physical coordinate axis we wish to -draw parallel to. The ``start'' array contains the coordinates of the -start of the curve and ``length'' specifies the distance to draw along -the axis in physical coordinate space. - -\subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves} -We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot} -class includes another method, -\htmlref{astGenCurve}{astGenCurve}, -which allows curves of \emph{any} form to be drawn. The caller supplies a -\htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the -start of the curve is at offset 0.0 and the end of the curve is at offset -1.0 - offset need not be linearly related to distance.} into the -corresponding position in the current \htmlref{Frame}{Frame} of the Plot. -astGenCurve, -then takes care of Mapping these positions into graphics coordinates. The -choice of exactly which positions along the curve are to be used to -define the curve is also made by -astGenCurve, -using an adaptive algorithm which concentrates points around areas where -the curve is bending sharply or is discontinuous in graphics coordinates. - -The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows -you to code your own Mappings to do any transformation you choose. - - -\subsection{\label{ss:clipping}Clipping} - -Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics -you produce. This means that plotting is restricted to certain regions -of the plotting surface so that anything drawn outside these regions -will not appear. All Plots automatically clip at the edges of the -plotting area specified when the Plot is created. This means that -graphics are ultimately restricted to the rectangular region of -plotting space to which you have attached the Plot. - -In addition to this, you may also specify lower and upper limits on -each axis at which clipping should occur. This permits you to further -restrict the plotting region. Moreover, you may attach these clipping -limits to \emph{any} of the Frames in the Plot. This allows you to -place restrictions on where plotting will take place in either the -physical coordinate system, the graphical coordinate system, or in any -other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot. - -For example, you could plot using equatorial coordinates and set up -clipping limits in galactic coordinates. In general, you could set up -arbitrary clipping regions by adding a new Frame to a Plot (in which -clipping will be performed) and inter-relating this to the other -Frames in a suitable way. - -Clipping limits are defined using the \htmlref{astClip}{astClip} function, as follows: - -\small -\begin{terminalv} -#define NAXES 2 -int iframe; -double lbnd[ NAXES ], ubnd[ NAXES ]; - -... -astClip( plot, iframe, lbnd, ubnd); -\end{terminalv} -\normalsize - -Here, the ``iframe'' value gives the index of the Frame within the -Plot to which clipping is to be applied, while ``lbnd'' and ``ubnd'' -give the limits on each axis of the selected Frame (NAXES is the -number of axes in this Frame). - -You can remove clipping by giving a value of AST\_\_NOFRAME for ``iframe''. - -\subsection{Using a Plot as a Mapping} - -All Plots are also Mappings (just like the FrameSets from which they -are derived), so can be used to transform coordinates. - -Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert -coordinates between the base and current Frames (\emph{i.e.}\ between -graphical and physical coordinates). This would be useful if you were -(say) reading a cursor position in graphical coordinates and needed to -convert this into physical coordinates for display. - -Conversely, a Plot's inverse transformation converts between its -current and base Frames (\emph{i.e.}\ from physical coordinates to -graphical coordinates). This transformation is applied automatically -whenever plotting operations are carried out by AST functions. It may -also be useful to apply it directly, however, if you wish to perform -additional plotting operations (\emph{e.g.}\ those provided by the -native graphics system) at positions specified in physical -coordinates. - -There is, however, one important difference between using a \htmlref{FrameSet}{FrameSet} -and a Plot to transform coordinates, and this is that clipping may be -applied by a Plot (if it has been enabled using -\htmlref{astClip}{astClip}---\secref{ss:clipping}). Any point which lies within the -clipped region of a Plot will, when transformed, yield coordinates -with the value AST\_\_BAD. If you wish to avoid this clipping, you -should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using -\htmlref{astGetMapping}{astGetMapping}) and use this, instead of the Plot, to transform the -coordinates. - -\subsection{Using a Plot as a Frame} - -Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of -Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units, -\emph{etc.}, which are typically used when displaying data and/or -coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from -the current Frame of the Plot (\secref{ss:framesetasframe}). They are -also used automatically when using the Plot to plot coordinate axes -and coordinate grids (\emph{e.g.}\ for labelling -them---\secref{ss:plottingagrid}). - -Because the current Frame of a Plot represents physical coordinates, -any Frame operation applied to the Plot will effectively be working in -this coordinate system. For example, the \htmlref{astDistance}{astDistance} and \htmlref{astOffset}{astOffset} -functions will compute distances and offsets in physical coordinate -space, while \htmlref{astFormat}{astFormat} and \htmlref{astNorm}{astNorm} will format physical coordinates in -an appropriate way for display. - -\subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates} - -When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot} -into graphics coordinates for plotting, they may not always yield -valid coordinates, irrespective of any clipping being applied -(\secref{ss:clipping}). To indicate this, the resulting coordinate -values will be set to the value AST\_\_BAD -(\secref{ss:badcoordinates}). - -There are a number of reasons why this may occur, but typically it -will be because physical coordinates only map on to a subset of the -graphics coordinate space. This situation is commonly encountered with -all-sky projections where, typically, the celestial sphere appears, -when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which -does not entirely fill the graphics space. In some cases, there may -even be multiple regions of valid and invalid physical coordinates. - -When plotting is performed \emph{via} a Plot, graphical output will -only appear in the regions of valid physical coordinates. Nothing will -appear where invalid coordinates occur. Such output is effectively -clipped. If you wish to plot in these areas, you must change -coordinate system and use, say, graphical coordinates to address the -plotting surface directly. - -\subsection{Plotting Borders} - -The \htmlref{astBorder}{astBorder} function is provided to draw a (line) border around your -graphical output. With most graphics systems, this would simply be a -rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this -boundary follows the edge of each region containing valid, unclipped -physical coordinates (\secref{ss:validphysicalcoordinates}). - -This means, for example, that if you were plotting an all-sky -projection, this boundary would outline the perimeter of the celestial -sphere when projected on to your plotting surface. Of course, if there -is no clipping and all physical coordinates are valid, then you will -get the traditional rectangular box. astBorder requires only -a pointer to the Plot: - -\small -\begin{terminalv} -int holes; - -... - -holes = astBorder( plot ); -\end{terminalv} -\normalsize - -It returns a boolean (integer) value to indicate if any invalid or -clipped physical coordinates were found within the plotting area. If -they were, it will draw around the valid unclipped regions and return -a value of one. Otherwise, it will draw a simple rectangular border -and return zero. - -\subsection{Plotting Text} - -Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be -displayed and a position in physical coordinates where the text is to -appear. The position is transformed into graphical coordinates to -determine where the text should appear on the plotting surface. You -must also provide a 2-element ``up'' vector which gives the upward -direction of the text in graphical coordinates. This allows text to be -drawn at any angle. - -Plotting is performed by \htmlref{astText}{astText}, for example: - -\small -\begin{terminalv} -char text[ 21 ]; -double pos[ NCOORD ]; -float up[ 2 ] = { 0.0f, 1.0f }; - -... - -astText( plot, text, pos, up, "TL" ); -\end{terminalv} -\normalsize - -Here, ``text'' contains the string to be drawn, ``pos'' is an array of -physical coordinates and ``up'' specifies the upward vector. In this -case, the text will be drawn horizontally. The final argument -specifies the text justification, here indicating that the top left -corner of the text should appear at the position given. - -Further control over the appearance of the text is possible by setting -values for various Plot attributes, for example Colour, Font and Size. -Sub-strings within the displayed text can be given different appearances, -or turned into super-scripts or sub-scripts, by the inclusion of escape -sequences (see section~\secref{ss:escapes}) within the supplied text string. - -\subsection{\label{ss:plottingagrid}Plotting a Grid} - -The most comprehensive plotting function available is \htmlref{astGrid}{astGrid}, which -can be used to draw labelled coordinate axes and, optionally, to -overlay coordinate grids on the plotting area -(Figure~\ref{fig:gridplot}). The routine is straightforward to use, -simply requiring a pointer to the \htmlref{Plot}{Plot}: - -\small -\begin{terminalv} -astGrid( plot ); -\end{terminalv} -\normalsize - -It will draw both linear and curvilinear axes and grids, as required -by the particular Plot. The appearance of the output can be modified -in a wide variety of ways by setting various Plot attributes. -The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis -labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings -within these strings can be given different appearances, or turned into -super-scripts or sub-scripts, by the inclusion of escape sequences (see -section~\secref{ss:escapes}) within the Label attributes. - -\subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings} -Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be -plotted so that all characters in the string have the same font size, -colour, \emph{etc.}, specified by the appropriate attributes of the -Plot. However, it is possible to include \emph{escape sequences} within -the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be -used to change, colour, font, size, width, to introduce extra horizontal -space between characters, and to change the base line of characters (thus -allowing super-scripts and sub-scripts to be created). See the entry for -the Escape attribute in \appref{ss:attributedescriptions} for details. - -As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is -plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a -super-scripted exponent. The exponent text will be 70\% of the size of -normal text (as determined by the Size attribute), and its baseline will -be raised by 50\% of the height of a normal character. - -Such escape sequences can be used in the strings assigned to textual -attributes of the Plot (such as the axis Labels), and may also be -included in strings plotted using -\htmlref{astText}{astText}. - -The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option -which will cause escape sequences to be included when formatting -celestial positions so that super-script characters are used as -delimiters for the various fields (a super-script ``h'' for hours, ``m'' -for minutes, \emph{etc}). - -Note, the facility for interpreting escape sequences is only available if -the graphics wrapper functions which provide the interface to the -underlying graphics system support all the functions included in the -\verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be -extended by the addition of new functions before escape sequences can be -interpretted. - -\subsection{\label{ss:logaxes}Producing Logarithmic Axes} -In certain situations you may wish for one or both of the plotted axes to -be displayed logarithmically rather than linearly. For instance, you may -wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux -against frequency. In this case, you can cause the frequency axis to be drawn -logarithmically simply by setting the boolean LogPlot attribute for the -frequency axis to a non-zero value. This causes several things to happen: - -\begin{enumerate} - -\item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents -the underlying graphics world coordinate system) and the base Frame of -the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By -default, this mapping is linear on both axes, but setting LogPlot non-zero -for an axis causes the Mapping to be modified so that it is logarithmic -on the specified axis. This is only possible if the displayed section of -the axis does not include the value zero (otherwise the attempt to set -a new value for LogPlot is ignored,and it retains its default value of -zero). - -\item The major tick marks drawn as part of the annotated coordinate grid -are spaced logarithmically rather than linearly. That is, major axis -values are chosen so that there is a constant ratio between adjacent -tick mark values. This ratio is constrained to be a power of ten. The -minor tick marks are drawn at linearly distributed points between the -adjoining major tick values. Thus if a pair of adjacent major tick values -are drawn at axis values 10.0 and 100.0, minor ticks will be placed at -20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick -marks are drawn). - -\item If possible, numerical axis labels are shown as powers of ten. -This depends on the facilities implemented by the graphics wrapper -functions (see the next section). Extra functions were introduced to this -set of wrapper functions at AST V3.2 which enable super-scripts and -sub-scripts to be produced. Some older wrappers may not yet have -implemented these functiosn and this will result in axis labels being -drawn in usual scientific or decimal notation. - -\end{enumerate} - -Whilst the LogPlot attribute can be used to control all three of the above -facilities, it is possible to control them individually as well. The -LogTicks and LogLabel attributes control the behaviour specified in items -2 and 3 above, but the default values for these attributes depend on the -setting of the LogPlot attribute. This means that setting LogPlot -non-zero will swicth all three facilites on, so long as zero values have -not been assigned explicitly to LogTicks or LogLabel. - - -\subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package} -The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a -graphics device. Instead, it requires a set of functions to be provided -which it uses to draw the required graphics. These include functions -to draw a straight line, draw a text string, \emph{etc}. You may choose -to provide functions from your favorite graphics package, or you can even -write your own! To accomodate variations in the calling interfaces of -different graphics packages, AST defines a standard interface for these -routines. If this interface differs from the interface provided by your -graphics package (which in general it will), then you must write a set of -\emph{wrapper functions}, which provide the interface expected by AST but -which then call functions from your graphics package to provide the -required functionality. AST comes with wrapper functions suitable for -the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}). - -There are two ways of indicating which wrapper functions are to be used by -the Plot class: -\begin{enumerate} - -\item A file containing C functions with pre-defined names can be written -and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command. -(see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is -distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT -functions to implement the required functionality. This file can be used -as a template for writing your own. - -\item The -\htmlref{astGrfSet}{astGrfSet} -method of the Plot class can be used to ``register'' -wrapper functions at run-time. This allows an application to switch -between graphics systems if required. Graphics functions registered in -this way do not need to have the pre-defined names used in the link-time -method described above. - -\end{enumerate} - -For details of the interfaces of the wrapper routines, see -either the \texttt{grf\_pgplot.c} file included in the AST source -distribution, or the reference documentation for the astGrfSet method. - -\cleardoublepage -\section{Compiling and Linking Software that Uses AST} - -A small number of UNIX commands are provided by AST to assist with the -process of building software. A description of these can be found in -\appref{ss:commanddescriptions} and their use is discussed here. Note -that in order to access these commands, the appropriate directory -(normally ``/star/bin'') should be on your PATH.\footnote{If you have -not installed AST in the usual location, then substitute the -appropriate directory in place of ``/star'' wherever it occurs.} - -\subsection{\label{ss:accessingheaderfile}Accessing the ``ast.h'' Header File} - -The ``ast.h'' header file defines the external interface to the AST library, -including all constants, function prototypes, macros, \emph{etc.}. This file -should be located using the usual compiler options for finding C -include files, for instance: - -\small -\begin{terminalv} -cc prog.c -I/star/include -o prog -\end{terminalv} -\normalsize - -This is preferable to specifying the file's absolute name within your -software. - -\subsection{\label{ss:linking}Linking with AST Facilities} - -C programs which use AST facilities may be linked by including -execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command -line. Thus, to compile and link a program called ``prog'', the -following might be used: - -\small -\begin{terminalv} -cc prog.c -L/star/lib `ast_link` -o prog -\end{terminalv} -\normalsize - -Note the use of backward quote characters, which cause the -``ast\_link'' command to be executed and its result substituted into -the compiler command. An alternative is to save the output from -``ast\_link'' in (say) a shell variable and use this instead. You may -find this a little faster if you are building software repeatedly -during development. - -Programs which use AST can also be linked in a number of other ways, -depending on the facilities they require. In the example above, we -have used the default method which assumes that the program will not -be generating graphical output, so that no graphics libraries need be -linked. If you need other facilities, then various switches can be -applied to the ``ast\_link'' command in order to control the linking -process. - -For example, if you were producing graphical output using the PGPLOT -graphics package, you could link with the AST/PGPLOT interface by -using the ``$-$pgplot'' switch with ``ast\_link'', as -follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use -the Starlink version of PGPLOT which uses GKS to generate its output.} - -\small -\begin{terminalv} -cc prog.c -L/star/lib `ast_link -pgplot` -o prog -\end{terminalv} -\normalsize - -See the ``ast\_link'' command description in -\appref{ss:commanddescriptions} for details of the options available. - -\subsection{Building ADAM Applications that Use AST} - -Users of Starlink's \xref{ADAM}{sg4}{} programming environment -\latex{(SG/4)} on UNIX should use the -``\xref{alink}{sun144}{ADAM_link_scripts}'' command -(\xref{SUN/144}{sun144}{}) to compile and link applications and can -access the AST library by including execution of the command -``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows: - -\begin{small} -\begin{terminalv} -alink adamprog.c `ast_link_adam` -\end{terminalv} -\end{small} - -Note the use of backward quote characters. - -By default, AST error messages produced by applications built in this -way will be delivered \emph{via} the Starlink EMS Error Message -Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is -consistent with the \xref{\emph{inherited -status}}{sun104}{inherited_status} error handling normally used in -Starlink software. - -Switches may be given to the ``ast\_link\_adam'' command (in a similar -way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with -additional AST-related facilities, such as a graphics interface. See -the ``ast\_link\_adam'' command description in -\appref{ss:commanddescriptions} for details of the options available. - -\appendix -\cleardoublepage -\section{\label{ss:classhierarchy}The AST Class Hierarchy} -The following table shows the hierarchy of classes in the AST library. -For a description of each class, you should consult -\appref{ss:classdescriptions}. - -\small -\begin{terminalv} -Object - Base class for all AST Objects - Axis - Store axis information - SkyAxis - Store celestial axis information - Channel - Basic (textual) I/O channel - FitsChan - I/O Channel using FITS header cards - XmlChan - I/O Channel using XML - StcsChan - I/O Channel using IVOA STC-S descriptions - KeyMap - Store a set of key/value pairs - Table - Store a 2-dimensional table of values - Mapping - Inter-relate two coordinate systems - CmpMap - Compound Mapping - DssMap - Map points using Digitised Sky Survey plate solution - Frame - Coordinate system description - CmpFrame - Compound Frame - SpecFluxFrame - Observed value versus spectral position - FluxFrame - Observed value at a given fixed spectral position - FrameSet - Set of inter-related coordinate systems - Plot - Provide facilities for 2D graphical output - Plot3D - Provide facilities for 3D graphical output - Region - Specify areas within a coordinate system - Box - A box region with sides parallel to the axes of a Frame - Circle - A circular or spherical region within a Frame - CmpRegion - A combination of two regions within a single Frame - Ellipse - An elliptical region within a 2-dimensional Frame - Interval - Intervals on one or more axes of a Frame. - NullRegion - A boundless region within a Frame - PointList - A collection of points in a Frame - Polygon - A polygonal region within a 2-dimensional Frame - Prism - An extrusion of a Region into orthogonal dimensions - Stc - Represents an generic instance of an IVOA STC-X description - StcResourceProfile - Represents an an IVOA STC-X ResourceProfile - StcSearchLocation - Represents an an IVOA STC-X SearchLocation - StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation - StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation - SkyFrame - Celestial coordinate system description - SpecFrame - Spectral coordinate system description - DSBSpecFrame - Dual sideband spectral coordinate system description - TimeFrame - Time coordinate system description - GrismMap - Models the spectral dispersion produced by a grism - IntraMap - Map points using a private transformation function - LutMap - Transform 1-dimensional coordinates using a lookup table - MathMap - Transform coordinates using mathematical expressions - MatrixMap - Map positions by multiplying them by a matrix - NormMap - Normalise coordinates using a supplied Frame - PcdMap - Apply 2-dimensional pincushion/barrel distortion - PermMap - Coordinate permutation Mapping - PolyMap - General N-dimensional polynomial Mapping - RateMap - Calculates an element of a Mapping's Jacobian matrix - SelectorMap - Locates positions within a set of Regions - ShiftMap - Shifts each axis by a constant amount - SlaMap - Sequence of celestial coordinate conversions - SpecMap - Sequence of spectral coordinate conversions - SphMap - Map 3-d Cartesian to 2-d spherical coordinates - SwitchMap - Encapuslates a set of alternate Mappings - TimeMap - Sequence of time coordinate conversions - TranMap - Combine fwd. and inv. transformations from two Mappings - UnitMap - Unit (null) Mapping - UnitNormMap - Converts a vector to a unit vector plus length - WcsMap - Implement a FITS-WCS sky projection - WinMap - Match windows by scaling and shifting each axis - ZoomMap - Zoom coordinates about the origin -\end{terminalv} -\normalsize - -\cleardoublepage -\section{\label{ss:functiondescriptions}AST Function Descriptions} -\small -\sstroutine{ - astSet -}{ - Set attribute values for an Object -}{ - \sstdescription{ - This function assigns a set of attribute values to an \htmlref{Object}{Object}, - over-riding any previous values. The attributes and their new - values are specified via a character string, which should - contain a comma-separated list of the form: - - \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"} - - where \texttt{"} attribute\_n\texttt{"} specifies an attribute name, and the value - to the right of each \texttt{"} =\texttt{"} sign should be a suitable textual - representation of the value to be assigned. This value will be - interpreted according to the attribute\texttt{'} s data type. - - The string supplied may also contain \texttt{"} printf\texttt{"} -style format - specifiers, identified by \texttt{"} \%\texttt{"} signs in the usual way. If - present, these will be substituted by values supplied as - additional optional arguments (using the normal \texttt{"} printf\texttt{"} rules) - before the string is used. - } - \sstsynopsis{ - void astSet( AstObject $*$this, const char $*$settings, ... ) - } - \sstparameters{ - \sstsubsection{ - this - }{ - Pointer to the Object. - } - \sstsubsection{ - settings - }{ - Pointer to a null-terminated character string containing a - comma-separated list of attribute settings in the form described - above. - } - \sstsubsection{ - ... - }{ - Optional additional arguments which supply values to be - substituted for any \texttt{"} printf\texttt{"} -style format specifiers that - appear in the \texttt{"} settings\texttt{"} string. - } - } - \sstapplicability{ - \sstsubsection{ - Object - }{ - This function applies to all Objects. - } - } - \sstexamples{ - \sstexamplesubsection{ - astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"} ); - }{ - Sets the Report attribute for Object \texttt{"} map\texttt{"} to the value 1 and - the Zoom attribute to 25.0. - } - \sstexamplesubsection{ - astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis ); - }{ - Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"} to a - suitable string, where the axis number is obtained from - \texttt{"} axis\texttt{"} , a variable of type int. - } - \sstexamplesubsection{ - astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring ); - }{ - Sets the Title attribute for Object \texttt{"} frame\texttt{"} to the contents of - the string \texttt{"} mystring\texttt{"} . - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - Attribute names are not case sensitive and may be surrounded - by white space. - - \sstitem - White space may also surround attribute values, where it will - generally be ignored (except for string-valued attributes where - it is significant and forms part of the value to be assigned). - - \sstitem - To include a literal comma in the value assigned to an attribute, - the whole attribute value should be enclosed in quotation markes. - Alternatively, you can use \texttt{"} \%s\texttt{"} format and supply the value as a - separate additional argument to astSet (or use the astSetC - function instead). - - \sstitem - The same procedure may be adopted if \texttt{"} \%\texttt{"} signs are to be included - and are not to be interpreted as format specifiers (alternatively, - the \texttt{"} printf\texttt{"} convention of writing \texttt{"} \%\%\texttt{"} may be used). - - \sstitem - An error will result if an attempt is made to set a value for - a read-only attribute. - } - } -} -\sstroutine{ - astAddColumn -}{ - Add a new column definition to a table -}{ - \sstdescription{ - Adds the definition of a new column to the supplied table. Initially, - the column is empty. Values may be added subsequently using the - methods of the \htmlref{KeyMap}{KeyMap} class. - } - \sstsynopsis{ - void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim, - int $*$dims, const char $*$unit ) - } - \sstparameters{ - \sstsubsection{ - this - }{ - Pointer to the \htmlref{Table}{Table}. - } - \sstsubsection{ - name - }{ - The column name. Trailing spaces are ignored (all other spaces - are significant). The supplied string is converted to upper case. - } - \sstsubsection{ - type - }{ - The data type associated with the column. See \texttt{"} Applicability:\texttt{"} - below. - } - \sstsubsection{ - ndim - }{ - The number of dimensions spanned by the values stored in a single - cell of the column. Zero if the column holds scalar values. - } - \sstsubsection{ - dims - }{ - An array holding the the lengths of each of the axes spanned by - the values stored in a single cell of the column. Ignored if the - column holds scalara values. - } - \sstsubsection{ - unit - }{ - A string specifying the units of the column. Supply a blank - string if the column is unitless. - } - } - \sstapplicability{ - \sstsubsection{ - Table - }{ - Tables can hold columns with any of the following data types - - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for - short int), - AST\_\_BYTETYPE (for - unsigned bytes - i.e. unsigned chars), - AST\_\_DOUBLETYPE (for double - precision floating point), AST\_\_FLOATTYPE (for single - precision floating point), AST\_\_STRINGTYPE (for character string), - AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for - arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values - created by - \htmlref{astMapPutU}{astMapPutU}). - } - \sstsubsection{ - \htmlref{FitsTable}{FitsTable} - }{ - FitsTables can hold columns with any of the following data types - - AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for - short int), - AST\_\_BYTETYPE (for - unsigned bytes - i.e. unsigned chars), - AST\_\_DOUBLETYPE (for double - precision floating point), AST\_\_FLOATTYPE (for single - precision floating point), AST\_\_STRINGTYPE (for character string). - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - This - function - returns without action if a column already exists in the Table - with the supplied name and properties. However an error is - reported if any of the properties differ. - } - } -} -\sstroutine{ - astAddFrame -}{ - Add a Frame to a FrameSet to define a new coordinate system -}{ - \sstdescription{ - This function adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a - \htmlref{FrameSet}{FrameSet} so as to define a new coordinate system, derived from - one which already exists within the FrameSet. The new Frame then - becomes the FrameSet\texttt{'} s current Frame. - - This function - may also be used to merge two FrameSets, or to append extra axes - to every Frame in a FrameSet. - } - \sstsynopsis{ - void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map, - AstFrame $*$frame ) - } - \sstparameters{ - \sstsubsection{ - this - }{ - Pointer to the FrameSet. - } - \sstsubsection{ - iframe - }{ - The index of the Frame within the FrameSet which describes - the coordinate system upon which the new one is to be based. - This value should lie in the range from 1 to the number of - Frames already in the FrameSet (as given by its \htmlref{Nframe}{Nframe} - attribute). As a special case, AST\_\_ALLFRAMES may be supplied, - in which case the axes defined by the supplied Frame are appended - to every Frame in the FrameSet (see the Notes section for details). - } - \sstsubsection{ - map - }{ - Pointer to a Mapping which describes how to convert - coordinates from the old coordinate system (described by the - Frame with index \texttt{"} iframe\texttt{"} ) into coordinates in the new - system. The Mapping\texttt{'} s forward transformation should perform - this conversion, and its inverse transformation should - convert in the opposite direction. The supplied Mapping is ignored - if parameter \texttt{"} iframe\texttt{"} is equal to AST\_\_ALLFRAMES. - } - \sstsubsection{ - frame - }{ - Pointer to a Frame that describes the new coordinate system. - Any class of Frame may be supplied (including Regions and - FrameSets). - - This function may also be used to merge two FrameSets by - supplying a pointer to a second FrameSet for this parameter - (see the Notes section for details). - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - Deep copies of the supplied - \texttt{"} mapping\texttt{"} and \texttt{"} frame\texttt{"} - objects are stored within the modified FrameSet. So any changes made - to the FrameSet after calling this method will have no effect on the - supplied Mapping and Frame objects. - - \sstitem - A value of AST\_\_BASE or AST\_\_CURRENT may be given for the - \texttt{"} iframe\texttt{"} parameter to specify the base Frame or the current - Frame respectively. - - \sstitem - This function sets the value of the \htmlref{Current}{Current} attribute for the - FrameSet so that the new Frame subsequently becomes the current - Frame. - - \sstitem - The number of input coordinate values accepted by the supplied - Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the - Frame identified by the \texttt{"} iframe\texttt{"} parameter. Similarly, the - number of output coordinate values generated by this Mapping - (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new - Frame. - - \sstitem - As a special case, if a pointer to a FrameSet is given for the - \texttt{"} frame\texttt{"} parameter, this is treated as a request to merge a pair of - FrameSets. This is done by appending all the new Frames (in the - \texttt{"} frame\texttt{"} FrameSet) to the original FrameSet, while preserving - their order and retaining all the inter-relationships - (i.e. Mappings) between them. The two sets of Frames are - inter-related within the merged FrameSet by using the Mapping - supplied. This should convert between the Frame identified by - the \texttt{"} iframe\texttt{"} parameter (in the original FrameSet) and the current - Frame of the \texttt{"} frame\texttt{"} FrameSet. This latter Frame becomes the - current Frame in the merged FrameSet. - - \sstitem - As another special case, if a value of AST\_\_ALLFRAMES is supplied - for parameter - \texttt{"} iframe\texttt{"} , - then the supplied Mapping is ignored, and the axes defined by the - supplied Frame are appended to each Frame in the FrameSet. In detail, - each Frame in the FrameSet is replaced by a \htmlref{CmpFrame}{CmpFrame} containing the - original Frame and the Frame specified by parameter - \texttt{"} frame\texttt{"} . - In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap} - containing the original Mapping and a \htmlref{UnitMap}{UnitMap} in parallel. The Nin and - Nout attributes of the UnitMap are set equal to the number of axes - in the supplied Frame. Each new CmpMap is simplified using - \htmlref{astSimplify}{astSimplify} - before being stored in the FrameSet. - } - } -} -\sstroutine{ - astAddParameter -}{ - Add a new global parameter definition to a table -}{ - \sstdescription{ - Adds the definition of a new global parameter to the supplied - table. Note, this does not store a value for the parameter. To get - or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class - should be used, using the name of the parameter as the key. - } - \sstsynopsis{ - void astAddParameter( AstTable $*$this, const char $*$name ) - } - \sstparameters{ - \sstsubsection{ - this - }{ - Pointer to the \htmlref{Table}{Table}. - } - \sstsubsection{ - name - }{ - The parameter name. Trailing spaces are ignored (all other spaces - are significant). The supplied string is converted to upper case. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - Unlike columns, the definition of a parameter does not specify its type, - size or dimensionality. - } - } -} -\sstroutine{ - astAddVariant -}{ - Store a new variant Mapping for the current Frame in a FrameSet -}{ - \sstdescription{ - This function - allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame} - in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"} attribute for more details. It can - also be used to rename the currently selected variant Mapping. - } - \sstsynopsis{ - void astAddVariant( AstFrameSet $*$this, AstMapping $*$map, - const char $*$name ) - } - \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 ) - } - \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} (so long as the Frames encapsulated by - the two NormMaps are equal - i.e. have the same class and the same - attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains - a NormMap, the CmpMap will still cancel with its own inverse. - } - \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, int narg, - 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{ - narg - }{ - The number of argument values supplied in the - \texttt{"} args\texttt{"} array. - } - \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, int narg, - 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{ - narg - }{ - The number of argument values supplied in the - \texttt{"} args\texttt{"} array. - } - \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, int narg, - 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{ - narg - }{ - The number of argument values supplied in the - \texttt{"} args\texttt{"} array. - } - \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 attribute gives a space separated list of the names of all the - variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute - \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the - list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the - current Frame. - } - \sstattributetype{ - String, read-only. - } - \sstapplicability{ - \sstsubsection{ - \htmlref{FrameSet}{FrameSet} - }{ - All FrameSets have this attribute. - } - } -} -\sstroutine{ - AllWarnings -}{ - A list of all currently available condition names -}{ - \sstdescription{ - This read-only attribute is a space separated list of all the conditions - names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed - below. - } - \sstattributetype{ - String, read-only - } - \sstapplicability{ - \sstsubsection{ - \htmlref{FitsChan}{FitsChan} - }{ - All FitsChans have this attribute. - } - } - \sstdiytopic{ - Conditions - }{ - The following conditions are currently recognised (all are - case-insensitive): - - \sstitemlist{ - - \sstitem - \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a - non-Native encoded FitsChan if an unknown celestial co-ordinate - system is specified by the CTYPE keywords. - - \sstitem - \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a - non-Native encoded FitsChan if an illegal algorithm code is specified - by a CTYPE keyword, and the illegal code can be converted to an - equivalent legal code. - - \sstitem - \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is - encountered that contains an illegal character (i.e. one not allowed - by the FITS standard). - - \sstitem - \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword - cannot be determined from the content of the header card. - - \sstitem - \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a - non-Native encoded FitsChan if the latitude of the reference point - has an absolute value greater than 90 degrees. The actual absolute - value used is set to exactly 90 degrees in these cases. - - \sstitem - \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the - transformation from pixel offsets to intermediate world coordinates - cannot be inverted. This matrix describes the scaling, rotation, shear, - etc., applied to the pixel axes, and is specified by keywords such as - PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable - if any rows or columns consist entirely of zeros. The FITS-WCS Paper I - \texttt{"} Representation of World Coordinates in FITS\texttt{"} by Greisen \& Calabretta - requires that this matrix be invertable. Many operations (such as - grid plotting) will not be possible if the matrix cannot be inverted. - - \sstitem - \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a - non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found - that refers to a projection parameter that is not used by the - projection type specified by CTYPE, or the PV values are otherwise - inappropriate for the projection type. - - \sstitem - \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a - non-Native encoded FitsChan if it is not possible to convert the - value of a FITS keywords to the expected type. For instance, this - can occur if the FITS header contains a string value for a keyword - which should have a floating point value, or if the keyword has no - value at all (i.e. is a comment card). - - \sstitem - \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a - non-Native encoded FitsChan if any of the CTYPE keywords specify an - unsupported distortion code using the \texttt{"} 4-3-3\texttt{"} format specified in - FITS-WCS paper IV. Such distortion codes are ignored. - - \sstitem - \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used - within \htmlref{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 change with time - for various reasons, including: (i) changing aberration of light - caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion - around the Sun), (ii) changing gravitational deflection by the Sun - due to changes in the observer\texttt{'} s position with time, (iii) fictitious - motion due to rotation of non-inertial coordinate systems (e.g. the - old FK4 system), and (iv) proper motion of the source itself (although - this last effect is not handled by the SkyFrame class because it - affects individual sources rather than the coordinate system as - a whole). - - The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the - old FK4-based coordinate systems (see the System attribute) and - J2000.0 (Julian) for all others. - - Care must be taken to distinguish the Epoch value, which relates to - motion (or apparent motion) of the source, from the superficially - similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate - system which is itself in motion in a (notionally) predictable way - as a result of being referred to a slowly moving reference plane - (e.g. the equator). - - See the description of the System attribute for details of which - qualifying attributes apply to each celestial coordinate system. - } - \sstsubsection{ - \htmlref{TimeFrame}{TimeFrame} - }{ - A TimeFrame describes a general time axis and so cannot be completely - characterised by a single Epoch value. For this reason the TimeFrame - class makes no use of the Epoch attribute. However, user code can - still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"} - time spanned by the TimeFrame. The default Epoch value for a TimeFrame - will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s - \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin, - then the default Epoch value is J2000.0. - } - } - \sstdiytopic{ - Input Formats - }{ - The formats accepted when setting an Epoch value are listed - below. They are all case-insensitive and are generally tolerant - of extra white space and alternative field delimiters: - - \sstitemlist{ - - \sstitem - Besselian Epoch: Expressed in decimal years, with or without - decimal places (\texttt{"} B1950\texttt{"} or \texttt{"} B1976.13\texttt{"} for example). - - \sstitem - Julian Epoch: Expressed in decimal years, with or without - decimal places (\texttt{"} J2000\texttt{"} or \texttt{"} J2100.9\texttt{"} for example). - - \sstitem - Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"} - for example). Such values are interpreted as a Besselian epoch - (see above) if less than 1984.0 and as a Julian epoch otherwise. - - \sstitem - Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"} for - example). - - \sstitem - Modified Julian Date: With or without decimal places - (\texttt{"} MJD 54321.4\texttt{"} for example). - - \sstitem - Gregorian Calendar Date: With the month expressed either as an - integer or a 3-character abbreviation, and with optional decimal - places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"} or - \texttt{"} 1996-Oct-2.6\texttt{"} for example). If no fractional part of a day is - given, the time refers to the start of the day (zero hours). - - \sstitem - Gregorian Date and Time: Any calendar date (as above) but with - a fraction of a day expressed as hours, minutes and seconds - (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"} for example). The date and time can be - separated by a space or by a \texttt{"} T\texttt{"} (as used by ISO8601 format). - } - } - \sstdiytopic{ - Output Format - }{ - When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"} - format described under \texttt{"} Input Formats\texttt{"} . This is a value in - decimal years which will be a Besselian epoch if less than - 1984.0 and a Julian epoch otherwise. By omitting any character - prefix, this format allows the Epoch value to be obtained as - either a character string or a floating point value. - } -} -\sstroutine{ - Equinox -}{ - Epoch of the mean equinox -}{ - \sstdescription{ - This attribute is used to qualify those celestial coordinate - systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on - the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun) - and/or the Earth\texttt{'} s equator. - - Both of these planes are in motion and their positions are - difficult to specify precisely. In practice, therefore, a model - ecliptic and/or equator are used instead. These, together with - the point on the sky that defines the coordinate origin (the - intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move - with time according to some model which removes the more rapid - fluctuations. The SkyFrame class supports both the FK4 and - FK5 models. - - The position of a fixed source expressed in any of these - coordinate systems will appear to change with time due to - movement of the coordinate system itself (rather than motion of - the source). Such coordinate systems must therefore be - qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"} - or \texttt{"} equinox\texttt{"} for short) which allows the position of the model - coordinate system on the sky to be determined. This is the role - of the Equinox attribute. - - The Equinox attribute is stored as a Modified Julian Date, but - when setting or getting its value you may use the same formats - as for the \htmlref{Epoch}{Epoch} attribute (q.v.). - - The default Equinox value is B1950.0 (Besselian) for the old - FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and - J2000.0 (Julian) for all others. - } - \sstattributetype{ - Floating point. - } - \sstapplicability{ - \sstsubsection{ - SkyFrame - }{ - All SkyFrames have this attribute. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - Care must be taken to distinguish the Equinox value, which - relates to the definition of a time-dependent coordinate system - (based on solar system reference planes which are in motion), - from the superficially similar Epoch value. The latter is used - to qualify coordinate systems where the positions of sources - change with time (or appear to do so) for a variety of other - reasons, such as aberration of light caused by the observer\texttt{'} s - motion, etc. - - \sstitem - See the description of the System attribute for details of - which qualifying attributes apply to each celestial coordinate - system. - } - } -} -\sstroutine{ - Escape -}{ - Allow changes of character attributes within strings? -}{ - \sstdescription{ - This attribute controls the appearance of text strings and numerical - labels drawn by the \htmlref{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 approximation 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 attribute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This - value will change as Frames are added or removed, but will - always be at least one. - } - \sstattributetype{ - Integer, read-only. - } - \sstapplicability{ - \sstsubsection{ - FrameSet - }{ - All FrameSets have this attribute. - } - } -} -\sstroutine{ - Nin -}{ - Number of input coordinates for a Mapping -}{ - \sstdescription{ - This attribute gives the number of coordinate values required to - specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of - dimensions of the space in which the Mapping\texttt{'} s input points - reside). - } - \sstattributetype{ - Integer, read-only. - } - \sstapplicability{ - \sstsubsection{ - Mapping - }{ - All Mappings have this attribute. - } - \sstsubsection{ - \htmlref{CmpMap}{CmpMap} - }{ - If a CmpMap\texttt{'} s component Mappings are joined in series, then - its Nin attribute is equal to the Nin attribute of the first - component (or to the \htmlref{Nout}{Nout} attribute of the second component - if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero). - - If a CmpMap\texttt{'} s component Mappings are joined in parallel, then - its Nin attribute is given by the sum of the Nin attributes - of each component (or to the sum of their Nout attributes if - the CmpMap\texttt{'} s Invert attribute is non-zero). - } - \sstsubsection{ - \htmlref{Frame}{Frame} - }{ - The Nin attribute for a Frame is always equal to the number - of Frame axes (\htmlref{Naxes}{Naxes} attribute). - } - \sstsubsection{ - \htmlref{FrameSet}{FrameSet} - }{ - The Nin attribute of a FrameSet is equal to the number of - axes (Naxes attribute) of its base Frame (as specified by the - FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may - therefore change if a new base Frame is selected. - } - } -} -\sstroutine{ - NiterInverse -}{ - Maximum number of iterations for the iterative inverse transformation -}{ - \sstdescription{ - This attribute controls the iterative inverse transformation - used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero. - - Its value gives the maximum number of iterations of the - Newton-Raphson algorithm to be used for each transformed position. - The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}. - } - \sstattributetype{ - Integer. - } - \sstapplicability{ - \sstsubsection{ - \htmlref{PolyMap}{PolyMap} - }{ - All PolyMaps have this attribute. - } - } -} -\sstroutine{ - Nkey -}{ - Number of unique FITS keywords in a FitsChan -}{ - \sstdescription{ - This attribute gives the total number of unique FITS keywords - stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or - deleted. If no keyword occurrs more than once in the FitsChan, the - \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs - more than once, the Nkey attribute value will be smaller than - the Ncard attribute value. - } - \sstattributetype{ - Integer, read-only. - } - \sstapplicability{ - \sstsubsection{ - FitsChan - }{ - All FitsChans have this attribute. - } - } -} -\sstroutine{ - Nobject -}{ - Number of Objects in class -}{ - \sstdescription{ - This attribute gives the total number of Objects currently in - existence in the same class as the \htmlref{Object}{Object} whose attribute value - is requested. This count does not include Objects which belong - to derived (more specialised) classes. - - This attribute is mainly intended for debugging. It can be used - to detect whether Objects which should have been deleted have, - in fact, been deleted. - } - \sstattributetype{ - Integer, read-only. - } - \sstapplicability{ - \sstsubsection{ - Object - }{ - All Objects have this attribute. - } - } -} -\sstroutine{ - Norm(axis) -}{ - Specifies the plane upon which a Plot3D draws text and markers -}{ - \sstdescription{ - This attribute controls the appearance of text and markers drawn - by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which - text and markers will be drawn by all subsequent invocations of the - \htmlref{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{ - Floating point. - } - \sstapplicability{ - \sstsubsection{ - Frame - }{ - All Frames have this attribute. - } - \sstsubsection{ - SpecFrame - }{ - Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, - it defines the Doppler shift introduced by the observers diurnal - motion around the earths axis, which is needed when converting to - or from the topocentric standard of rest. The maximum velocity - error which can be caused by an incorrect value is 0.5 km/s. The - default value for the attribute is zero. - } - \sstsubsection{ - TimeFrame - }{ - Together with the ObsLon attribute, it is used when converting - between certain time scales (TDB, TCB, LMST, LAST) - } - } -} -\sstroutine{ - ObsLat -}{ - The geodetic latitude of the observer -}{ - \sstdescription{ - This attribute specifies the geodetic latitude of the observer, in - degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame} - class makes no use of this attribute, but specialised subclasses of - Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} - classes use it. The default value is zero. - - The value is stored internally in radians, but is converted to and - from a degrees string for access. Some example input formats are: - \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} , - \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can - optionally be indicated using characters \texttt{"} N\texttt{"} and \texttt{"} S\texttt{"} in place of the - usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the - format \texttt{"} [s]dd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} N\texttt{"} or \texttt{"} S\texttt{"} . - } - \sstattributetype{ - String. - } - \sstapplicability{ - \sstsubsection{ - Frame - }{ - All Frames have this attribute. - } - \sstsubsection{ - SpecFrame - }{ - Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, - it defines the Doppler shift introduced by the observers diurnal - motion around the earths axis, which is needed when converting to - or from the topocentric standard of rest. The maximum velocity - error which can be caused by an incorrect value is 0.5 km/s. The - default value for the attribute is zero. - } - \sstsubsection{ - TimeFrame - }{ - Together with the ObsLon attribute, it is used when converting - between certain time scales (TDB, TCB, LMST, LAST) - } - } -} -\sstroutine{ - ObsLon -}{ - The geodetic longitude of the observer -}{ - \sstdescription{ - This attribute specifies the geodetic (or equivalently, geocentric) - longitude of the observer, in degrees, measured positive eastwards. - See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this - attribute, but specialised subclasses of Frame may use it. For instance, - the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value - is zero. - - The value is stored internally in radians, but is converted to and - from a degrees string for access. Some example input formats are: - \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} , - \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can - optionally be indicated using characters \texttt{"} E\texttt{"} and \texttt{"} W\texttt{"} in place of the - usual \texttt{"} $+$\texttt{"} and \texttt{"} -\texttt{"} . When converting the stored value to a string, the - format \texttt{"} [s]ddd:mm:ss.ss\texttt{"} is used, when \texttt{"} [s]\texttt{"} is \texttt{"} E\texttt{"} or \texttt{"} W\texttt{"} and the - numerical value is chosen to be less than 180 degrees. - } - \sstattributetype{ - String. - } - \sstapplicability{ - \sstsubsection{ - Frame - }{ - All Frames have this attribute. - } - \sstsubsection{ - SpecFrame - }{ - Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes, - it defines the Doppler shift introduced by the observers diurnal - motion around the earths axis, which is needed when converting to - or from the topocentric standard of rest. The maximum velocity - error which can be caused by an incorrect value is 0.5 km/s. The - default value for the attribute is zero. - } - \sstsubsection{ - TimeFrame - }{ - Together with the ObsLon attribute, it is used when converting - between certain time scales (TDB, TCB, LMST, LAST) - } - } -} -\sstroutine{ - PVMax(i) -}{ - Maximum number of FITS-WCS projection parameters -}{ - \sstdescription{ - This attribute specifies the largest legal index for a PV projection - parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the - largest legal value for \texttt{"} m\texttt{"} when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"} attribute). - The axis index is specified by i, and should be in the range 1 to 99. - The value for each axis is determined by the projection type specified - when the WcsMap - is first created using \htmlref{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. - } - \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 to a non-zero value, it - is possible to change this behaviour so that the effect of the offset - coordinate system is not removed when aligning two SkyFrames. - } -} -\sstroutine{ - SkyRefIs -}{ - Selects the nature of the offset coordinate system -}{ - \sstdescription{ - This attribute controls how the values supplied for the SkyRef and - SkyRefP attributes are used. These three attributes together allow - a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin - or pole within the coordinate system specified by the \htmlref{System}{System} attribute, - rather than absolute axis values. SkyRefIs can take one of the - case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"} or \texttt{"} Ignored\texttt{"} . - - If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system - represented by the SkyFrame is modified to put the origin of longitude - and latitude at the position specified by the SkyRef attribute. - - If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented - by the SkyFrame is modified to put the north pole at the position - specified by the SkyRef attribute. - - If SkyRefIs is set to \texttt{"} Ignored\texttt{"} (the default), then any value set for the - SkyRef attribute is ignored, and the SkyFrame represents the coordinate - system specified by the System attribute directly without any rotation. - } - \sstattributetype{ - String. - } - \sstapplicability{ - \sstsubsection{ - SkyFrame - }{ - All SkyFrames have this attribute. - } - } -} -\sstroutine{ - SkyRefP(axis) -}{ - Position on primary meridian of offset coordinate system -}{ - \sstdescription{ - This attribute is used to control the orientation of the offset - coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used, - it should be set to hold the longitude and latitude of a point within - the coordinate system specified by the \htmlref{System}{System} attribute. The offset - coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in - order to put the position supplied for SkyRefP on the zero longitude - meridian. This rotation is about an axis from the centre of the - celestial sphere to the point specified by the SkyRef attribute. - The default value for SkyRefP is usually the north pole (that is, a - latitude of $+$90 degrees in the coordinate system specified by the System - attribute). The exception to this is if the SkyRef attribute is - itself set to either the north or south pole. In these cases the - default for SkyRefP is the origin (that is, a (0,0) in the coordinate - system specified by the System attribute). - - If an integer axis index is included in the attribute name (e.g. - \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single - floating point axis value, in radians, when setting a value for the - attribute, and will be returned in the same form when getting the value - of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"} - or \texttt{"} 2\texttt{"} (the values to use for longitude and latitude axes are - given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes). - - If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then - the attribute value should be supplied as a character string - containing two formatted axis values (an axis 1 value followed by a - comma, followed by an axis 2 value). The same form - will be used when getting the value of the attribute. - } - \sstattributetype{ - Floating point. - } - \sstapplicability{ - \sstsubsection{ - SkyFrame - }{ - All SkyFrames have this attribute. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - If the position given by the SkyRef attribute defines the origin - of the offset coordinate system (that is, if the SkyRefIs attribute - is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations - which will put the supplied SkyRefP position on the zero longitude - meridian. The orientation which is actually used is the one which - gives the SkyRefP position a positive latitude in the offset coordinate - system (the other possible orientation would give the SkyRefP position - a negative latitude). - - \sstitem - An error will be reported if an attempt is made to use a - SkyRefP value which is co-incident with SkyRef or with the point - diametrically opposite to SkyRef on the celestial sphere. The - reporting of this error is deferred until the SkyRef and SkyRefP - attribute values are used within a calculation. - - \sstitem - If the System attribute of the SkyFrame is changed, any position - given for SkyRefP is transformed into the new System. - } - } -} -\sstroutine{ - SkyTol -}{ - The smallest significant shift in sky coordinates -}{ - \sstdescription{ - This attribute indicates the accuracy of the axis values that will - be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two - positions within the SkyFrame is smaller than the value of SkyTol, - then the two positions will (for the puposes indicated below) be - considered to be co-incident. - - This value is used only when constructing the \htmlref{Mapping}{Mapping} between - two different SkyFrames (for instance, when calling - \htmlref{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 stored with current Frame - - \sstitem - \htmlref{Base}{Base}: FrameSet base Frame index - - \sstitem - \htmlref{Current}{Current}: FrameSet current Frame index - - \sstitem - \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet - - \sstitem - \htmlref{Variant}{Variant}: Name of variant mapping in use by current Frame - - } - Every FrameSet also inherits any further attributes that belong - to its current Frame, regardless of that Frame\texttt{'} s class. (For - example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{SkyFrame} class, is - inherited by any FrameSet which has a SkyFrame as its current - Frame.) The set of attributes belonging to a FrameSet may therefore - change when a new current Frame is selected. - } - \sstdiytopic{ - Functions - }{ - In addition to those 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} (so long as the Frames encapsulated by - the two NormMaps are equal - i.e. have the same class and the same - attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains - a NormMap, the CmpMap will still cancel with its own inverse. - } - \sstconstructor{ - \htmlref{astNormMap}{astNormMap} - } - \sstdiytopic{ - Inheritance - }{ - The NormMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The NormMap class does not define any new attributes beyond - those which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The NormMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - NullRegion -}{ - A boundless region within a Frame -}{ - \sstdescription{ - The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}. - If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion - represents a Region containing no points. If the Negated attribute of - a NullRegion is true, the NullRegion represents an infinite Region - (that is, all points in the coordinate system are inside the NullRegion). - } - \sstconstructor{ - \htmlref{astNullRegion}{astNullRegion} - } - \sstdiytopic{ - Inheritance - }{ - The NullRegion class inherits from the Region class. - } - \sstdiytopic{ - Attributes - }{ - The NullRegion class does not define any new attributes beyond - those which are applicable to all Regions. - } - \sstdiytopic{ - Functions - }{ - The NullRegion class does not define any new functions beyond those - which are applicable to all Regions. - } -} -\sstroutine{ - Object -}{ - Base class for all AST Objects -}{ - \sstdescription{ - This class is the base class from which all other classes in the - AST library are derived. It provides all the basic Object - behaviour and Object manipulation facilities required throughout - the library. There is no Object constructor, however, as Objects - on their own are not useful. - } - \sstconstructor{ - None. - } - \sstdiytopic{ - Inheritance - }{ - The Object base class does not inherit from any other class. - } - \sstdiytopic{ - Attributes - }{ - All Objects have the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{Class}{Class}: Object class name - - \sstitem - \htmlref{ID}{ID}: Object identification string - - \sstitem - \htmlref{Ident}{Ident}: Permanent Object identification string - - \sstitem - \htmlref{Nobject}{Nobject}: Number of Objects in class - - \sstitem - \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes - - \sstitem - \htmlref{RefCount}{RefCount}: Count of active Object pointers - - \sstitem - \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes? - } - } - \sstdiytopic{ - Functions - }{ - The following functions may be applied to all Objects: - - \sstitemlist{ - - \sstitem - \htmlref{astAnnul}{astAnnul}: Annul a pointer to an Object - - \sstitem - \htmlref{astBegin}{astBegin}: Begin a new AST context - - \sstitem - \htmlref{astClear}{astClear}: Clear attribute values for an Object - - \sstitem - \htmlref{astClone}{astClone}: Clone a pointer to an Object - - \sstitem - \htmlref{astCopy}{astCopy}: Copy an Object - - \sstitem - \htmlref{astDelete}{astDelete}: Delete an Object - - \sstitem - \htmlref{astEnd}{astEnd}: End an AST context - - \sstitem - \htmlref{astEscapes}{astEscapes}: Control whether graphical escape sequences are removed - - \sstitem - \htmlref{astExempt}{astExempt}: Exempt an Object pointer from AST context handling - - \sstitem - \htmlref{astExport}{astExport}: Export an Object pointer to an outer context - - \sstitem - \htmlref{astGet$<$X$>$}{astGet$<$X$>$}: Get an attribute value for an Object - - \sstitem - \htmlref{astHasAttribute}{astHasAttribute}: Test if an Object has a named attribute - - \sstitem - \htmlref{astImport}{astImport}: Import an Object pointer to the current context - - \sstitem - \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$}: Test class membership - - \sstitem - \htmlref{astLock}{astLock}: Lock an Object for use by the calling thread - - \sstitem - \htmlref{astToString}{astToString}: Create an in-memory serialisation of an Object - - \sstitem - \htmlref{astSame}{astSame}: Do two AST pointers refer to the same Object? - - \sstitem - \htmlref{astSet}{astSet}: Set attribute values for an Object - - \sstitem - \htmlref{astSet$<$X$>$}{astSet$<$X$>$}: Set an attribute value for an Object - - \sstitem - \htmlref{astShow}{astShow}: Display a textual representation of an Object on standard - output - - \sstitem - \htmlref{astTest}{astTest}: Test if an attribute value is set for an Object - - \sstitem - \htmlref{astTune}{astTune}: Set or get an integer AST tuning parameter - - \sstitem - \htmlref{astTuneC}{astTuneC}: Set or get a character AST tuning parameter - - \sstitem - \htmlref{astUnlock}{astUnlock}: Unlock an Object for use by other threads - - \sstitem - \htmlref{astFromString}{astFromString}: Re-create an Object from an in-memory serialisation - - \sstitem - \htmlref{astVersion}{astVersion}: Return the verson of the AST library being used. - } - } -} -\sstroutine{ - PcdMap -}{ - Apply 2-dimensional pincushion/barrel distortion -}{ - \sstdescription{ - A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional - positions to correct for the radial distortion introduced by some - cameras and telescopes. This can take the form either of pincushion - or barrel distortion, and is characterized by a single distortion - coefficient. - - A PcdMap is specified by giving this distortion coefficient and the - coordinates of the centre of the radial distortion. The forward - transformation of a PcdMap applies the distortion: - - RD = R $*$ ( 1 $+$ C $*$ R $*$ R ) - - where R is the undistorted radial distance from the distortion - centre (specified by attribute PcdCen), RD is the radial distance - from the same centre in the presence of distortion, and C is the - distortion coefficient (given by attribute \htmlref{Disco}{Disco}). - - The inverse transformation of a PcdMap removes the distortion - produced by the forward transformation. The expression used to derive - R from RD is an approximate inverse of the expression above. - } - \sstconstructor{ - \htmlref{astPcdMap}{astPcdMap} - } - \sstdiytopic{ - Inheritance - }{ - The PcdMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Mappings, every - PcdMap also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient - - \sstitem - \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion - } - } - \sstdiytopic{ - Functions - }{ - The PcdMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - PermMap -}{ - Coordinate permutation Mapping -}{ - \sstdescription{ - A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates, - and possibly also changes the number of coordinates, between its - input and output. - - In addition to permuting the coordinate order, a PermMap may - also assign constant values to coordinates. This is useful when - the number of coordinates is being increased as it allows fixed - values to be assigned to any new ones. - } - \sstconstructor{ - \htmlref{astPermMap}{astPermMap} - } - \sstdiytopic{ - Inheritance - }{ - The PermMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The PermMap class does not define any new attributes beyond - those which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The PermMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - Plot -}{ - Provide facilities for 2D graphical output -}{ - \sstdescription{ - This class provides facilities for producing 2D graphical output. - A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base - \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"} coordinate system and is - associated with a rectangular plotting area in the underlying - graphics system. This plotting area is where graphical output - appears. It is defined when the Plot is created. - - The current Frame of a Plot describes a \texttt{"} physical\texttt{"} coordinate - system, which is the coordinate system in which plotting - operations are specified. The results of each plotting operation - are automatically transformed into graphical coordinates so as - to appear in the plotting area (subject to any clipping which - may be in effect). - - Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates - may often be non-linear, or even discontinuous, most plotting - does not result in simple straight lines. The basic plotting - element is therefore not a straight line, but a geodesic curve - (see \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve} and \htmlref{astPolyCurve}{astPolyCurve}). A Plot also provides facilities for - drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines - (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with - optional coordinate grids (\htmlref{astGrid}{astGrid}). - A range of Plot attributes is available to allow precise control - over the appearance of graphical output produced by these - functions. - - You may select different physical coordinate systems in which to - plot (including the native graphical coordinate system itself) - by selecting different Frames as the current Frame of a Plot, - using its \htmlref{Current}{Current} attribute. You may also set up clipping (see - \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and - this may be done in any of the coordinate systems associated - with the Plot, not necessarily the one you are plotting in. - - Like any FrameSet, a Plot may also be used as a Frame. In this - case, it behaves like its current Frame, which describes the - physical coordinate system. - - When used as a Mapping, a Plot describes the inter-relation - between graphical coordinates (its base Frame) and physical - coordinates (its current Frame). It differs from a normal - FrameSet, however, in that an attempt to transform points which - lie in clipped areas of the Plot will result in bad coordinate - values (AST\_\_BAD). - } - \sstconstructor{ - \htmlref{astPlot}{astPlot} - } - \sstdiytopic{ - Inheritance - }{ - The Plot class inherits from the FrameSet class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all FrameSets, every - Plot also has the following attributes: - - \sstitemlist{ - - \sstitem - Abbrev: Abbreviate leading fields? - - \sstitem - \htmlref{Border}{Border}: Draw a border around valid regions of a Plot? - - \sstitem - \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary? - - \sstitem - \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR? - - \sstitem - \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element - - \sstitem - \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot? - - \sstitem - \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot? - - \sstitem - \htmlref{Escape}{Escape}: Allow changes of character attributes within strings? - - \sstitem - \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot - - \sstitem - \htmlref{Font(element)}{Font(element)}: Character font for a Plot element - - \sstitem - \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values - - \sstitem - \htmlref{Grf}{Grf}: Select the graphics interface to use. - - \sstitem - \htmlref{Grid}{Grid}: Draw grid lines for a Plot? - - \sstitem - \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink? - - \sstitem - \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot - - \sstitem - \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot? - - \sstitem - \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright? - - \sstitem - \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot - - \sstitem - \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values - - \sstitem - \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically? - - \sstitem - \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically? - - \sstitem - \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot - - \sstitem - \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot - - \sstitem - \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot - - \sstitem - \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot? - - \sstitem - \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot - - \sstitem - \htmlref{Size(element)}{Size(element)}: Character size for a Plot element - - \sstitem - \htmlref{Style(element)}{Style(element)}: Line style for a Plot element - - \sstitem - \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot? - - \sstitem - \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot - - \sstitem - \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot? - - \sstitem - \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title - - \sstitem - \htmlref{Tol}{Tol}: Plotting tolerance - - \sstitem - \htmlref{Width(element)}{Width(element)}: Line width for a Plot element - } - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all FrameSets, the - following functions may also be applied to all Plots: - - \sstitemlist{ - - \sstitem - \htmlref{astBBuf}{astBBuf}: Begin a new graphical buffering context - - \sstitem - \htmlref{astBorder}{astBorder}: Draw a border around valid regions of a Plot - - \sstitem - \htmlref{astBoundingBox}{astBoundingBox}: Returns a bounding box for previously drawn graphics - - \sstitem - \htmlref{astClip}{astClip}: Set up or remove clipping for a Plot - - \sstitem - \htmlref{astCurve}{astCurve}: Draw a geodesic curve - - \sstitem - \htmlref{astEBuf}{astEBuf}: End the current graphical buffering context - - \sstitem - \htmlref{astGenCurve}{astGenCurve}: Draw a generalized curve - - \sstitem - \htmlref{astGetGrfContext}{astGetGrfContext}: Get the graphics context for a Plot - - \sstitem - \htmlref{astGrfPop}{astGrfPop}: Retrieve previously saved graphics functions - - \sstitem - \htmlref{astGrfPush}{astGrfPush}: Save the current graphics functions - - \sstitem - \htmlref{astGrfSet}{astGrfSet}: Register a graphics routine for use by a Plot - - \sstitem - \htmlref{astGrid}{astGrid}: Draw a set of labelled coordinate axes - - \sstitem - \htmlref{astGridLine}{astGridLine}: Draw a grid line (or axis) for a Plot - - \sstitem - \htmlref{astMark}{astMark}: Draw a set of markers for a Plot - - \sstitem - \htmlref{astPolyCurve}{astPolyCurve}: Draw a series of connected geodesic curves - - \sstitem - \htmlref{astRegionOutline}{astRegionOutline}: Draw the outline of an AST \htmlref{Region}{Region} - - \sstitem - \htmlref{astText}{astText}: Draw a text string for a Plot - } - } - \sstdiytopic{ - Graphical Elements - }{ - The colour index, character font, character size, line style and - line width used for plotting can be set independently for - various elements of the graphical output produced by a Plot. - The different graphical elements are identified by appending the - strings listed below as subscripts to the Plot attributes - Colour(element), Font(element), Size(element), Style(element) - and Width(element). These strings are case-insensitive and - unambiguous abbreviations may be used. Elements of the graphical - output which relate to individual axes can be referred to either - independently (e.g. \texttt{"} (Grid1)\texttt{"} and \texttt{"} (Grid2)\texttt{"} ) or together (e.g. - \texttt{"} (Grid)\texttt{"} ): - - \sstitemlist{ - - \sstitem - Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using astGrid - - \sstitem - Axis1: Axis line drawn through tick marks on axis 1 using astGrid - - \sstitem - Axis2: Axis line drawn through tick marks on axis 2 using astGrid - - \sstitem - Border: The Plot border drawn using astBorder, astGrid or astRegionOutline - - \sstitem - Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve - - \sstitem - Grid: Grid lines drawn using astGridLine or astGrid - - \sstitem - Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid - - \sstitem - Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid - - \sstitem - Markers: Graphical markers (symbols) drawn using astMark - - \sstitem - NumLab: Numerical axis labels drawn using astGrid - - \sstitem - NumLab1: Numerical labels for axis 1 drawn using astGrid - - \sstitem - NumLab2: Numerical labels for axis 2 drawn using astGrid - - \sstitem - Strings: Text strings drawn using astText - - \sstitem - TextLab: Descriptive axis labels drawn using astGrid - - \sstitem - TextLab1: Descriptive label for axis 1 drawn using astGrid - - \sstitem - TextLab2: Descriptive label for axis 2 drawn using astGrid - - \sstitem - Ticks: Tick marks (both major and minor) drawn using astGrid - - \sstitem - Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid - - \sstitem - Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid - - \sstitem - \htmlref{Title}{Title}: The Plot title drawn using astGrid - } - } -} -\sstroutine{ - Plot3D -}{ - Provide facilities for 3D graphical output -}{ - \sstdescription{ - A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities - for producing 3D graphical output, including fully annotated 3D - coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional - \texttt{"} graphical\texttt{"} coordinate system. The axes of this coordinate system are - assumed to be right-handed (that is, if X appears horizontally to the - right and Y vertically upwards, then Z is out of the screen towards - the viewer), and are assumed to be equally scaled (that is, the same - units are used to measure positions on each of the 3 axes). The upper - and lower bounds of a volume within this graphical coordinate system - is specified when the Plot3D is created, and all subsequent graphics - are \texttt{"} drawn\texttt{"} in this volume. - - The Plot3D class does not itself include any ability to draw on a - graphics device. Instead it calls upon function in an externally - supplied module (the \texttt{"} grf3d\texttt{"} module) to do the required drawing. - A module should be written that implements the functions of the - grf3d interface using the facilities of a specific graphics system - This module should then be linked into the application so that the - Plot3D class can use its functions (see the description of the - \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface - defines a few simple functions for drawing primitives such as straight - lines, markers and character strings. These functions all accept - positions in the 3D graphics coordinate system (the base Frame of the - Plot3D), and so the grf3d module must also manage the projection of - these 3D coordinates onto the 2D viewing surface, including the choice - of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"} position, direction of viewing, etc. The AST - library includes a sample implementation of the grf3d interface - based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This - implementation also serves to document the grf3d interface itself and - should be consulted for details before writing a new implementation. - - The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"} 3-dimensional - coordinate system, which is the coordinate system in which plotting - operations are specified when invoking the methods of the Plot3D - class. The results of each plotting operation are automatically - transformed into 3D graphical coordinates before being plotted - using the facilities of the grf3d module linked into the application. - Note, at least one of the three axes of the current Frame must be - independent of the other two current Frame axes. - - You may select different physical coordinate systems in which to - plot (including the native graphical coordinate system itself) - by selecting different Frames as the current Frame of a Plot3D, - using its \htmlref{Current}{Current} attribute. - - Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this - case, it behaves like its current Frame, which describes the - physical coordinate system. - - When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation - between 3D graphical coordinates (its base Frame) and 3D physical - coordinates (its current Frame). - - Although the Plot3D class inherits from the Plot class, several of - the facilities of the Plot class are not available in the Plot3D - class, and an error will be reported if any attempt is made to use - them. Specifically, the Plot3D class does not support clipping - using the - \htmlref{astClip}{astClip} function. - Nor does it support the specification of graphics primitive functions - at run-time using the - \htmlref{astGrfSet}{astGrfSet}, \htmlref{astGrfPop}{astGrfPop}, \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGetGrfContext}{astGetGrfContext} functions. - } - \sstconstructor{ - \htmlref{astPlot3D}{astPlot3D} - } - \sstdiytopic{ - Inheritance - }{ - The Plot3D class inherits from the Plot class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Plots, every - Plot3D also has the following attributes: - - \sstitemlist{ - - \sstitem - Norm: Normal vector defining the 2D plane used for text and markers - - \sstitem - \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated. - - } - Some attributes of the Plot class refer to specific physical - coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic - Plot, the axis index must be 1 or 2, but for a Plot3D the axis index - can be 1, 2 or 3. - - Certain Plot attributes are ignored by the Plot3D class (e.g. Edge, - \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation - for details. All other Plot attributes can be set for a specific - plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"} - or \texttt{"} \_YZ\texttt{"} to the end of the Plot attribute name. For instance, - \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"} refers to the \texttt{"} Grid\texttt{"} attribute for the plane spanning - the second (Y) and third (Z) axes of the 3-d plot. - } - \sstdiytopic{ - Functions - }{ - The Plot3D class does not define any new functions beyond those - which are applicable to all Plots. Note, however, that the - following methods inherited from the Plot class cannot be used with - a Plot3D and will report an error if called: - \sstitemlist{ - - \sstitem - \htmlref{astBoundingBox}{astBoundingBox}, astClip, \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve}, - astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, \htmlref{astGridLine}{astGridLine}, - \htmlref{astPolyCurve}{astPolyCurve}. - } - } -} -\sstroutine{ - PointList -}{ - A collection of points in a Frame -}{ - \sstdescription{ - The PointList class implements a \htmlref{Region}{Region} which represents a collection - of points in a \htmlref{Frame}{Frame}. - } - \sstconstructor{ - \htmlref{astPointList}{astPointList} - } - \sstdiytopic{ - Inheritance - }{ - The PointList class inherits from the Region class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Regions, every - PointList also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList - } - } - \sstdiytopic{ - Functions - }{ - The PointList class does not define any new functions beyond those - which are applicable to all Regions. - } -} -\sstroutine{ - PolyMap -}{ - Map coordinates using polynomial functions -}{ - \sstdescription{ - A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial - transformation. Each output coordinate is a polynomial function of - all the input coordinates. The coefficients are specified separately - for each output coordinate. The forward and inverse transformations - are defined independantly by separate sets of coefficients. If no - inverse transformation is supplied, an iterative method can be used - to evaluate the inverse based only on the forward transformation. - } - \sstconstructor{ - \htmlref{astPolyMap}{astPolyMap} - } - \sstdiytopic{ - Inheritance - }{ - The PolyMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Mappings, every - PolyMap also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation? - - \sstitem - \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse - - \sstitem - \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse - } - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Objects, the - following functions may also be applied to all Mappings: - - \sstitemlist{ - - \sstitem - \htmlref{astPolyTran}{astPolyTran}: Fit a PolyMap inverse or forward transformation - } - } -} -\sstroutine{ - Polygon -}{ - A polygonal region within a 2-dimensional Frame -}{ - \sstdescription{ - The Polygon class implements a polygonal area, defined by a - collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices - are connected together by geodesic curves within the encapsulated Frame. - For instance, if the encapsulated Frame is a simple Frame then the - geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then - the geodesics will be great circles. Note, the vertices must be - supplied in an order such that the inside of the polygon is to the - left of the boundary as the vertices are traversed. Supplying them - in the reverse order will effectively negate the polygon. - - Within a SkyFrame, neighbouring vertices are always joined using the - shortest path. Thus if an edge of 180 degrees or more in length is - required, it should be split into section each of which is less - than 180 degrees. The closed path joining all the vertices in order - will divide the celestial sphere into two disjoint regions. The - inside of the polygon is the region which is circled in an - anti-clockwise manner (when viewed from the inside of the celestial - sphere) when moving through the list of vertices in the order in - which they were supplied when the Polygon was created (i.e. the - inside is to the left of the boundary when moving through the - vertices in the order supplied). - } - \sstconstructor{ - \htmlref{astPolygon}{astPolygon} - } - \sstdiytopic{ - Inheritance - }{ - The Polygon class inherits from the \htmlref{Region}{Region} class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Regions, every - Polygon also has the following attributes: - \sstitemlist{ - - \sstitem - \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices? - } - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Regions, the - following functions may also be applied to all Polygons: - - \sstitemlist{ - - \sstitem - \htmlref{astDownsize}{astDownsize}: Reduce the number of vertices in a Polygon. - - \sstitem - \htmlref{astConvex$<$X$>$}{astConvex$<$X$>$}: Create a Polygon giving the convex hull of a pixel array - - \sstitem - \htmlref{astOutline$<$X$>$}{astOutline$<$X$>$}: Create a Polygon outlining values in a pixel array - } - } -} -\sstroutine{ - Prism -}{ - An extrusion of a region into higher dimensions -}{ - \sstdescription{ - A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region - into one or more orthogonal dimensions (specified by another Region). - If the Region to be extruded has N axes, and the Region defining the - extrusion has M axes, then the resulting Prism will have (M$+$N) axes. - A point is inside the Prism if the first N axis values correspond to - a point inside the Region being extruded, and the remaining M axis - values correspond to a point inside the Region defining the extrusion. - - As an example, a cylinder can be represented by extruding an existing - \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the - Interval would have a single axis and would specify the upper and - lower limits of the cylinder along its length. - } - \sstconstructor{ - \htmlref{astPrism}{astPrism} - } - \sstdiytopic{ - Inheritance - }{ - The Prism class inherits from the Region class. - } - \sstdiytopic{ - Attributes - }{ - The Prism class does not define any new attributes beyond those - which are applicable to all Regions. - } - \sstdiytopic{ - Functions - }{ - The Prism class does not define any new functions beyond those - which are applicable to all Regions. - } -} -\sstroutine{ - RateMap -}{ - Mapping which represents differentiation -}{ - \sstdescription{ - A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the - Jacobian matrix of another Mapping. The Mapping for which the - Jacobian is required is specified when the new RateMap is created, - and is referred to as the \texttt{"} encapsulated Mapping\texttt{"} below. - - The number of inputs to a RateMap is the same as the number of inputs - to its encapsulated Mapping. The number of outputs from a RateMap - is always one. This one output equals the rate of change of a - specified output of the encapsulated Mapping with respect to a - specified input of the encapsulated Mapping (the input and output - to use are specified when the RateMap is created). - - A RateMap which has not been inverted does not define an inverse - transformation. If a RateMap has been inverted then it will define - an inverse transformation but not a forward transformation. - } - \sstconstructor{ - \htmlref{astRateMap}{astRateMap} - } - \sstdiytopic{ - Inheritance - }{ - The RateMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The RateMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The RateMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - Region -}{ - Represents a region within a coordinate system -}{ - \sstdescription{ - This class provides the basic facilities for describing a region within - a specified coordinate system. However, the Region class does not - have a constructor function of its own, as it is simply a container - class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc, - which implement Regions with particular shapes. - - All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region - is created. This Frame describes the coordinate system in which the - Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"} below. - Constructors will also typically required one or more positions to be - supplied which define the location and extent of the region. These - positions must be supplied within the encapsulated Frame. - - The Region class inherits from the Frame class, and so a Region can be - supplied where-ever a Frame is expected. In these cases, supplying a - Region is equivalent to supplying a reference to its encapsulated Frame. - Thus all the methods of the Frame class can be used on the Region class. - For instance, the - \htmlref{astFormat}{astFormat} function - may be used on a Region to format an axis value. - - In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort - of Mapping. Transforming positions by supplying a Region to one of the - astTran$<$X$>$ functions - is the way to determine if a given position is inside or outside the - Region. When used as a Mapping, most classes of Frame are equivalent to - a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a - Region acts like a UnitMap only for input positions which are within the - area represented by the Region. Input positions which are outside the - area produce bad output values (i.e. the output values are equal to - AST\_\_BAD). This behaviour is the same for both the forward and the - inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"} - is not a true inverse of the forward transformation, since applying - the forward transformation to a point outside the Region, and then - applying the inverse transformation results, in a set of AST\_\_BAD axis - values rather than the original axis values. If required, the - \htmlref{astRemoveRegions}{astRemoveRegions} - function can be used to remove the \texttt{"} masking\texttt{"} effect of any Regions - contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by - replacing each Region with a UnitMap or equivalent Frame (depending - on the context in which the Region is used). - - If the coordinate system represented by the Region is changed (by - changing the values of one or more of the attribute which the Region - inherits from its encapsulated Frame), the area represented by - the Region is mapped into the new coordinate system. For instance, let\texttt{'} s - say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being - supplied to the constructor so that the Circle describes a circular - area on the sky in FK4 equatorial coordinates. Since Region inherits - from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute - will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then - changed from FK4 to FK5, the circular area represented by the Region - will automatically be mapped from the FK4 system into the FK5 system. - In general, changing the coordinate system in this way may result in the - region changing shape - for instance, a circle may change into an - ellipse if the transformation from the old to the new coordinate system - is linear but with different scales on each axis. Thus the specific - class of a Region cannot be used as a guarantee of the shape in any - particular coordinate system. If the - \htmlref{astSimplify}{astSimplify} function - is used on a Region, it will endeavour to return a new Region of - a sub-class which accurately describes the shape in the current - coordinate system of the Region (but this may not always be possible). - - It is possible to negate an existing Region so that it represents all - areas of the encapsulated Frame except for the area specified when - the Region was created. - } - \sstconstructor{ - None. - } - \sstdiytopic{ - Inheritance - }{ - The Region class inherits from the Frame class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Frames, every - Region also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system? - - \sstitem - \htmlref{Negated}{Negated}: Has the original region been negated? - - \sstitem - \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region? - - \sstitem - \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region - - \sstitem - \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest - - \sstitem - \htmlref{Bounded}{Bounded}: Is the Region bounded? - - } - Every Region also inherits any further attributes that belong - to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For - example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is - inherited by any Region which represents a SkyFrame.) - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Frames, the - following functions may also be applied to all Regions: - - \sstitemlist{ - - \sstitem - \htmlref{astGetRegionBounds}{astGetRegionBounds}: Get the bounds of a Region - - \sstitem - \htmlref{astGetRegionFrame}{astGetRegionFrame}: Get a copy of the Frame represent by a Region - - \sstitem - \htmlref{astGetRegionFrameSet}{astGetRegionFrameSet}: Get a copy of the Frameset encapsulated by a Region - - \sstitem - \htmlref{astGetRegionMesh}{astGetRegionMesh}: Get a mesh of points covering a Region - - \sstitem - \htmlref{astGetRegionPoints}{astGetRegionPoints}: Get the positions that define a Region - - \sstitem - \htmlref{astGetUnc}{astGetUnc}: Obtain uncertainty information from a Region - - \sstitem - \htmlref{astMapRegion}{astMapRegion}: Transform a Region into a new coordinate system - - \sstitem - \htmlref{astNegate}{astNegate}: Toggle the value of the Negated attribute - - \sstitem - \htmlref{astOverlap}{astOverlap}: Determines the nature of the overlap between two Regions - - \sstitem - \htmlref{astMask$<$X$>$}{astMask$<$X$>$}: Mask a region of a data grid - - \sstitem - \htmlref{astSetUnc}{astSetUnc}: Associate a new uncertainty with a Region - - \sstitem - \htmlref{astShowMesh}{astShowMesh}: Display a mesh of points on the surface of a Region - } - } -} -\sstroutine{ - SelectorMap -}{ - A Mapping that locates positions within one of a set of alternate - Regions -}{ - \sstdescription{ - A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains - a given input position. - - A SelectorMap encapsulates a number of Regions that all have the same - number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of - inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes - spanned by one of the encapsulated Region. All SelectorMaps have only - a single output. SelectorMaps do not define an inverse transformation. - - For each input position, the forward transformation of a SelectorMap - searches through the encapsulated Regions (in the order supplied when - the SelectorMap was created) until a Region is found which contains - the input position. The index associated with this Region is - returned as the SelectorMap output value (the index value is the - position of the Region within the list of Regions supplied when the - SelectorMap was created, starting at 1 for the first Region). If an - input position is not contained within any Region, a value of zero is - returned by the forward transformation. - - If a compound Mapping contains a SelectorMap in series with its own - inverse, the combination of the two adjacent SelectorMaps will be - replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using - \htmlref{astSimplify}{astSimplify}. - - In practice, SelectorMaps are often used in conjunction with SwitchMaps. - } - \sstconstructor{ - \htmlref{astSelectorMap}{astSelectorMap} - } - \sstdiytopic{ - Inheritance - }{ - The SelectorMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The SelectorMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The SelectorMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - ShiftMap -}{ - Add a constant value to each coordinate -}{ - \sstdescription{ - A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a - specified constant value. - } - \sstconstructor{ - \htmlref{astShiftMap}{astShiftMap} - } - \sstdiytopic{ - Inheritance - }{ - The ShiftMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The ShiftMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The ShiftMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - SkyAxis -}{ - Store celestial axis information -}{ - \sstdescription{ - The SkyAxis class is used to store information associated with a - particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST - library and has no constructor function. You should encounter it - only within textual output (e.g. from \htmlref{astWrite}{astWrite}). - } - \sstconstructor{ - None. - } - \sstdiytopic{ - Inheritance - }{ - The SkyAxis class inherits from the \htmlref{Axis}{Axis} class. - } -} -\sstroutine{ - SkyFrame -}{ - Celestial coordinate system description -}{ - \sstdescription{ - A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes - celestial longitude/latitude coordinate systems. The particular - celestial coordinate system to be represented is specified by - setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default - is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or - an \htmlref{Epoch}{Epoch}. - - For each of the supported celestial coordinate systems, a SkyFrame - can apply an optional shift of origin to create a coordinate system - representing offsets within the celestial coordinate system from some - specified reference point. This offset coordinate system can also be - rotated to define new longitude and latitude axes. See attributes - SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. - - All the coordinate values used by a SkyFrame are in - radians. These may be formatted in more conventional ways for - display by using \htmlref{astFormat}{astFormat}. - For a SkyFrame, the Unit attribute describes the formatted value of - a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a - formatted axis value contains colon-separated fields for hours, minutes - and seconds. On the other hand, the InternalUnit attribute for a - SkyFrame is always set to \texttt{"} rad\texttt{"} (i.e. radians), indicating that the - unformatted (i.e. floating point) axis values used by application code - are always in units of radians - } - \sstconstructor{ - \htmlref{astSkyFrame}{astSkyFrame} - } - \sstdiytopic{ - Inheritance - }{ - The SkyFrame class inherits from the Frame class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Frames, every - SkyFrame also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system? - - \sstitem - \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times? - - \sstitem - \htmlref{Equinox}{Equinox}: Epoch of the mean equinox - - \sstitem - IsLatAxis: Is the specified axis the latitude axis? - - \sstitem - IsLonAxis: Is the specified axis the longitude axis? - - \sstitem - \htmlref{LatAxis}{LatAxis}: Index of the latitude axis - - \sstitem - \htmlref{LonAxis}{LonAxis}: Index of the longitude axis - - \sstitem - \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]? - - \sstitem - \htmlref{Projection}{Projection}: Sky projection description. - - \sstitem - SkyRef: Position defining location of the offset coordinate system - - \sstitem - \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system - - \sstitem - SkyRefP: Position defining orientation of the offset coordinate system - - \sstitem - \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates - } - } - \sstdiytopic{ - Functions - }{ - In addition to those - functions - applicable to all Frames, the following - functions - may also be applied to all SkyFrames: - - \sstitemlist{ - - \sstitem - \htmlref{astSkyOffsetMap}{astSkyOffsetMap}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates - } - } -} -\sstroutine{ - SlaMap -}{ - Sequence of celestial coordinate conversions -}{ - \sstdescription{ - An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to - represent a sequence of conversions between standard celestial - (longitude, latitude) coordinate systems. - - When an SlaMap is first created, it simply performs a unit - (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd} - function, a series of coordinate conversion steps may then be - added, selected from those provided by the SLALIB Positional - Astronomy Library (Starlink User Note SUN/67). This allows - multi-step conversions between a variety of celestial coordinate - systems to be assembled out of the building blocks provided by - SLALIB. - - For details of the individual coordinate conversions available, - see the description of the astSlaAdd function. - } - \sstconstructor{ - \htmlref{astSlaMap}{astSlaMap} (also see astSlaAdd) - } - \sstdiytopic{ - Inheritance - }{ - The SlaMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The SlaMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Mappings, the - following function may also be applied to all SlaMaps: - - \sstitemlist{ - - \sstitem - \htmlref{astSlaAdd}{astSlaAdd}: Add a celestial coordinate conversion to an SlaMap - } - } -} -\sstroutine{ - SpecFluxFrame -}{ - Compound spectrum/flux Frame -}{ - \sstdescription{ - A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single - 2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used - to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents - spectral position and the second axis represents flux. - } - \sstconstructor{ - \htmlref{astSpecFluxFrame}{astSpecFluxFrame} - } - \sstdiytopic{ - Inheritance - }{ - The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class. - } - \sstdiytopic{ - Attributes - }{ - The SpecFluxFrame class does not define any new attributes beyond - those which are applicable to all CmpFrames. However, the attributes - of the component Frames can be accessed as if they were attributes - of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise - the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"} attribute and forward access requests to the component - SpecFrame. An axis index can optionally be appended to the end of any - attribute name, in which case the request to access the attribute will - be forwarded to the primary Frame defining the specified axis. - } - \sstdiytopic{ - Functions - }{ - The SpecFluxFrame class does not define any new functions beyond those - which are applicable to all CmpFrames. - } -} -\sstroutine{ - SpecFrame -}{ - Spectral coordinate system description -}{ - \sstdescription{ - A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which - represents various coordinate systems used to describe positions within - an electro-magnetic spectrum. The particular coordinate system to be - used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the - default is wavelength) qualified, as necessary, by other attributes - such as the rest frequency, the standard of rest, the epoch of - observation, units, etc (see the description of the System attribute - for details). - - By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made - to represent offsets from a given spectral position, rather than absolute - spectral values. - } - \sstconstructor{ - \htmlref{astSpecFrame}{astSpecFrame} - } - \sstdiytopic{ - Inheritance - }{ - The SpecFrame class inherits from the Frame class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Frames, every - SpecFrame also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system? - - \sstitem - \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames - - \sstitem - \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000) - - \sstitem - \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000) - - \sstitem - \htmlref{RestFreq}{RestFreq}: Rest frequency - - \sstitem - \htmlref{SourceSys}{SourceSys}: Source velocity spectral system - - \sstitem - \htmlref{SourceVel}{SourceVel}: Source velocity - - \sstitem - \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame - - \sstitem - \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values - - \sstitem - \htmlref{StdOfRest}{StdOfRest}: Standard of rest - - } - Several of the Frame attributes inherited by the SpecFrame class - refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, - \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional, - it allows these attributes to be specified without an axis index. - So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Frames, the - following functions may also be applied to all SpecFrames: - - \sstitemlist{ - - \sstitem - \htmlref{astSetRefPos}{astSetRefPos}: Set reference position in any celestial system - - \sstitem - \htmlref{astGetRefPos}{astGetRefPos}: Get reference position in any celestial system - } - } -} -\sstroutine{ - SpecMap -}{ - Sequence of spectral coordinate conversions -}{ - \sstdescription{ - A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to - represent a sequence of conversions between standard spectral - coordinate systems. - - When an SpecMap is first created, it simply performs a unit - (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} - function, a series of coordinate conversion steps may then be - added. This allows multi-step conversions between a variety of - spectral coordinate systems to be assembled out of a set of building - blocks. - - Conversions are available to transform between standards of rest. - Such conversions need to know the source position as an RA and DEC. - This information can be supplied in the form of parameters for - the relevant conversions, in which case the SpecMap is 1-dimensional, - simply transforming the spectral axis values. This means that the - same source position will always be used by the SpecMap. However, this - may not be appropriate for an accurate description of a 3-D spectral - cube, where changes of spatial position can produce significant - changes in the Doppler shift introduced when transforming between - standards of rest. For this situation, a 3-dimensional SpecMap can - be created in which axes 2 and 3 correspond to the source RA and DEC - The SpecMap simply copies values for axes 2 and 3 from input to - output), but modifies axis 1 values (the spectral axis) appropriately. - - For details of the individual coordinate conversions available, - see the description of the astSpecAdd function. - } - \sstconstructor{ - \htmlref{astSpecMap}{astSpecMap} (also see astSpecAdd) - } - \sstdiytopic{ - Inheritance - }{ - The SpecMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The SpecMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Mappings, the - following function may also be applied to all SpecMaps: - - \sstitemlist{ - - \sstitem - \htmlref{astSpecAdd}{astSpecAdd}: Add a spectral coordinate conversion to an SpecMap - } - } -} -\sstroutine{ - SphMap -}{ - Map 3-d Cartesian to 2-d spherical coordinates -}{ - \sstdescription{ - A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a - 3-dimensional Cartesian coordinate system into a 2-dimensional - spherical coordinate system (longitude and latitude on a unit - sphere centred at the origin). It works by regarding the input - coordinates as position vectors and finding their intersection - with the sphere surface. The inverse transformation always - produces points which are a unit distance from the origin - (i.e. unit vectors). - } - \sstconstructor{ - \htmlref{astSphMap}{astSphMap} - } - \sstdiytopic{ - Inheritance - }{ - The SphMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Mappings, every - SphMap also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere? - - \sstitem - \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole - } - } - \sstdiytopic{ - Functions - }{ - The SphMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - Stc -}{ - Represents an instance of the IVOA STC class -}{ - \sstdescription{ - The Stc class is an implementation of the IVOA STC class which forms - part of the IVOA Space-Time Coordinate Metadata system. See: - - http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html - - The Stc class does not have a constructor function of its own, as it - is simply a container class for a family of specialised sub-classes - including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation} - and \htmlref{StcObsDataLocation}{StcObsDataLocation}. - } - \sstconstructor{ - astStc - } - \sstdiytopic{ - Inheritance - }{ - The Stc class inherits from the \htmlref{Region}{Region} class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Regions, every - Stc also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region. - } - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Regions, the - following functions may also be applied to all Stc\texttt{'} s: - - \sstitemlist{ - - \sstitem - \htmlref{astGetStcRegion}{astGetStcRegion}: Get a pointer to the encapsulated Region - - \sstitem - \htmlref{astGetStcCoord}{astGetStcCoord}: Get information about an AstroCoords element - - \sstitem - \htmlref{astGetStcNCoord}{astGetStcNCoord}: Returns the number of AstroCoords elements in an Stc - } - } -} -\sstroutine{ - StcCatalogEntryLocation -}{ - Correspond to the IVOA STCCatalogEntryLocation class -}{ - \sstdescription{ - The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe - the coverage of the datasets contained in some VO resource. - - See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html - } - \sstconstructor{ - \htmlref{astStcCatalogEntryLocation}{astStcCatalogEntryLocation} - } - \sstdiytopic{ - Inheritance - }{ - The StcCatalogEntryLocation class inherits from the Stc class. - } - \sstdiytopic{ - Attributes - }{ - The StcCatalogEntryLocation class does not define any new attributes beyond - those which are applicable to all Stcs. - } - \sstdiytopic{ - Functions - }{ - The StcCatalogEntryLocation class does not define any new functions beyond those - which are applicable to all Stcs. - } -} -\sstroutine{ - StcObsDataLocation -}{ - Correspond to the IVOA ObsDataLocation class -}{ - \sstdescription{ - The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe - the coordinate space occupied by a particular observational dataset. - - See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html - - An STC ObsDataLocation element specifies the extent of the - observation within a specified coordinate system, and also specifies - the observatory location within a second coordinate system. - - The AST StcObsDataLocation class inherits from Stc, and therefore - an StcObsDataLocation can be used directly as an Stc. When used - in this way, the StcObsDataLocation describes the location of the - observation (not the observatory). - - Eventually, this class will have a method for returning an Stc - describing the observatory location. However, AST currently does not - include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar - system positions. Therefore, the provision for returning observatory - location as an Stc is not yet available. However, for terrestrial - observations, the position of the observatory can still be recorded - using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated - within the Stc representing the observation location (this assumes - the observatory is located at sea level). - } - \sstconstructor{ - \htmlref{astStcObsDataLocation}{astStcObsDataLocation} - } - \sstdiytopic{ - Inheritance - }{ - The StcObsDataLocation class inherits from the Stc class. - } - \sstdiytopic{ - Attributes - }{ - The StcObsDataLocation class does not define any new attributes beyond - those which are applicable to all Stcs. - } - \sstdiytopic{ - Functions - }{ - The StcObsDataLocation class does not define any new functions beyond those - which are applicable to all Stcs. - } -} -\sstroutine{ - StcResourceProfile -}{ - Correspond to the IVOA STCResourceProfile class -}{ - \sstdescription{ - The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe - the coverage of the datasets contained in some VO resource. - - See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html - } - \sstconstructor{ - \htmlref{astStcResourceProfile}{astStcResourceProfile} - } - \sstdiytopic{ - Inheritance - }{ - The StcResourceProfile class inherits from the Stc class. - } - \sstdiytopic{ - Attributes - }{ - The StcResourceProfile class does not define any new attributes beyond - those which are applicable to all Stcs. - } - \sstdiytopic{ - Functions - }{ - The StcResourceProfile class does not define any new functions beyond those - which are applicable to all Stcs. - } -} -\sstroutine{ - StcSearchLocation -}{ - Correspond to the IVOA SearchLocation class -}{ - \sstdescription{ - The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe - the coverage of a query. - - See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html - } - \sstconstructor{ - \htmlref{astStcSearchLocation}{astStcSearchLocation} - } - \sstdiytopic{ - Inheritance - }{ - The StcSearchLocation class inherits from the Stc class. - } - \sstdiytopic{ - Attributes - }{ - The StcSearchLocation class does not define any new attributes beyond - those which are applicable to all Stcs. - } - \sstdiytopic{ - Functions - }{ - The StcSearchLocation class does not define any new functions beyond those - which are applicable to all Stcs. - } -} -\sstroutine{ - StcsChan -}{ - I/O Channel using STC-S to represent Objects -}{ - \sstdescription{ - A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S - I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using - \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an - STC-S description of that Object, and reading from an StcsChan will - create a new Object from its STC-S description. - - When an STC-S description is read using - \htmlref{astRead}{astRead}, - the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC - AstroCoords (i.e. a single point of interest within the coordinate frame - described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC - AstrCoordsArea (i.e. an area or volume of interest within the coordinate - frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap} - containing the uninterpreted property values read form the STC-S - description, or 4) a KeyMap containing any combination of the first - 3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} - control which of the above is returned by - astRead. - - When an STC-S description is created from an AST Object using - astWrite, - the AST Object must be either a Region or a KeyMap. If it is a - Region, it is assumed to define the AstroCoordsArea or (if the - Region is a single point) the AstroCoords to write to the STC-S - description. If the Object is a KeyMap, it may contain an entry - with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the - AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} , - holding a Region (a PointList) to be used to create the - AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding - a KeyMap that contains uninterpreted property values to be used as - defaults for any STC-S properties that are not determined by the - other supplied Regions. In addition, a KeyMap supplied to - astWrite - may itself hold the default STC-S properties (rather than defaults - being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"} entry in the - supplied KeyMap). - - The - astRead and astWrite - functions work together so that any Object returned by - astRead can immediately be re-written using astWrite. - - Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"} - and \texttt{"} sink\texttt{"} functions which connect it to an external data store - by reading and writing the resulting text. These functions - should perform any conversions needed between external character - encodings and the internal ASCII encoding. If no such functions - are supplied, a Channel will read from standard input and write - to standard output. - - Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from - specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, - in which case no sink or source function need be supplied. - - Support for STC-S is currently based on the IVOA document \texttt{"} STC-S: - Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} , - version 1.30 (dated 5th December 2007), available at - http://www.ivoa.net/Documents/latest/STC-S.html. Note, this - document is a recommednation only and does not constitute an accepted - IVOA standard. - - The full text of version 1.30 is supported by the StcsChan class, - with the following exceptions and provisos: - - \sstitemlist{ - - \sstitem - When reading an STC-S phrase, case is ignored except when reading - units strings. - - \sstitem - There is no support for multiple intervals specified within a - TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval. - - \sstitem - If the ET timescale is specified, TT is used instead. - - \sstitem - If the TEB timescale is specified, TDB is used instead. - - \sstitem - The LOCAL timescale is not supported. - - \sstitem - The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a - reference position to be specified. Consequently, any $<$refpos$>$ - specified within the Time or Space sub-phrase of an STC-S document - is ignored. - - \sstitem - The Convex identifier for the space sub-phrase is not supported. - - \sstitem - The GEO\_C and GEO\_D space frames are not supported. - - \sstitem - The UNITSPHERE and SPHER3 space flavours are not supported. - - \sstitem - If any Error values are supplied in a space sub-phrase, then the - number of values supplied should equal the number of spatial axes, - and the values are assumed to specify an error box (i.e. error - circles, ellipses, etc, are not supported). - - \sstitem - The spectral and redshift sub-phrases do not support the - following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos, - EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, - NEPTUNE, PLUTO. - - \sstitem - Error values are supported but error ranges are not. - - \sstitem - Resolution, PixSize and Size values are ignored. - - \sstitem - Space velocity sub-phrases are ignored. - } - } - \sstconstructor{ - \htmlref{astStcsChan}{astStcsChan} - } - \sstdiytopic{ - Inheritance - }{ - The StcsChan class inherits from the Channel class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Channels, every - StcsChan also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S? - - \sstitem - \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S? - - \sstitem - \htmlref{StcsLength}{StcsLength}: Controls output buffer length - - \sstitem - \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S? - } - } - \sstdiytopic{ - Functions - }{ - The StcsChan class does not define any new functions beyond those - which are applicable to all Channels. - } -} -\sstroutine{ - SwitchMap -}{ - A Mapping that encapsulates a set of alternate Mappings -}{ - \sstdescription{ - A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate - Mappings, each of which is used to transform positions within a - particular region of the input or output coordinate system of the - SwitchMap. - - A SwitchMap can encapsulate any number of Mappings, but they must - all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the - same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself - inherits these same values for its Nin and Nout attributes. Each of - these Mappings represents a \texttt{"} route\texttt{"} through the switch, and are - referred to as \texttt{"} route\texttt{"} Mappings below. Each route Mapping transforms - positions between the input and output coordinate space of the entire - SwitchMap, but only one Mapping will be used to transform any given - position. The selection of the appropriate route Mapping to use with - any given input position is made by another Mapping, called the - \texttt{"} selector\texttt{"} Mapping. Each SwitchMap encapsulates two selector - Mappings in addition to its route Mappings; one for use with the - SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector - Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation - (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping - must have the same number of inputs as the route Mappings, but - should have only one output. Likewise, the inverse selector Mapping - must have the same number of outputs as the route Mappings, but - should have only one input. - - When the SwitchMap is used to transform a position in the forward - direction (from input to output), each supplied input position is - first transformed by the forward transformation of the forward selector - Mapping. This produces a single output value for each input position - referred to as the selector value. The nearest integer to the selector - value is found, and is used to index the array of route Mappings (the - first supplied route Mapping has index 1, the second route Mapping has - index 2, etc). If the nearest integer to the selector value is less - than 1 or greater than the number of route Mappings, then the SwitchMap - output position is set to a value of AST\_\_BAD on every axis. Otherwise, - the forward transformation of the selected route Mapping is used to - transform the supplied input position to produce the SwitchMap output - position. - - When the SwitchMap is used to transform a position in the inverse - direction (from \texttt{"} output\texttt{"} to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"} position - is first transformed by the inverse transformation of the inverse - selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"} - position. Again, the nearest integer to the selector value is found, - and is used to index the array of route Mappings. If this selector - index value is within the bounds of the array of route Mappings, then - the inverse transformation of the selected route Mapping is used to - transform the supplied \texttt{"} output\texttt{"} position to produce the SwitchMap - \texttt{"} input\texttt{"} position. If the selector index value is outside the bounds - of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"} position is - set to a value of AST\_\_BAD on every axis. - - In practice, appropriate selector Mappings should be chosen to - associate a different route Mapping with each region of coordinate - space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly - appropriate for this purpose. - - If a compound Mapping contains a SwitchMap in series with its own - inverse, the combination of the two adjacent SwitchMaps will be - replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using - \htmlref{astSimplify}{astSimplify}. - } - \sstconstructor{ - \htmlref{astSwitchMap}{astSwitchMap} - } - \sstdiytopic{ - Inheritance - }{ - The SwitchMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The SwitchMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The SwitchMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - Table -}{ - A 2-dimensional table of values -}{ - \sstdescription{ - The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional - table of values. The - astMapGet... and astMapPut... - methods provided by the KeyMap class should be used for storing and - retrieving values from individual cells within a Table. Each entry - in the KeyMap represents a single cell of the table and has an - associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"} where \texttt{"} $<$COL$>$\texttt{"} is the - upper-case name of a table column and \texttt{"} i\texttt{"} is the row index (the - first row is row 1). Keys of this form should always be used when - using KeyMap methods to access entries within a Table. - - Columns must be declared using the - \htmlref{astAddColumn}{astAddColumn} - method before values can be stored within them. This also fixes the - type and shape of the values that may be stored in any cell of the - column. Cells may contain scalar or vector values of any data type - supported by the KeyMap class. Multi-dimensional arrays may also be - stored, but these must be vectorised when storing and retrieving - them within a table cell. All cells within a single column must - have the same type and shape, as specified when the column is added - to the Table. - - Tables may have parameters that describe global properties of the - entire table. These are stored as entries in the parent KeyMap and - can be access using the get and set method of the KeyMap class. - However, parameters must be declared using the - \htmlref{astAddParameter}{astAddParameter} - method before being accessed. - - Note - since accessing entries within a KeyMap is a relatively slow - process, it is not recommended to use the Table class to store - very large tables. - } - \sstconstructor{ - \htmlref{astTable}{astTable} - } - \sstdiytopic{ - Inheritance - }{ - The Table class inherits from the KeyMap class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all KeyMaps, every - Table also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column - - \sstitem - \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column - - \sstitem - \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column - - \sstitem - \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column - - \sstitem - ColumnUnit(column): The unit string describing each value in a column - - \sstitem - \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table - - \sstitem - \htmlref{Nrow}{Nrow}: The number of rows currently in the Table - - \sstitem - \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table - } - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all KeyMaps, the - following functions may also be applied to all Tables: - - \sstitemlist{ - - \sstitem - \htmlref{astAddColumn}{astAddColumn}: Add a new column definition to a Table - - \sstitem - \htmlref{astAddParameter}{astAddParameter}: Add a new global parameter definition to a Table - - \sstitem - \htmlref{astColumnName}{astColumnName}: Return the name of the column with a given index - - \sstitem - \htmlref{astColumnShape}{astColumnShape}: Return the shape of the values in a named column - - \sstitem - \htmlref{astHasColumn}{astHasColumn}: Checks if a column exists in a Table - - \sstitem - \htmlref{astHasParameter}{astHasParameter}: Checks if a global parameter exists in a Table - - \sstitem - \htmlref{astParameterName}{astParameterName}: Return the name of the parameter with a given index - - \sstitem - \htmlref{astPurgeRows}{astPurgeRows}: Remove all empty rows from a Table - - \sstitem - \htmlref{astRemoveColumn}{astRemoveColumn}: Remove a column from a Table - - \sstitem - \htmlref{astRemoveParameter}{astRemoveParameter}: Remove a global parameter from a Table - - \sstitem - \htmlref{astRemoveRow}{astRemoveRow}: Remove a row from a Table - } - } -} -\sstroutine{ - TimeFrame -}{ - Time coordinate system description -}{ - \sstdescription{ - A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which - represents various coordinate systems used to describe positions in - time. - - A TimeFrame represents a moment in time as either an Modified Julian - Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch, - as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be - specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame - representing time offsets from the specified zero point. - - Even though JD and MJD are defined as being in units of days, the - TimeFrame class allows other units to be used (via the Unit attribute) - on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1 - hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs - can be described in units other than the usual years. Besselian epoch - are always represented in units of (tropical) years. - - The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that - is, the physical process used to define the rate of flow of time). - MJD, JD and Julian epoch can be used to represent a time in any - supported time scale. However, Besselian epoch may only be used with the - \texttt{"} TT\texttt{"} (Terrestrial Time) time scale. The list of supported time scales - includes universal time and siderial time. Strictly, these represent - angles rather than time scales, but are included in the list since - they are in common use and are often thought of as time scales. - - When a time value is formatted it can be formated either as a simple - floating point value, or as a Gregorian date (see the Format - attribute). - } - \sstconstructor{ - \htmlref{astTimeFrame}{astTimeFrame} - } - \sstdiytopic{ - Inheritance - }{ - The TimeFrame class inherits from the Frame class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Frames, every - TimeFrame also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames - - \sstitem - \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours. - - \sstitem - \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values - - \sstitem - \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame - - } - Several of the Frame attributes inherited by the TimeFrame class - refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)}, - \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional, - it allows these attributes to be specified without an axis index. - So for instance, \texttt{"} Unit\texttt{"} is allowed in place of \texttt{"} Unit(1)\texttt{"} . - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Frames, the - following functions may also be applied to all TimeFrames: - - \sstitemlist{ - - \sstitem - \htmlref{astCurrentTime}{astCurrentTime}: Return the current system time - } - } -} -\sstroutine{ - TimeMap -}{ - Sequence of time coordinate conversions -}{ - \sstdescription{ - A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be - used to represent a sequence of conversions between standard time - coordinate systems. - - When a TimeMap is first created, it simply performs a unit - (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd} - function, a series of coordinate conversion steps may then be - added. This allows multi-step conversions between a variety of - time coordinate systems to be assembled out of a set of building - blocks. - - For details of the individual coordinate conversions available, - see the description of the astTimeAdd function. - } - \sstconstructor{ - \htmlref{astTimeMap}{astTimeMap} (also see astTimeAdd) - } - \sstdiytopic{ - Inheritance - }{ - The TimeMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The TimeMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - In addition to those functions applicable to all Mappings, the - following function may also be applied to all TimeMaps: - - \sstitemlist{ - - \sstitem - \htmlref{astTimeAdd}{astTimeAdd}: Add a time coordinate conversion to an TimeMap - } - } -} -\sstroutine{ - TranMap -}{ - Mapping with specified forward and inverse transformations -}{ - \sstdescription{ - A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of - a supplied Mapping with the inverse transformation of another - supplied Mapping, ignoring the un-used transformation in each - Mapping (indeed the un-used transformation need not exist). - - When the forward transformation of the TranMap is referred to, the - transformation actually used is the forward transformation of the - first Mapping supplied when the TranMap was constructed. Likewise, - when the inverse transformation of the TranMap is referred to, the - transformation actually used is the inverse transformation of the - second Mapping supplied when the TranMap was constructed. - } - \sstconstructor{ - \htmlref{astTranMap}{astTranMap} - } - \sstdiytopic{ - Inheritance - }{ - The TranMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The TranMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The TranMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - UnitMap -}{ - Unit (null) Mapping -}{ - \sstdescription{ - A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the - coordinates supplied to it. They are simply copied. This can be - useful if a Mapping is required (e.g. to pass to another - function) but you do not want it to have any effect. - The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and - are specified when it is created. - } - \sstconstructor{ - \htmlref{astUnitMap}{astUnitMap} - } - \sstdiytopic{ - Inheritance - }{ - The UnitMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The UnitMap class does not define any new attributes beyond - those which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The UnitMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - UnitNormMap -}{ - Convert a vector to a unit vector and its norm, relative to a specified centre -}{ - \sstdescription{ - The forward transformation of a UnitNormMap subtracts the specified centre - and then transforms the resulting vector to a unit vector and the vector norm. - The output contains one more coordinate than the input: the initial \htmlref{Nin}{Nin} outputs - are in the same order as the input; the final output is the norm. - - The inverse transformation of a UnitNormMap multiplies each component - of the provided vector by the provided norm and adds the specified centre. - The output contains one fewer coordinate than the input: the initial Nin inputs - are in the same order as the output; the final input is the norm. - - UnitNormMap enables radially symmetric transformations, as follows: - \sstitemlist{ - - \sstitem - apply a UnitNormMap to produce a unit vector and norm (radius) - - \sstitem - apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged - - \sstitem - apply the same UnitNormMap in the inverse direction to produce the result - } - } - \sstconstructor{ - \htmlref{astUnitNormMap}{astUnitNormMap} - } - \sstdiytopic{ - Inheritance - }{ - The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class. - } - \sstdiytopic{ - Attributes - }{ - The UnitNormMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The UnitNormMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - WcsMap -}{ - Implement a FITS-WCS sky projection -}{ - \sstdescription{ - This class is used to represent sky coordinate projections as - described in the FITS world coordinate system (FITS-WCS) paper II - \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"} by M. Calabretta - and E.W. Griesen. This paper defines a set of functions, or sky - projections, which transform longitude-latitude pairs representing - spherical celestial coordinates into corresponding pairs of Cartesian - coordinates (and vice versa). - - A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these - sky projections and applies them to a specified pair of coordinates. - All the projections in the FITS-WCS paper are supported, plus the now - deprecated \texttt{"} TAN with polynomial correction terms\texttt{"} projection which - is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology, - the transformation is between \texttt{"} native spherical\texttt{"} and \texttt{"} projection - plane\texttt{"} coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} . - These coordinates may, optionally, be embedded in a space with more - than two dimensions, the remaining coordinates being copied unchanged. - Note, however, that for consistency with other AST facilities, a - WcsMap handles coordinates that represent angles in radians (rather - than the degrees used by FITS-WCS). - - The type of FITS-WCS projection to be used and the coordinates - (axes) to which it applies are specified when a WcsMap is first - created. The projection type may subsequently be determined - using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts - may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute. - - Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"} to be - associated with each axis. These specify the precise form of the - projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"} is - the integer axis index (starting at 1), and m is an integer - \texttt{"} parameter index\texttt{"} in the range 0 to 99. The number of projection - parameters required by each projection, and their meanings, are - dependent upon the projection type (most projections either do not - use any projection parameters, or use parameters 1 and 2 associated - with the latitude axis). Before creating a WcsMap you should consult - the FITS-WCS paper for details of which projection parameters are - required, and which have defaults. When creating the WcsMap, you must - explicitly set values for all those required projection parameters - which do not have defaults defined in this paper. - } - \sstconstructor{ - \htmlref{astWcsMap}{astWcsMap} - } - \sstdiytopic{ - Inheritance - }{ - The WcsMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Mappings, every - WcsMap also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection - - \sstitem - \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection - - \sstitem - \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters - - \sstitem - PVMax: Maximum number of FITS-WCS projection parameters - - \sstitem - \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes - - \sstitem - \htmlref{WcsType}{WcsType}: FITS-WCS projection type - } - } - \sstdiytopic{ - Functions - }{ - The WcsMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - WinMap -}{ - Map one window on to another by scaling and shifting each axis -}{ - \sstdescription{ - A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular - window in one coordinate system into a similar window in another - coordinate system by scaling and shifting each axis (the window - edges being parallel to the coordinate axes). - - A WinMap is specified by giving the coordinates of two opposite - corners (A and B) of the window in both the input and output - coordinate systems. - } - \sstconstructor{ - \htmlref{astWinMap}{astWinMap} - } - \sstdiytopic{ - Inheritance - }{ - The WinMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - The WinMap class does not define any new attributes beyond those - which are applicable to all Mappings. - } - \sstdiytopic{ - Functions - }{ - The WinMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - XmlChan -}{ - I/O Channel using XML to represent Objects -}{ - \sstdescription{ - A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O - operations. Writing an \htmlref{Object}{Object} to an XmlChan (using - \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an - XML description of that Object, and reading from an XmlChan will - create a new Object from its XML description. - - Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"} - and \texttt{"} sink\texttt{"} functions which connect it to an external data store - by reading and writing the resulting XML text. These functions - should perform any conversions needed between external character - encodings and the internal ASCII encoding. If no such functions - are supplied, a Channel will read from standard input and write - to standard output. - - Alternatively, an XmlChan can be told to read or write from - specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes, - in which case no sink or source function need be supplied. - } - \sstconstructor{ - \htmlref{astXmlChan}{astXmlChan} - } - \sstdiytopic{ - Inheritance - }{ - The XmlChan class inherits from the Channel class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Channels, every - XmlChan also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML - - \sstitem - \htmlref{XmlLength}{XmlLength}: Controls output buffer length - - \sstitem - \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing - } - } - \sstdiytopic{ - Functions - }{ - The XmlChan class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\sstroutine{ - ZoomMap -}{ - Zoom coordinates about the origin -}{ - \sstdescription{ - The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"} - transformation by multiplying all coordinate values by the same - scale factor (the inverse transformation is performed by - dividing by this scale factor). The number of coordinate values - representing each point is unchanged. - } - \sstconstructor{ - \htmlref{astZoomMap}{astZoomMap} - } - \sstdiytopic{ - Inheritance - }{ - The ZoomMap class inherits from the Mapping class. - } - \sstdiytopic{ - Attributes - }{ - In addition to those attributes common to all Mappings, every - ZoomMap also has the following attributes: - - \sstitemlist{ - - \sstitem - \htmlref{Zoom}{Zoom}: ZoomMap scale factor - } - } - \sstdiytopic{ - Functions - }{ - The ZoomMap class does not define any new functions beyond those - which are applicable to all Mappings. - } -} -\normalsize - -\cleardoublepage -\section{\label{ss:commanddescriptions}UNIX Command Descriptions} -The commands described here are provided for use from the UNIX shell -to assist with developing software which uses AST. To use these -commands, you should ensure that the directory -``/star/bin''\footnote{Or the equivalent directory if AST is installed -in a non-standard location.} is on your PATH. -\small -\sstroutine{ - ast\_link -}{ - Link a program with the AST library -}{ - \sstdescription{ - This command should be used when building programs which use the AST - library, in order to generate the correct arguments to allow the compiler - to link your program. The arguments generated are written to standard - output but may be substituted into the compiler command line in the - standard UNIX way using backward quotes (see below). - - By default, it is assumed that you are building a stand-alone program - which does not produce graphical output. However, switches are provided - for linking other types of program. - } - \sstinvocation{ - cc program.c -L/star/lib `ast\_link [switches]` -o program - } - \sstexamples{ - \sstexamplesubsection{ - cc display.c -L/star/lib `ast\_link -pgplot` -o display - }{ - Compiles and links a C program called ``display\texttt{'} \texttt{'} which uses - the standard version of PGPLOT for graphical output. - } - \sstexamplesubsection{ - cc plotit.c -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit - }{ - Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'} - switch indicates that graphical output will be delivered through - a graphical interface which you have implemented yourself, which - corresponds to the interface required by the current version of AST. - Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library - reference. - } - \sstexamplesubsection{ - cc plotit.c -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit - }{ - Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'} - switch indicates that graphical output will be delivered through - a graphical interface which you have implemented yourself, which - corresponds to the interface required by version 2.0 of AST. - Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library - reference. - } - } - \sstdiytopic{ - Switches - }{ - The following switches may optionally be given to this command to - modify its behaviour: - - \sstitemlist{ - - \sstitem - ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. - - \sstitem - ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. - - \sstitem - ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages - produced by the AST library are delivered via the Starlink EMS (Error - Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default, - error messages are simply written to standard error. - - \sstitem - ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages - produced by the AST library are delivered via the DRAMA Ers (Error - Reporting Service) library. By default, error messages are simply - written to standard error. - - \sstitem - ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which - 2D graphics system is used to display output from the AST library. You - should use this option only if you have implemented an interface to a - new graphics system yourself and wish to provide your own arguments for - linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in - that it assumes that your graphics module implements the complete - interface required by the current version of AST. If future versions of - AST introduce new functions to the graphics interface, this switch will - cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you - that you need to implement new functions in your graphics module. To - avoid such errors, you can use one of the other, version-specific, - switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time - errors to be reported if any AST function is invoked which requires - facilities not in the implemented interface. - - \sstitem - ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. - It indicates that you want to link with your own graphics module - which implements the 2D graphics interface required by V2.0 of AST. - - \sstitem - ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own - graphics module which implements the 2D graphics interface required by - V3.2 of AST. - - \sstitem - ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own - graphics module which implements the 2D graphics interface required by - V5.6 of AST. - - \sstitem - ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how - error messages produced by the AST library should be delivered. You - should use this option only if you have implemented an interface to a - new error delivery system yourself and wish to provide your own - arguments for linking with it. - - \sstitem - ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, - but is retained in order to allow applications to be linked with a - graphics module which implements the 2D interface used by AST V2.0. It - is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. - - \sstitem - ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D - graphical output from the AST library is displayed via the - Starlink version of the PGPLOT graphics package (which uses GKS - for its output). By default, no 2D graphics package is linked and - this will result in an error at run time if AST routines are - invoked that attempt to generate graphical output. - - \sstitem - ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D - graphical output from the AST library is displayed via - the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics - package. By default, no 2D graphics package is linked and this will - result in an error at run time if AST routines are invoked that - attempt to generate graphical output. - - \sstitem - ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which - 3D graphics system is used to display output from the AST library. You - should use this option only if you have implemented an interface to a - new 3D graphics system yourself and wish to provide your own arguments - for linking with it. - - \sstitem - ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D - graphical output from the AST library is displayed via the - Starlink version of the PGPLOT graphics package (which uses GKS - for its output). By default, no 3D graphics package is linked and - this will result in an error at run time if AST routines are - invoked that attempt to generate graphical output. - - \sstitem - ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D - graphical output from the AST library is displayed via - the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics - package. By default, no 3D graphics package is linked and this will - result in an error at run time if AST routines are invoked that - attempt to generate graphical output. - } - } - \sstdiytopic{ - ERFA \& PAL - }{ - The AST distribution includes bundled copies of the ERFA and PAL - libraries. These will be used for fundamental positional astronomy - calculations unless the \texttt{"} --with-external\_pal\texttt{"} option was used when - AST was configured. If \texttt{"} --with-external\_pal\texttt{"} is used, this script - will include \texttt{"} -lpal\texttt{"} in the returned list of linking options, and - the user should then ensure that external copies of the PAL and - ERFA libraries are available (ERFA functions are used within PAL). - } -} -\sstroutine{ - ast\_link\_adam -}{ - Link an ADAM program with the AST library -}{ - \sstdescription{ - This command should only be used when building Starlink ADAM programs - which use the AST library, in order to generate the correct arguments - to allow the ADAM ``alink\texttt{'} \texttt{'} command to link the program. The arguments - generated are written to standard output but may be substituted into - the ``alink\texttt{'} \texttt{'} command line in the standard UNIX way using backward - quotes (see below). - - By default, it is assumed that you are building an ADAM program which - does not produce graphical output. However, switches are provided for - linking other types of program. This command should not be used when - building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'} command - instead. - } - \sstinvocation{ - alink program.o -L/star/lib `ast\_link\_adam [switches]` - } - \sstexamples{ - \sstexamplesubsection{ - alink display.o -L/star/lib `ast\_link\_adam -pgplot` - }{ - Links an ADAM program ``display\texttt{'} \texttt{'} which uses the standard - version of PGPLOT for graphical output. - } - \sstexamplesubsection{ - alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf` -lgrf - }{ - Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\texttt{'} \texttt{'} - switch indicates that graphical output will be delivered through - a graphical interface which you have implemented yourself, which - corresponds to the interface required by the current version of AST. - Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library - reference. - } - \sstexamplesubsection{ - alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf - }{ - Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\_v2.0\texttt{'} \texttt{'} - switch indicates that graphical output will be delivered through - a graphical interface which you have implemented yourself, which - corresponds to the interface required by version 2.0 of AST. Here, - this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'} library - reference. - } - } - \sstdiytopic{ - Switches - }{ - The following switches may optionally be given to this command to - modify its behaviour: - - \sstitemlist{ - - \sstitem - ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. - - \sstitem - ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only. - - \sstitem - ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which - 2D graphics system is used to display output from the AST library. You - should use this option only if you have implemented an interface to a - new graphics system yourself and wish to provide your own arguments for - linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'} switches in - that it assumes that your graphics module implements the complete - interface required by the current version of AST. If future versions of - AST introduce new functions to the graphics interface, this switch will - cause ``unresolved symbol\texttt{'} \texttt{'} errors to occur during linking, warning you - that you need to implement new functions in your graphics module. To - avoid such errors, you can use one of the other, version-specific, - switches in place of the ``-grf\texttt{'} \texttt{'} switch, but these will cause run-time - errors to be reported if any AST function is invoked which requires - facilities not in the implemented interface. - - \sstitem - ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'} switch. - It indicates that you want to link with your own graphics module which - implements the 2D graphics interface required by V2.0 of AST. - - \sstitem - ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics - module which implements the 2D graphics interface required by V3.2 of AST. - - \sstitem - ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics - module which implements the 2D graphics interface required by V5.6 of AST. - - \sstitem - ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how - error messages produced by the AST library should be delivered. You - should use this option only if you have implemented an interface to a - new error delivery system yourself and wish to provide your own - arguments for linking with it. By default, error messages are delivered - in the standard ADAM way via the EMS Error Message Service (Starlink - \htmlref{System}{System} Note SSN/4). - - \sstitem - ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'} switch, - but is retained in order to allow applications to be linked with a - graphics module which implements the interface used by AST V2.0. It is - equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'} switch. - - \sstitem - ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D - graphical output from the AST library is displayed via the - Starlink version of the PGPLOT graphics package (which uses GKS - for its output). By default, no graphics package is linked and - this will result in an error at run time if AST routines are - invoked that attempt to generate graphical output. - - \sstitem - ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D - graphical output from the AST library is displayed via the - standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics - package. By default, no graphics package is linked and this will - result in an error at run time if AST routines are invoked that - attempt to generate graphical output. - - \sstitem - ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which - 3D graphics system is used to display output from the AST library. You - should use this option only if you have implemented an interface to a - new 3D graphics system yourself and wish to provide your own arguments - for linking with it. - - \sstitem - ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D - graphical output from the AST library is displayed via the - Starlink version of the PGPLOT graphics package (which uses GKS - for its output). By default, no 3D graphics package is linked and - this will result in an error at run time if AST routines are - invoked that attempt to generate graphical output. - - \sstitem - ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D - graphical output from the AST library is displayed via - the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics - package. By default, no 3D graphics package is linked and this will - result in an error at run time if AST routines are invoked that - attempt to generate graphical output. - } - } - \sstdiytopic{ - SLALIB - }{ - The AST distribution includes a cut down subset of the C version of - the SLALIB library written by Pat Wallace. This subset contains only - the functions needed by the AST library. It is built as part of the - process of building AST and is distributed under GPL (and is thus - compatible with the AST license). Previous version of this script - allowed AST applications to be linked against external SLALIB - libraries (either Fortran or C) rather than the internal version. - The current version of this script does not provide this option, - and always uses the internal SLALIB library. However, for backward - compatibility, this script still allows the \texttt{"} -fsla\texttt{"} and \texttt{"} -csla\texttt{"} flags - (previously used for selecting which version of SLALIB to use) to be - specified, but they will be ignored. - } -} -\normalsize - -\cleardoublepage -\section{\label{ss:memoryfunctions}AST Memory Management and Utility Functions} -AST provides a memory management layer that can be used in place of -system functions such as \texttt{malloc}, \texttt{free}, \texttt{realloc}, -\emph{etc.} The AST replacements for these functions ( \texttt{\htmlref{astMalloc}{astMalloc}}, -\texttt{\htmlref{astFree}{astFree}} and \texttt{\htmlref{astRealloc}{astRealloc}}) add extra information to each -allocated memory block that allows AST to check the validity of supplied -pointers. For example, this extra information allows \texttt{astFree} to -detect if the supplied pointer has already been freed, and if so to issue -an appropriate error message. The existence of this extra information is -invisible to outside callers, and stored in a header block located just -before the returned memory block. - -In addition to the standard functions, AST provides other memory management -functions, such as: - -\begin{description} -\item [\texttt{\htmlref{astStore}{astStore}}] - stores data in dynamically allocated memory, allocating -the memory (or adjusting the size of previously allocated memory) to match -the amount of data to be stored. -\item [\texttt{\htmlref{astGrow}{astGrow}}] - allocates and expands memory to hold an adjustable-sized array. -\item [\texttt{\htmlref{astAppendString}{astAppendString}}] - allocates and expands memory to hold a -concatenated string. -\end{description} - -Theses are just a few of the available utilities functions in the AST -memory management layer. Prototypes for all AST memory management -functions are included in the header file ``\texttt{ast.h}''. - -An important restriction on these functions is that pointers created by -other memory management functions, such as the system version of \texttt{malloc} \emph{etc.}, should never supplied to an AST memory management -function. Only pointers created by AST should be used by these functions. - -In addition to memory management functions, AST provides various other -utility functions, such as a basic regular expression facility, and other -string manipulation functions. These are also documented in this appendix. - -The AST memory management layer is implemented on top of the usual \texttt{malloc}, {tt free} and \texttt{realloc} functions. By default these will be -the standard functions provided by <stdlib.h>. However, the facilities of -the STARMEM package (included in the Starlink Software Collection) can be -used to specify alternative functions to use. This requires that AST be -configured using the ``--with-starmem'' option when it is built. - -The STARMEM package provides a wrapper for the standard malloc -implementation that enables the user to switch malloc schemes at runtime -by setting the STARMEM\_MALLOC environment variable. Currently allowed -values for this variable are: - -\begin{description} -\item [SYSTEM] - standard system malloc/free - the default -\item [DL] - Doug Lea's malloc/free -\item [GC] - Hans-Boehm Garbage Collection -\end{description} - -\small -\sstroutine{ - astAppendString -}{ - Append a string to another string which grows dynamically -}{ - \sstdescription{ - This function appends one string to another dynamically - allocated string, extending the dynamic string as necessary to - accommodate the new characters (plus the final null). - } - \sstsynopsis{ - char $*$astAppendString( char $*$str1, int $*$nc, const char $*$str2 ) - } - \sstparameters{ - \sstsubsection{ - str1 - }{ - Pointer to the null-terminated dynamic string, whose memory - has been allocated using an AST memory allocation function. - If no space has yet been allocated for this string, a NULL - pointer may be given and fresh space will be allocated by this - function. - } - \sstsubsection{ - nc - }{ - Pointer to an integer containing the number of characters in - the dynamic string (excluding the final null). This is used - to save repeated searching of this string to determine its - length and it defines the point where the new string will be - appended. Its value is updated by this function to include - the extra characters appended. - - If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will - be ignored and zero will be used. - } - \sstsubsection{ - str2 - }{ - Pointer to a constant null-terminated string, a copy of which - is to be appended to \texttt{"} str1\texttt{"} . - } - } - \sstreturnedvalue{ - \sstsubsection{ - astAppendString() - }{ - A possibly new pointer to the dynamic string with the new string - appended (its location in memory may have to change if it has to - be extended, in which case the original memory is automatically - freed by this function). When the string is no longer required, - its memory should be freed using \htmlref{astFree}{astFree}. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - If this function is invoked with the global error status set - or if it should fail for any reason, then the returned pointer - will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be - unchanged. - } - } -} -\sstroutine{ - astAppendStringf -}{ - Append a string to another string, allowing printf format specifiers -}{ - \sstdescription{ - This function appends one string to another dynamically - allocated string, extending the dynamic string as necessary to - accommodate the new characters (plus the final null). It is the - same as \htmlref{astAppendString}{astAppendString}, except that the \texttt{"} str2\texttt{"} string ay include - printf format specifiers. - } - \sstsynopsis{ - char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... ) - } - \sstparameters{ - \sstsubsection{ - str1 - }{ - Pointer to the null-terminated dynamic string, whose memory - has been allocated using an AST memory allocation function. - If no space has yet been allocated for this string, a NULL - pointer may be given and fresh space will be allocated by this - function. - } - \sstsubsection{ - nc - }{ - Pointer to an integer containing the number of characters in - the dynamic string (excluding the final null). This is used - to save repeated searching of this string to determine its - length and it defines the point where the new string will be - appended. Its value is updated by this function to include - the extra characters appended. - - If \texttt{"} str1\texttt{"} is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"} will - be ignored and zero will be used. - } - \sstsubsection{ - str2 - }{ - Pointer to a constant null-terminated string, a copy of which - is to be appended to \texttt{"} str1\texttt{"} . It may contain format - specifications such as used with the C \texttt{"} printf\texttt{"} family of - functions. - } - \sstsubsection{ - ... - }{ - Additional optional arguments (as used by e.g. \texttt{"} printf\texttt{"} ) - which specify values which are to be substituted into the \texttt{"} str2\texttt{"} - string in place of any format specifications. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astAppendString() - }{ - A possibly new pointer to the dynamic string with the new string - appended (its location in memory may have to change if it has to - be extended, in which case the original memory is automatically - freed by this function). When the string is no longer required, - its memory should be freed using \htmlref{astFree}{astFree}. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - If this function is invoked with the global error status set - or if it should fail for any reason, then the returned pointer - will be equal to \texttt{"} str1\texttt{"} and the dynamic string contents will be - unchanged. - } - } -} -\sstroutine{ - astCalloc -}{ - Allocate and initialise memory -}{ - \sstdescription{ - This function allocates memory in a similar manner to the - standard C \texttt{"} calloc\texttt{"} function, but with improved security - (against memory leaks, etc.) and with error reporting. It also - fills the allocated memory with zeros. - - Like \htmlref{astMalloc}{astMalloc}, it allows zero-sized memory allocation - (without error), resulting in a NULL returned pointer value. - } - \sstsynopsis{ - void $*$astCalloc( size\_t nmemb, size\_t size ) - } - \sstparameters{ - \sstsubsection{ - nmemb - }{ - The number of array elements for which memory is to be allocated. - } - \sstsubsection{ - size - }{ - The size of each array element, in bytes. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astCalloc() - }{ - If successful, the function returns a pointer to the start of - the allocated memory region. If the size allocated is zero, this - will be a NULL pointer. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A pointer value of NULL is returned if this function is - invoked with the global error status set or if it fails for any - reason. - } - } -} -\sstroutine{ - astChr2Double -}{ - read a double value from a string -}{ - \sstdescription{ - This function reads a double from the supplied null-terminated string, - ignoring leading and trailing white space. AST\_\_BAD is ereturned - without error if the string is not a numerical value. - } - \sstsynopsis{ - double astChr2Double( const char $*$str ) - } - \sstparameters{ - \sstsubsection{ - str - }{ - Pointer to the string. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChr2Double() - }{ - The double value, or AST\_\_BAD. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A value of AST\_\_BAD is returned if this function is invoked with - the global error status set or if it should fail for any reason. - } - } -} -\sstroutine{ - astChrCase -}{ - Convert a string to upper or lower case -}{ - \sstdescription{ - This function converts a supplied string to upper or lower case, - storing the result in a supplied buffer. The \htmlref{astStringCase}{astStringCase} function - is similar, but stores the result in a dynamically allocated buffer. - } - \sstsynopsis{ - void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status ) - } - \sstparameters{ - \sstsubsection{ - in - }{ - Pointer to the null terminated string to be converted. If this - is NULL, the supplied contents of the \texttt{"} out\texttt{"} string are used as - the input string. - } - \sstsubsection{ - out - }{ - Pointer to the buffer to receive the converted string. The - length of this buffer is given by \texttt{"} blen\texttt{"} . If NULL is supplied - for \texttt{"} in\texttt{"} , then the supplied contents of \texttt{"} out\texttt{"} are converted and - written back into \texttt{"} out\texttt{"} over-writing the supplied contents. - } - \sstsubsection{ - upper - }{ - If non-zero, the string is converted to upper case. Otherwise it - is converted to lower case. - } - \sstsubsection{ - blen - }{ - The length of the output buffer. Ignored if \texttt{"} in\texttt{"} is NULL. No - more than \texttt{"} blen - 1\texttt{"} characters will be copied from \texttt{"} in\texttt{"} to - \texttt{"} out\texttt{"} , and a terminating null character will then be added. - } - } -} -\sstroutine{ - astChrLen -}{ - Determine the used length of a string -}{ - \sstdescription{ - This function returns the used length of a string. This excludes any - trailing white space or non-printable characters (such as the - trailing null character). - } - \sstsynopsis{ - size\_t astChrLen( const char $*$string ) - } - \sstparameters{ - \sstsubsection{ - string - }{ - Pointer to the string. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrLen() - }{ - The number of characters in the supplied string, not including the - trailing newline, and any trailing white-spaces or non-printable - characters. - } - } -} -\sstroutine{ - astChrMatch -}{ - Case insensitive string comparison -}{ - \sstdescription{ - This function compares two null terminated strings for equality, - discounting differences in case and any trailing white space in either - string. - } - \sstsynopsis{ - int astChrMatch( const char $*$str1, const char $*$str2 ) - } - \sstparameters{ - \sstsubsection{ - str1 - }{ - Pointer to the first string. - } - \sstsubsection{ - str2 - }{ - Pointer to the second string. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrMatch() - }{ - Non-zero if the two strings match, otherwise zero. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A value of zero is returned if this function is invoked with the - global error status set or if it should fail for any reason. - } - } -} -\sstroutine{ - astChrMatchN -}{ - Case insensitive string comparison of at most N characters -}{ - \sstdescription{ - This function compares two null terminated strings for equality, - discounting differences in case and any trailing white space in either - string. No more than \texttt{"} n\texttt{"} characters are compared. - } - \sstsynopsis{ - int astChrMatchN( const char $*$str1, const char $*$str2, size\_t n ) - } - \sstparameters{ - \sstsubsection{ - str1 - }{ - Pointer to the first string. - } - \sstsubsection{ - str2 - }{ - Pointer to the second string. - } - \sstsubsection{ - n - }{ - Maximum number of characters to compare. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrMatchN() - }{ - Non-zero if the two strings match, otherwise zero. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A value of zero is returned if this function is invoked with the - global error status set or if it should fail for any reason. - } - } -} -\sstroutine{ - astChrSplit -}{ - Extract words from a supplied string -}{ - \sstdescription{ - This function extracts all space-separated words form the supplied - string and returns them in an array of dynamically allocated strings. - } - \sstsynopsis{ - char $*$$*$astChrSplit\_( const char $*$str, int $*$n ) - } - \sstparameters{ - \sstsubsection{ - str - }{ - Pointer to the string to be split. - } - \sstsubsection{ - n - }{ - Address of an int in which to return the number of words returned. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrSplit() - }{ - A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. - Each element is a pointer to a dynamically allocated character - string containing a word extracted from the supplied string. Each - of these words will have no leading or trailing white space. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A NULL pointer is returned if this function is invoked with the - global error status set or if it should fail for any reason, or if - the supplied string contains no words. - } - } -} -\sstroutine{ - astChrSplitC -}{ - Split a string using a specified character delimiter -}{ - \sstdescription{ - This function extracts all sub-strings separated by a given - character from the supplied string and returns them in an array - of dynamically allocated strings. The delimiter character itself - is not included in the returned strings. - - Delimiter characters that are preceded by \texttt{"} $\backslash$\texttt{"} are not used as - delimiters but are included in the returned word instead (without - the \texttt{"} $\backslash$\texttt{"} ). - } - \sstsynopsis{ - char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n ) - } - \sstparameters{ - \sstsubsection{ - str - }{ - Pointer to the string to be split. - } - \sstsubsection{ - c - }{ - The delimiter character. - } - \sstsubsection{ - n - }{ - Address of an int in which to return the number of words returned. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrSplitC() - }{ - A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. - Each element is a pointer to a dynamically allocated character - string containing a word extracted from the supplied string. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A NULL pointer is returned if this function is invoked with the - global error status set or if it should fail for any reason, or if - the supplied string contains no words. - } - } -} -\sstroutine{ - astChrSplitRE -}{ - Extract sub-strings matching a specified regular expression -}{ - \sstdescription{ - This function compares the supplied string with the supplied - regular expression. If they match, each section of the test string - that corresponds to a parenthesised sub-string in the regular - expression is copied and stored in the returned array. - } - \sstsynopsis{ - char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n, - const char $*$$*$matchend ) - } - \sstparameters{ - \sstsubsection{ - str - }{ - Pointer to the string to be split. - } - \sstsubsection{ - regexp - }{ - The regular expression. See \texttt{"} Template Syntax:\texttt{"} in the \htmlref{astChrSub}{astChrSub} - prologue. Note, this function differs from astChrSub in that any - equals signs (=) in the regular expression are treated literally. - } - \sstsubsection{ - n - }{ - Address of an int in which to return the number of sub-strings - returned. - } - \sstsubsection{ - matchend - }{ - A pointer to a location at which to return a pointer to the - character that follows the last character within the supplied test - string that matched any parenthesises sub-section of \texttt{"} regexp\texttt{"} . A - NULL pointer is returned if no matches were found. A NULL pointer - may be supplied if the location of the last matching character is - not needed. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrSplitRE() - }{ - A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"} elements. - Each element is a pointer to a dynamically allocated character - string containing a sub-string extracted from the supplied string. - The array itself, and the strings within it, should all be freed - using \htmlref{astFree}{astFree} when no longer needed. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - If a parenthesised sub-string in the regular expression is matched - by more than one sub-string within the test string, then only the - first is returned. To return multiple matches, the regular - expression should include multiple copies of the parenthesised - sub-string (for instance, separated by \texttt{"} .$+$?\texttt{"} if the intervening - string is immaterial). - - \sstitem - A NULL pointer is returned if this function is invoked with the - global error status set or if it should fail for any reason, or if - the supplied string contains no words. - } - } -} -\sstroutine{ - astChrSub -}{ - Performs substitutions on a supplied string -}{ - \sstdescription{ - This function checks a supplied test string to see if it matches a - supplied template. If it does, specified sub-sections of the test - string may optionally be replaced by supplied substitution strings. - The resulting string is returned. - } - \sstsynopsis{ - char $*$astChrSub( const char $*$test, const char $*$pattern, - const char $*$subs[], int nsub ) - } - \sstparameters{ - \sstsubsection{ - test - }{ - The string to be tested. - } - \sstsubsection{ - pattern - }{ - The template string. See \texttt{"} Template Syntax:\texttt{"} below. - } - \sstsubsection{ - subs - }{ - An array of strings that are to replace the sections of the test - string that match each parenthesised sub-string in \texttt{"} pattern\texttt{"} . The - first element of \texttt{"} subs\texttt{"} replaces the part of the test string that - matches the first parenthesised sub-string in the template, etc. - - If \texttt{"} nsub\texttt{"} is zero, then the \texttt{"} subs\texttt{"} pointer is ignored. In this - case, substitution strings may be specified by appended them to - the end of the \texttt{"} pattern\texttt{"} string, separated by \texttt{"} =\texttt{"} characters. - Note, if you need to include a literal \texttt{"} =\texttt{"} character in the - pattern, precede it by an escape \texttt{"} $\backslash$\texttt{"} character. - } - \sstsubsection{ - nsub - }{ - The number of substitution strings supplied in array \texttt{"} subs\texttt{"} . - } - } - \sstreturnedvalue{ - \sstsubsection{ - astChrSub() - }{ - A pointer to a dynamically allocated string holding the result - of the substitutions, or NULL if the test string does not match - the template string. This string should be freed using \htmlref{astFree}{astFree} - when no longer needed. If no substituions are specified then a - copy of the test string is returned if it matches the template. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A NULL pointer is returned if this function is invoked with the - global error status set or if it should fail for any reason, or if - the supplied test string does not match the template. - } - } - \sstdiytopic{ - Template Syntax - }{ - The template syntax is a minimal form of regular expression, The - quantifiers allowed are \texttt{"} $*$\texttt{"} , \texttt{"} ?\texttt{"} , \texttt{"} $+$\texttt{"} , \texttt{"} \{n\}\texttt{"} , \texttt{"} $*$?\texttt{"} and \texttt{"} $+$?\texttt{"} (the - last two are non-greedy - they match the minimum length possible - that still gives an overall match to the template). The only - constraints allowed are \texttt{"} $\wedge$\texttt{"} and \texttt{"} \$\texttt{"} . The following atoms are allowed: - - \sstitemlist{ - - \sstitem - [chars]: Matches any of the specified characters. - - \sstitem - [$\wedge$chars]: Matches anything but the specified characters. - - \sstitem - .: Matches any single character. - - \sstitem - x: Matches the character x so long as x has no other significance. - - \sstitem - $\backslash$x: Always matches the character x (except for [dDsSwW]). - - \sstitem - $\backslash$d: Matches a single digit. - - \sstitem - $\backslash$D: Matches anything but a single digit. - - \sstitem - $\backslash$w: Matches any alphanumeric character, and \texttt{"} \_\texttt{"} . - - \sstitem - $\backslash$W: Matches anything but alphanumeric characters, and \texttt{"} \_\texttt{"} . - - \sstitem - $\backslash$s: Matches white space. - - \sstitem - $\backslash$S: Matches anything but white space. - - } - Note, minus signs (\texttt{"} -\texttt{"} ) within brackets have no special significance, - so ranges of characters must be specified explicitly. - - Multiple template strings can be concatenated, using the \texttt{"} $|$\texttt{"} - character to separate them. The test string is compared against - each one in turn until a match is found. - - Parentheses are used within each template to identify sub-strings - that are to be replaced by the strings supplied in \texttt{"} sub\texttt{"} . - - If \texttt{"} nsub\texttt{"} is supplied as zero, then substitution strings may be - specified by appended them to the end of the \texttt{"} pattern\texttt{"} string, - separated by \texttt{"} =\texttt{"} characters. If \texttt{"} nsub\texttt{"} is not zero, then any - substitution strings appended to the end of \texttt{"} pattern\texttt{"} are ignored. - - Each element of \texttt{"} subs\texttt{"} - may contain a reference to a token of the - form \texttt{"} \$1\texttt{"} , \texttt{"} \$2\texttt{"} , etc. The \texttt{"} \$1\texttt{"} token will be replaced by the part - of the test string that matched the first parenthesised sub-string - in \texttt{"} pattern\texttt{"} . The \texttt{"} \$2\texttt{"} token will be replaced by the part of the - test string that matched the second parenthesised sub-string in - \texttt{"} pattern\texttt{"} , etc. - } -} -\sstroutine{ - astChrTrunc -}{ - Terminate a string to exclude trailing spaces -}{ - \sstdescription{ - This function pokes a null character into the supplied string to - remove any trailing spaces. - } - \sstsynopsis{ - void astChrTrunc( char $*$text ) - } - \sstparameters{ - \sstsubsection{ - text - }{ - The string to be truncated. - } - } -} -\sstroutine{ - astFree -}{ - Free previously allocated memory -}{ - \sstdescription{ - This function frees memory that has previouly been dynamically - allocated using one of the AST memory function. - } - \sstsynopsis{ - void $*$astFree( void $*$ptr ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to previously allocated memory. An error will result - if the memory has not previously been allocated by another - function in this module. However, a NULL pointer value is - accepted (without error) as indicating that no memory has yet - been allocated, so that no action is required. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astFree() - }{ - Always returns a NULL pointer. - } - } -} -\sstroutine{ - astFreeDouble -}{ - Free previously double allocated memory -}{ - \sstdescription{ - This function frees memory that has previouly been dynamically - allocated using one of the AST memory function. It assumes that - the supplied pointer is a pointer to an array of pointers. Each - of these pointers is first freed, and then the supplied pointer - is freed. - - Note, this routine should not be used with arrays allocated - by \htmlref{astGrow}{astGrow} since astGrow over-allocates and so there may be - non-initialised pointers at the end of the array. - } - \sstsynopsis{ - void $*$astFreeDouble( void $*$ptr ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to previously allocated memory. An error will result - if the memory has not previously been allocated by another - function in this module. However, a NULL pointer value is - accepted (without error) as indicating that no memory has yet - been allocated, so that no action is required. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astFreeDouble() - }{ - Always returns a NULL pointer. - } - } -} -\sstroutine{ - astGrow -}{ - Allocate memory for an adjustable array -}{ - \sstdescription{ - This function allocates memory in which to store an array of - data whose eventual size is unknown. It should be invoked - whenever a new array size is determined and will appropriately - increase the amount of memory allocated when necessary. In - general, it will over-allocate in anticipation of future growth - so that the amount of memory does not need adjusting on every - invocation. - } - \sstsynopsis{ - void $*$astGrow( void $*$ptr, int n, size\_t size ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to previously allocated memory (or NULL if none has - yet been allocated). - } - \sstsubsection{ - n - }{ - Number of array elements to be stored (may be zero). - } - \sstsubsection{ - size - }{ - The size of each array element. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astGrow() - }{ - If the memory was allocated successfully, a pointer to the start - of the possibly new memory region is returned (this may be the - same as the original pointer). - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - When new memory is allocated, the existing contents are preserved. - - \sstitem - This function does not free memory once it is allocated, so - the size allocated grows to accommodate the maximum size of the - array (or \texttt{"} high water mark\texttt{"} ). Other memory handling routines may - be used to free the memory (or alter its size) if necessary. - - \sstitem - If this function is invoked with the global error status set, - or if it fails for any reason, the original pointer value is - returned and the memory contents are unchanged. - } - } -} -\sstroutine{ - astIsDynamic -}{ - Returns a flag indicating if memory was allocated dynamically -}{ - \sstdescription{ - This function takes a pointer to a region of memory and tests if - the memory has previously been dynamically allocated using other - functions from this module. It does this by checking for the - presence of a \texttt{"} magic\texttt{"} number in the header which precedes the - allocated memory. If the magic number is not present (or the - pointer is invalid for any other reason), zero is returned. - Otherwise 1 is returned. - } - \sstsynopsis{ - int astIsDynamic\_( const void $*$ptr ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to test. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astIsDynamic() - }{ - Non-zero if the memory was allocated dynamically. Zero is returned - if the supplied pointer is NULL. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A value of zero is returned if this function is invoked with - the global error status set, or if it fails for any reason. - } - } -} -\sstroutine{ - astMalloc -}{ - Allocate memory -}{ - \sstdescription{ - This function allocates memory in a similar manner to the - standard C \texttt{"} malloc\texttt{"} function, but with improved security - (against memory leaks, etc.) and with error reporting. It also - allows zero-sized memory allocation (without error), resulting - in a NULL returned pointer value. - } - \sstsynopsis{ - void $*$astMalloc( size\_t size ) - } - \sstparameters{ - \sstsubsection{ - size - }{ - The size of the memory region required (may be zero). - } - } - \sstreturnedvalue{ - \sstsubsection{ - astMalloc() - }{ - If successful, the function returns a pointer to the start of - the allocated memory region. If the size allocated is zero, this - will be a NULL pointer. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A pointer value of NULL is returned if this function is - invoked with the global error status set or if it fails for any - reason. - } - } -} -\sstroutine{ - astMemCaching -}{ - Controls whether allocated but unused memory is cached in this module -}{ - \sstdescription{ - This function sets a flag indicating if allocated but unused memory - should be cached or not. It also returns the original value of the - flag. - - If caching is switched on or off as a result of this call, then the - current contents of the cache are discarded. - - Note, each thread has a separate cache. Calling this function - affects only the currently executing thread. - } - \sstsynopsis{ - int astMemCaching( int newval ) - } - \sstparameters{ - \sstsubsection{ - newval - }{ - The new value for the MemoryCaching tuning parameter (see - \htmlref{astTune}{astTune} in objectc.c). If AST\_\_TUNULL is supplied, the current - value is left unchanged. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astMemCaching() - }{ - The original value of the MemoryCaching tuning parameter. - } - } -} -\sstroutine{ - astRealloc -}{ - Change the size of a dynamically allocated region of memory -}{ - \sstdescription{ - This function changes the size of a dynamically allocated region - of memory, preserving its contents up to the minimum of the old - and new sizes. This may involve copying the contents to a new - location, so a new pointer is returned (and the old memory freed - if necessary). - - This function is similar to the standard C \texttt{"} realloc\texttt{"} function - except that it provides better security against programming - errors and also supports the allocation of zero-size memory - regions (indicated by a NULL pointer). - } - \sstsynopsis{ - void $*$astRealloc( void $*$ptr, size\_t size ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to previously allocated memory (or NULL if the - previous size of the allocated memory was zero). - } - \sstsubsection{ - size - }{ - New size required for the memory region. This may be zero, in - which case a NULL pointer is returned (no error results). It - should not be negative. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astRealloc() - }{ - If the memory was reallocated successfully, a pointer to the - start of the new memory region is returned (this may be the same - as the original pointer). If size was given as zero, a NULL - pointer is returned. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - If this function is invoked with the error status set, or if - it fails for any reason, the original pointer value is returned - and the memory contents are unchanged. Note that this behaviour - differs from that of the standard C \texttt{"} realloc\texttt{"} function which - returns NULL if it fails. - } - } -} -\sstroutine{ - astRemoveLeadingBlanks -}{ - Remove any leading white space from a string -}{ - \sstdescription{ - This function moves characters in the supplied string to the left - in order to remove any leading white space. - } - \sstsynopsis{ - void astRemoveLeadingBlanks( char $*$string ) - } - \sstparameters{ - \sstsubsection{ - string - }{ - Pointer to the string. - } - } -} -\sstroutine{ - astSizeOf -}{ - Determine the size of a dynamically allocated region of memory -}{ - \sstdescription{ - This function returns the size of a region of dynamically - allocated memory. - } - \sstsynopsis{ - size\_t astSizeOf( const void $*$ptr ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to dynamically allocated memory (or NULL if the size - of the allocated memory was zero). - } - } - \sstreturnedvalue{ - \sstsubsection{ - astSizeOf() - }{ - The allocated size. This will be zero if a NULL pointer was - supplied (no error will result). - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A value of zero is returned if this function is invoked with - the global error status set, or if it fails for any reason. - } - } -} -\sstroutine{ - astStore -}{ - Store data in dynamically allocated memory -}{ - \sstdescription{ - This function stores data in dynamically allocated memory, - allocating the memory (or adjusting the size of previously - allocated memory) to match the amount of data to be stored. - } - \sstsynopsis{ - void $*$astStore( void $*$ptr, const void $*$data, size\_t size ) - } - \sstparameters{ - \sstsubsection{ - ptr - }{ - Pointer to previously allocated memory (or NULL if none has - yet been allocated). - } - \sstsubsection{ - data - }{ - Pointer to the start of the data to be stored. This may be - given as NULL if there are no data, in which case it will be - ignored and this function behaves like \htmlref{astRealloc}{astRealloc}, preserving - the existing memory contents. - } - \sstsubsection{ - size - }{ - The total size of the data to be stored and/or the size of - memory to be allocated. This may be zero, in which case the - data parameter is ignored, any previously-allocated memory is - freed and a NULL pointer is returned. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astStore() - }{ - If the data were stored successfully, a pointer to the start of - the possibly new memory region is returned (this may be the same - as the original pointer). If size was given as zero, a NULL - pointer is returned. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - This is a convenience function for use when storing data of - arbitrary size in memory which is to be allocated - dynamically. It is appropriate when the size of the data will - not change frequently because the size of the memory region will - be adjusted to fit the data on every invocation. - - \sstitem - If this function is invoked with the error status set, or if - it fails for any reason, the original pointer value is returned - and the memory contents are unchanged. - } - } -} -\sstroutine{ - astString -}{ - Create a C string from an array of characters -}{ - \sstdescription{ - This function allocates memory to hold a C string and fills the - string with the sequence of characters supplied. It then - terminates the string with a null character and returns a - pointer to its start. The memory used for the string may later - be de-allocated using \htmlref{astFree}{astFree}. - - This function is intended for constructing null terminated C - strings from arrays of characters which are not null terminated, - such as when importing a character argument from a Fortran 77 - program. - } - \sstsynopsis{ - char $*$astString( const char $*$chars, int nchars ) - } - \sstparameters{ - \sstsubsection{ - chars - }{ - Pointer to the array of characters to be used to fill the string. - } - \sstsubsection{ - nchars - }{ - The number of characters in the array (zero or more). - } - } - \sstreturnedvalue{ - \sstsubsection{ - astString() - }{ - If successful, the function returns a pointer to the start of - the allocated string. If the number of characters is zero, a - zero-length string is still allocated and a pointer to it is - returned. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A pointer value of NULL is returned if this function is - invoked with the global error status set or if it fails for any - reason. - } - } -} -\sstroutine{ - astStringArray -}{ - Create an array of C strings from an array of characters -}{ - \sstdescription{ - This function turns an array of fixed-length character data into - a dynamicllay allocated array of null-terminated C strings with - an index array that may be used to access them. - - The array of character data supplied is assumed to hold \texttt{"} nel\texttt{"} - adjacent fixed-length strings (without terminating nulls), each - of length \texttt{"} len\texttt{"} characters. This function allocates memory and - creates a null-terminated copy of each of these strings. It also - creates an array of \texttt{"} nel\texttt{"} pointers which point at the start of - each of these new strings. A pointer to this index array is - returned. - - The memory used is allocated in a single block and should later - be de-allocated using \htmlref{astFree}{astFree}. - } - \sstsynopsis{ - char $*$$*$astStringArray( const char $*$chars, int nel, int len ) - } - \sstparameters{ - \sstsubsection{ - chars - }{ - Pointer to the array of input characters. The number of characters - in this array should be at least equal to (nel $*$ len). - } - \sstsubsection{ - nel - }{ - The number of fixed-length strings in the input character - array. This may be zero but should not be negative. - } - \sstsubsection{ - len - }{ - The number of characters in each fixed-length input - string. This may be zero but should not be negative. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astStringArray() - }{ - A pointer to the start of the index array, which contains \texttt{"} nel\texttt{"} - pointers pointing at the start of each null-terminated output - string. - - The returned pointer should be passed to astFree to de-allocate - the memory used when it is no longer required. This will free - both the index array and the memory used by the strings it - points at. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A NULL pointer will also be returned if the value of \texttt{"} nel\texttt{"} is - zero, in which case no memory is allocated. - - \sstitem - A pointer value of NULL will also be returned if this function - is invoked with the global error status set or if it fails for - any reason. - } - } -} -\sstroutine{ - astStringCase -}{ - Convert a string to upper or lower case -}{ - \sstdescription{ - This function converts a supplied string to upper or lower case, - storing the result in dynamically allocated memory. The \htmlref{astChrCase}{astChrCase} - function is similar, but stores the result in a supplied buffer. - } - \sstsynopsis{ - char $*$astStringCase( const char string, int upper ) - } - \sstparameters{ - \sstsubsection{ - string - }{ - Pointer to the null terminated string to be converted. - } - \sstsubsection{ - upper - }{ - If non-zero, the string is converted to upper case. Otherwise it - is converted to lower case. - } - } - \sstreturnedvalue{ - \sstsubsection{ - astStringCase() - }{ - If successful, the function returns a pointer to the start of - the allocated string. The returned memory should be freed using - \htmlref{astFree}{astFree} when no longer needed. - } - } - \sstnotes{ - \sstitemlist{ - - \sstitem - A pointer value of NULL is returned if this function is - invoked with the global error status set or if it fails for any - reason. - } - } -} -\normalsize - -\newpage -\section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage} - -This appendix gives details of the \htmlref{FitsChan}{FitsChan} class -implementation of the conventions described in the FITS-WCS papers -available at -\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are -used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan -has the value ``FITS-WCS'' (whether set explicitly or defaulted). It -should always be possible for a \htmlref{FrameSet}{FrameSet} to be read -(using the -\htmlref{astRead}{astRead} -function) from a FitsChan containing a header which conforms to these -conventions. However, only those FrameSets which are compatible with the -FITS-WCS model can be \emph{written} to a FitsChan using the -\htmlref{astWrite}{astWrite} -function. For instance, if the current \htmlref{Frame}{Frame} of a -FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{MathMap} -then the FrameSet will no longer be compatible with the FITS-WCS model, -and so will not be written out successfully to a FitsChan. - -The following sub-sections describe the details of the implementation of -each of the first four FITS-WCS papers. Here, the term ``pixel axes'' is -used to refer to the FITS pixel coordinates (i.e. the centre of the -first image pixel has a value 1.0 on each pixel axis); the term ``IWC -axes'' is used to refer to the axes of the Intermediate World Coordinate -system; and the term ``WCS axes'' is used to refer to the axes of the final -physical coordinate system described by the CTYPE\emph{i} keywords. - -\subsection{Paper I - General Linear Coordinates} -When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} keyword -values within the FitsChan do not conform to the conventions described in -later papers, in which case the axes are assumed to be linear. When -writing a FrameSet to a FitsChan, these conventions are used for axes -which are described by a simple \htmlref{Frame}{Frame} (\emph{i.e.} not a -\htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}). - -\htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword -defined by FITS-WCS paper I. - -\begin{table}[htbp] -\begin{tabular}{|l|p{2.5in}|p{2.5in}|} -\hline -\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} -& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline - -\fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS -Frame - only written if different to NAXIS.} - -\fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS -\htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference -Point'' below).} - -\fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always -written (see ``Choice of Reference Point'' below).} - -\fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only -written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is -set to zero.} - -\fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only -written in FITS-AIPS and FITS-AIPS++ encodings.} - -\fitskey{CTYPE\emph{ia}}{Used to choose the class and attributes of the -WCS Frame, and to create the pixel to WCS Mapping (note, ``STOKES'' and -``COMPLEX'' axes are treated as unknown linear axes).}{Always written -(see ``Use and Choice of CTYPE keywords'' below).} - -\fitskey{CUNIT\emph{ia}}{Used to set the Units attributes -of the WCS Frame.}{Only written if the Units attribute of the WCS Frame -has been set explicitly. If so, the Units value for each axis is used as -the CUNIT value.} - -\fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS -Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to -zero.} - -\fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS -Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to -a non-zero value.} - -\fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes -are linear.} - -\fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.} - -\fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{Domain} attribute -of the WCS Frame.}{Only written if the Domain attribute of the WCS Frame -has been set explicitly. If so, the Domain value is used as the WCSNAME -value.} - -\fitskey{CRDER\emph{ia}}{Ignored.}{Not used.} - -\fitskey{CSYER\emph{ia}}{Ignored.}{Not used.} - -\hline -\end{tabular} -\vspace{3.mm} -\caption{Use of FITS-WCS Paper I keywords} -\label{tab:fitspaper1} -\end{table} - -\subsubsection{Requirements for a Successful Write Operation} -When writing a \htmlref{FrameSet}{FrameSet} in which the WCS -\htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan}, -success depends on the \htmlref{Mapping}{Mapping} from pixel coordinates -(the base Frame in the FrameSet) to the WCS Frame being linear. The write -operation will fail if this is not the case. - -\subsubsection{Use and Choice of CTYPE\emph{i} keywords} -When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the -Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from -the CNAME\emph{i} keywords, if present in the header. Otherwise they are set -from the CTYPE\emph{i} comments strings in the header, so long as each -axis has a unique non-blank comment. Otherwise, the Label attributes are -set to the CTYPE\emph{i} values. The above procedure is over-ridden if -the axis types conform to the conventions described in paper II or III, -as described below. - -When writing a FrameSet to a FitsChan, each CTYPE\emph{i} value is set to -the value of the Symbol attribute of the corresponding axis in the Frame -being written. If a value has been set explicitly for the axis Label -attribute, it is used as the axis comment (except that any existing -comments in the FitsChan take precedence if the keyword value has not -changed). The above procedure is over-ridden if the Frame is a -\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which -case the CTYPE\emph{i} value is derived from the \htmlref{System}{System} -attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping} -according to the conventions of papers II and III, as described below. - -\subsubsection{Choice of Reference Point} -When writing a \htmlref{FrameSet}{FrameSet} to a -\htmlref{FitsChan}{FitsChan}, the pixel coordinates of the -reference point for linear axes (i.e. the CRPIX\emph{j} values) are -chosen as follows: - -\begin{itemize} -\item If the FrameSet is being written to a FitsChan which previously -contained a set of axis descriptions with the same identifying letter, -then the previous CRVAL\emph{j}values are converted into the coordinate system -of the \htmlref{Frame}{Frame} being written (if possible). These values are then -transformed into the pixel Frame, and the closest integer pixel values -are used as the CRPIX keywords. -\item If the above step could not be performed for any reason, the -central pixel is used as the reference point. This requires the image -dimensions to be present in the FitsChan in the form of a set of -NAXIS\emph{j} keyword values. -\item If both the above two steps failed for any axis, then the pixel -reference position is set to a value of 1.0 on the pixel axis. -\end{itemize} - -The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding -CRVAL\emph{j}values. - -Again, the above procedure is over-ridden if the Frame is a -\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which -case the conventions of papers II and III are used as described below. - - -\subsubsection{Choice of Axis Ordering} -When reading a \htmlref{FrameSet}{FrameSet} from a -\htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current -\htmlref{Frame}{Frame} of the -resulting FrameSet corresponds to axis $i$ in the FITS header. - -When writing a FrameSet to a FitsChan, the axis ordering for the FITS -header is chosen to make the CD\emph{i\_j} or PC\emph{i\_j} matrix -predominately diagonal. This means that the axis numbering in the FITS -header will not necessarily be the same as that in the AST Frame. - -\subsubsection{Alternate Axis Descriptions} -When reading a \htmlref{FrameSet}{FrameSet} from a -\htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions, -each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added -to the final FrameSet, connected via an appropriate -\htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{Ident} attribute of the Frame is set to hold the single alphabetical -character which is used to identify the set of axis descriptions within -the FITS header (a single space is used for the primary axis descriptions). - -When writing a FrameSet to a FitsChan, it is assumed that the base Frame -represents pixel coordinates, and the current Frame represents the -primary axis descriptions. If there are any other Frames present in the -FrameSet, an attempt is made to create a complete set of ``alternate'' -set of keywords describing each additional Frame. The first character in -the Ident attribute of the Frame is used as the single character -descriptor to be appended to the keyword, with the proviso that a given -character can only be used once. If a second Frame is found with an Ident -attribute which has already been used, its Ident attribute is ignored and -the next free character is used instead. Note, failure to write a set of -alternate axis descriptions does not result in failure of the entire -write operation: the primary axis descriptions are still written, -together with any other alternate axis descriptions which can be produced -successfully. - -\subsection{Paper II - Celestial Coordinates} -These conventions are used when reading a \htmlref{FrameSet}{FrameSet} -from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i} -values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame} -is a \htmlref{SkyFrame}{SkyFrame}. - -\htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword -whose meaning is defined or extended by FITS-WCS paper II. - -\begin{table}[htbp] -\begin{tabular}{|l|p{2.5in}|p{2.5in}|} -\hline -\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} -& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline - -\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types -listed in paper II are supported (note, ``CUBEFACE'' axes are treated as -unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar -HEALPix) are supported.}{Determined by the \htmlref{System}{System} attribute -of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the -\htmlref{WcsMap}{WcsMap} within the FrameSet.} - -\fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.} - -\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values -are stored as attributes of a WcsMap within this Mapping).}{Values are -obtained from the WcsMap in the pixel to WCS Mapping.} - -\fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also -stored as a \htmlref{PVi\_m}{PVi\_m} attribute for the longitude axis of the WcsMap.}{Only -written if not equal to the default value defined in paper II (see -``Choice of LONPOLE/LATPOLE'' below).} - -\fitskey{LATPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also -stored as a PV attribute for the longitude axis of the WcsMap.}{Only -written if not equal to the default value defined in paper II (see -``Choice of LONPOLE/LATPOLE'' below).} - -\fitskey{RADESYS\emph{a}}{Used to set the attributes of the SkyFrame. All -values supported except that ecliptic coordinates are currently always -assumed to be FK5.}{Always written. Determined by the System attribute of -the SkyFrame.} - -\fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute -of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of -the SkyFrame.} - -\fitskey{EPOCH}{Used to set the Equinox attribute of the SkyFrame.}{Only -written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute -of the SkyFrame.} - -\fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{Epoch} attribute of the -SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on -RADESYS and EQUINOX is used if used if DATE-OBS is not present -either.}{Determined by the Epoch attribute of the SkyFrame. Only written -if this attribute has been set to an explicit value (in which case -DATE-OBS is also written).} - -\hline -\end{tabular} -\vspace{3.mm} -\caption{Use of FITS-WCS Paper II keywords} -\label{tab:fitspaper2} -\end{table} - -\subsubsection{Requirements for a Successful Write Operation} -When writing a \htmlref{FrameSet}{FrameSet} in which the WCS -\htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a -\htmlref{FitsChan}{FitsChan}, success depends on the following conditions -being met: - -\begin{enumerate} -\item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame -in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}. -\item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear. -\item The Mapping after the WcsMap (\emph{i.e.} from native spherical to -celestial coordinates) is a spherical rotation for the -celestial axes, and linear for any other axes. -\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan, -and the longitude and latitude axes are separable. In this case the Mapping will -be described by a pair of 1-dimensional look-up tables, using the ``-TAB'' -algorithm described in FITS-WCS paper III. -\end{enumerate} - -If none of the above conditions hold, the write operation will be -unsuccessful. - -\subsubsection{Choice of LONPOLE/LATPOLE} -When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan}, -the choice of LONPOLE and LATPOLE values is determined as follows: - -\begin{enumerate} - -\item If the projection represented by the \htmlref{WcsMap}{WcsMap} is -azimuthal, then any values set for attributes ``PV\emph{i}\_3'' -and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis) -within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a -FrameSet from a FITS-WCS header -results in the original LONPOLE and LATPOLE values being stored within a -WcsMap within the FrameSet. Consequently, if a FrameSet is read from a -FITS-WCS header and it is subsequently written out to a new FITS-WCS -header, the original LONPOLE and LATPOLE values will usually be used in -the new header (the exception being if the WcsMap has been explicitly -modified before being written out again). Any extra rotation of the sky -is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is -possible only if the projection is azimuthal). - -\item If the projection represented by the WcsMap is azimuthal but no -values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4'' -attributes within the WcsMap, then the default LONPOLE and LATPOLE values -are used. This results in no LONPOLE or LATPOLE keywords being stored in -the header since default values are never stored. Any extra rotation of -the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this -is possible only if the projection is azimuthal). - -\item If the projection represented by the WcsMap is not azimuthal, -then the values of LONPOLE and LATPOLE are found by transforming the -coordinates of the celestial north pole (\emph{i.e} longitude zero, -latitude $+\pi/2$) into native spherical coordinates using the inverse of -the \htmlref{Mapping}{Mapping} which follows the WcsMap. - -\end{enumerate} - -\subsubsection{User Defined Fiducial Points} -When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters -PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis -``\emph{i}'') are used to indicate a user-defined fiducial point as -described in section 2.5 of paper II. This results in a shift of IWC -origin being applied \emph{before} the \htmlref{WcsMap}{WcsMap} which converts -IWC into -native spherical coordinates. The values of these projection parameters, -if supplied, are stored as the corresponding \htmlref{PVi\_m}{PVi\_m} attributes -of the WcsMap. - -When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap -determine the native coordinates of the fiducial point (the fixed -defaults for each projection described in paper II are used if the PV -attributes of the WcsMap have not been assigned a value). The -corresponding celestial coordinates are used as the CRVAL\emph{i} -keywords and the corresponding pixel coordinates as the CRPIX\emph{j} -keywords. - -\subsubsection{Common Non-Standard Features} -A collection of common non-standard features are supported when reading a -\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, in addition -to those embodied within the -available encodings of the FitsChan class. These are translated into the -equivalent standard features before being used to create a FrameSet. -Note, the reverse operation is never performed: it is not possible to -produce non-standard features when writing a FrameSet to a FitsChan -(other than those embodied in the available encodings of the FitsChan -class). The supported non-standard features include: - -\begin{itemize} -\item EQUINOX keywords with string values equal to a date preceded -by the letter B or J (\emph{e.g.} ``B1995.0''). - -\item EQUINOX or EPOCH keywords with value zero (these are converted to -B1950). - -\item The IRAF ``ZPX'' projection is represented by a -\htmlref{WcsMap}{WcsMap} with type of -AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn} -keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the -WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic -ZPN projection by including ``lngcor'' or ``latcor'' terms. These are -supported if they use half cross-terms, in either simple or Chebyshev -representation. - -\item The IRAF ``TNX'' projection is represented by a WcsMap with type of -AST\_\_TPN (a distorted TAN projection retained within the WcsMap class -from an early draft of the FITS-WCS paper II). Projection parameter values -are read from any WAT\emph{i\_nnn} keywords, and corresponding PV -attributes are set in the WcsMap. If the TNX projection cannot be -converted exactly into an AST\_\_TPN projection, ASTWARN keywords are -added to the FitsChan containing a warning message (but only if the -\htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently, -TNX projections that use half cross-terms, in either simple or Chebyshev -representation, are supported. - -\item ``QV'' parameters for TAN projections (as produced by -\xref{AUTOASTROM}{sun242}{} -\footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}} -are renamed to the equivalent ``PV'' parameters. - -\item TAN projections that have associated ``PV'' parameters on the -latitude axis are converted to the corresponding TPN (distorted TAN) -projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute -of the FitsChan class. - -\end{itemize} - -\subsection{Paper III - Spectral Coordinates} -These conventions are used when reading a \htmlref{FrameSet}{FrameSet} -from a \htmlref{FitsChan}{FitsChan} which includes appropriate -CTYPE\emph{i} values, and when writing a FrameSet in which -the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}. - -\htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword -whose meaning is defined or extended by FITS-WCS paper III. - -\begin{table}[htbp] -\begin{footnotesize} -\begin{tabular}{|l|p{2.5in}|p{2.5in}|} -\hline -\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}} -& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline - -\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types -listed in paper III are supported algorithm (the ``-LOG'' algorithm may -also be applied to non-spectral linear axes; the ``-TAB'' algorithm -requires the \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the -SpecFrame and the nature of the pixel to SpecFrame -\htmlref{Mapping}{Mapping}.} - -\fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of -the SpecFrame (note, SpecFrames always have an ``active'' Units attribute -(see \htmlref{astSetActiveUnit}{astSetActiveUnit}).}{Always written.} - -\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values -are stored as attributes of a \htmlref{GrismMap}{GrismMap}).} -{Set from the attributes of the GrismMap, if present, and if set explicitly.} - -\fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{StdOfRest} -attribute of the SpecFrame (all systems are supported except CMBDIPOL).} -{Set from the StdOfRest attribute of the SpecFrame, but only if it has been -set explicitly.} - -\fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.} - -\fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and -\htmlref{ObsLat}{ObsLat} attributes of the Frame (the observers -height above sea level is ignored).}{Set from the ObsLon and ObsLat -attributes of the Frame, if they have been set explicitly (it is -assumed that the observer is at sea level).} - -\fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of -the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has -been set explicitly.} - -\fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the -SpecFrame -(all systems are supported except CMBDIPOL).} {Set from the SourceVRF -attribute of the SpecFrame.} - -\fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{SourceVel} -attribute of the SpecFrame (the SourceVRF attribute -is first set to the system indicated by the SSYSSRC keyword, and the -ZSOURCE value is then converted to an apparent radial velocity and stored -as the SourceVel attribute).} -{Set from the SourceVel attribute of -the SpecFrame, if it has been set explicitly (the SourceVel value is -first converted from apparent radial velocity to redshift).} - -\fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the -SpecFrame that define the standard of rest and the observers position.} - -\fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{RestFreq} -attribute of the SpecFrame.}{Set from the RestFreq attribute of the -SpecFrame, but only if the System attribute is not set to -``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set -explicitly.} - -\fitskey{RESTWAV\emph{a}}{Used to set the RestFreq -attribute of the SpecFrame (after conversion from wavelength to frequency).} -{Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the -System attribute is set to ``WAVE'', ``VOPT'', ``ZOPT'' or -``AWAV'', and only if RestFreq has been set explicitly.} - -\fitskey{CNAME\emph{ia}}{Used to set the Label attributes of -the WCS Frame keywords.}{Set from the Label attributes of the WCS Frame, -if they have been set explicitly.} -\hline -\end{tabular} -\end{footnotesize} -\vspace{3.mm} -\caption{Use of FITS-WCS Paper III keywords} -\label{tab:fitspaper3} -\end{table} - -\subsubsection{Requirements for a Successful Write Operation} -When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a -\htmlref{FitsChan}{FitsChan}, the write operation is successful only if -the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame -in the FrameSet) to the SpecFrame satisfies one of the following conditions: - -\begin{enumerate} -\item It is linear. -\item It is logarithmic. -\item It is linear if the SpecFrame were to be re-mapped into one of the -other spectral systems supported by FITS-WCS paper III. -\item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from -pixel coordinates to grism parameter) is linear, and the Mapping after the -GrismMap is either null or represents a change of spectral system from wavelength (air or -vacuum) to one of the supported spectral systems. -\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan. -\end{enumerate} - -If none of the above conditions hold, the write operation will be -unsuccessful. Note, if the FitsChan's TabOK attribute is set to a positive -non-zero value then any Mapping that does not meet any of the earlier conditions -will be written out as a look-up table, using the ``-TAB'' algorithm described -in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or -negative in the FitsChan, then the write operation will be unsuccessful unless -one of the eaerlier conditions is met.\footnote{If the -TAB algorithm is used, the -positive value of the TabOK attribute is used as the table version number -(the EXTVER header) in the associated FITS binary table.} - -\subsubsection{Common Non-Standard Features} -The following non-standard features are supported when reading spectral -axes from a \htmlref{FitsChan}{FitsChan}: - -\begin{itemize} -\item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes -(specified in early drafts of paper III) to the corresponding -``-X2P'' form. -\item Conversion of ``RESTFREQ'' to ``RESTFRQ'' -\end{itemize} - -\subsection{Paper IV - Coordinate Distortions} - -This paper proposes that an additional 4 character code be appended to -the end of the CTYPE\emph{i} keyword to specify the nature of any -distortion away from the basic algorithm described by the first 8 -characters of the CTYPE\emph{i} value. Currently AST ignores all such -codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} (except for the ``-SIP'' code -defined by the Spitzer Space Telescope project - see below). This means that -a FrameSet can still be read from such headers, but the \htmlref{Mapping}{Mapping} which gives -the WCS position associated with a given pixel position will reflect only -the basic algorithm and will not include the effects of the distortion. - -If such a FrameSet is then written out to a FitsChan, the resulting -CTYPE\emph{i} keywords will include no distortion code. - -\subsubsection{The ``-SIP'' distortion code} - -The Spitzer Space Telescope project -(\url{http://www.spitzer.caltech.edu/}) -has developed its own system for encoding 2-dimensional image distortion -within a FITS header, based on the proposals of paper IV. A description -of this system is available in -\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}. In this -system, the presence of distortion is indicated by appending the -distortion code ``-SIP'' to the CTYPE\emph{i} keyword values for the -celestial axes. The distortion takes the form of a polynomial function -which is applied to the pixel coordinates, after subtraction of the -CRPIX\emph{j} values. - -This system is a strictly 2 dimensional system. When reading a -\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which -includes the ``-SIP'' distortion code, AST assumes that it -is only applied to the first 2 WCS axes in a FITS header (i.e. -CTYPE1 and CTYPE2). If the ``-SIP'' distortion code is attached to other -axes, it will be ignored. The distortion itself is represented by a -\htmlref{PolyMap}{PolyMap} within the resulting FrameSet. - -If a FrameSet is read from a FitsChan which includes ``-SIP'' -distortion, and an attempt is then made to write this FrameSet out to a -FitsChan, the write operation will fail unless the distortion is -insignificant (\emph{i.e.} is so small that the tests for linearity built -into AST are passed). In this case, no distortion code will be appended to -the resulting CTYPE\emph{i} keyword values. - -\newpage -\section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes} - -\subsection{Changes Introduced in V1.1} - -The following describes the most significant changes which occurred in -the AST library between versions V1.0 and V1.1 (not the most recent -version): - -\begin{enumerate} - -\item A new ``How To\ldots'' section (\secref{ss:howto}) has been -added to this document. It contains simple recipies for performing -commonly-required operations using AST. - -\item A new \htmlref{astUnformat}{astUnformat} function has been provided to read formatted -coordinate values for the axes of a \htmlref{Frame}{Frame} -(\secref{ss:unformattingaxisvalues}). In essence, this function is the -inverse of \htmlref{astFormat}{astFormat}. It may be used to decode user-supplied formatted -values representing coordinates, turning them into numerical values -for processing. Celestial coordinates may also be read using this -function (\secref{ss:unformattingskyaxisvalues}) and free-format input -is supported. - -\item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting -celestial coordinate values now allows the degrees/hours field to be -omitted, so that celestial coordinates may be given in (\emph{e.g.}) -arc-minutes and/or arc-seconds -(\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours -field is no longer included by default. A new ``t'' format specifier -has been introduced (see the Format attribute) to allow minutes and/or -seconds of time to be specified if required. - -\item A new function \htmlref{astMapBox}{astMapBox} has been introduced. This allows you to -find the extent of a ``bounding box'' which just encloses another box -after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to -calculate the size which an image would have if it were transformed by -the Mapping. - -\item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced -(\secref{ss:intramaps}). This is a specialised form of Mapping which -encapsulates a privately-defined coordinate transformation function -(\emph{e.g.}\ written in C) so that it may be used like any other AST -Mapping. This allows you to create Mappings that perform any -conceivable coordinate transformation. - -\item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically -preserved whenever changes are made to any attributes which affect the -current Frame (either by setting or clearing their values). This is -accomplished by appropriately re-mapping the current Frame to account -for any change to the coordinate system which it represents -(\secref{ss:framesetintegrity}). - -\item The internal structure of a FrameSet is now automatically tidied -to eliminate redundant nodes whenever any of its Frames is removed or -re-mapped. Automatic simplification of any compound Mappings which -result may also occur. The effect of this change is to prevent the -accumulation of unnecessary structure in FrameSets which are -repeatedly modified. - -\item Some improvements have been made to the algorithms for -simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. - -\item The textual representation used for some Objects -(\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed -slightly, but remains compatible with earlier versions of AST. - -\item Interfaces to the internal functions and macros used by AST for -handling memory and error conditions are now provided \emph{via} the -``ast.h'' header file. This is for the benefit of those writing -(\emph{e.g.}) new graphics interfaces for AST. - -\item A problem has been fixed which could result when using \htmlref{astRead}{astRead} -to read FITS headers in which the CDELT value is zero. Previously, -this could produce a Mapping whose inverse transformation was not -defined and this could unnecessarily restrict the use to which it -could be put. The problem has been overcome by supplying a suitable -small CDELT value for FITS axes which have only a single pixel. - -\item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap} -to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of -a compound Mapping which is being simplified using astSimplify. - - -\item A problem has been fixed which could prevent tick marks being -drawn on a coordinate axis close to a singularity in the coordinate -system. -\end{enumerate} - -\subsection{Changes Introduced in V1.2} - -The following describes the most significant changes which occurred in -the AST library between versions V1.1 and V1.2 (not the most recent -version): - -\begin{enumerate} -\item A new function, \htmlref{astPolyCurve}{astPolyCurve}, has been introduced to allow more -efficient plotting of multiple geodesic curves -(\secref{ss:plottinggeodesics}). - -\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced -to perform resampling of gridded data such as images -(\emph{i.e.}\ re-gridding) under the control of a geometrical -transformation specified by a \htmlref{Mapping}{Mapping}. - -\item The command-line options ``$-$pgp'' and ``$-$pgplot'', which -were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and -``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option -``$-$pgp'' now causes linking with the Starlink version of PGPLOT -(which uses GKS to generate its output), while ``$-$pgplot'' links -with the standard (or ``native'') version of PGPLOT. - -\item The function \htmlref{astMapBox}{astMapBox} has been changed to execute more quickly, -although this has been achieved at the cost of some loss of robustness -when used with difficult Mappings. - -\item A new value of ``FITS-IRAF'' has been introduced for the -\htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an -interim solution to the problem of storing coordinate system -information in FITS headers, until the proposed new FITS-WCS standard -becomes stable. - -\item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by -reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame} -of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to -``GRID''. This reflects the fact that this Frame represents FITS data -grid coordinates (equivalent to FITS pixel coordinates---see -\secref{ss:domainconventions}). Previously, this Domain value was not -set. - -\item \htmlref{astFindFits}{astFindFits} now ignores trailing spaces in its keyword template. - -\item \htmlref{astPutFits}{astPutFits} now recognises ``D'' and ``d'' as valid exponent -characters in floating point numbers. - -\item The FitsChan class is now more tolerant of common minor -violations of the FITS standard. - -\item The FitsChan class now incorporates an improved test for the -linearity of Mappings, allowing more reliable conversion of AST data -into FITS (using ``foreign'' FITS encodings). - -\item Some further improvements have been made to the algorithms for -simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}. - -\item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap} -class. This allows improved simplification of compound Mappings -(CmpMaps) involving SphMaps and typically improves performance when -handling FITS world coordinate information. - -\item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of -AST\_\_BAD automatically to all output coordinates. If certain output -coordinates do not depend on the affected input coordinate(s) because -the relevant matrix elements are zero, then they may now remain valid. - -\item A minor bug has been corrected which could cause certain -projections which involve half the celestial sphere to produce valid -coordinates for the other (unprojected) half of the sphere as well. - -\item A bug has been fixed which could occasionally cause \htmlref{astConvert}{astConvert} -to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was -possible when, in fact, it wasn't. -\end{enumerate} - -\subsection{Changes Introduced in V1.3} - -The following describes the most significant changes which occurred in -the AST library between versions V1.2 and V1.3 (not the most recent -version): - -\begin{enumerate} -\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to -provide efficient resampling of gridded data, such as spectra and -images, under the control of a geometrical transformation specified by -a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported. - -\item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised -form of Mapping which implements 2-dimensional pincushion or barrel -distortion. - -\item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too -many digits when formatting floating point values for inclusion in a -FITS header if the numerical value was in the range -0.00099999\ldots -to -0.0001. - -\item A bug has been fixed which could cause a FitsChan to lose the -comment associated with a string value in a FITS header. - -\item A FitsChan now reports an error if it reads a FITS header which -identifies a non-standard sky projection (previously, this was -accepted without error and a Cartesian projection used instead). - -\item A bug has been fixed which could prevent conversion between the -coordinate systems represented by two CmpFrames. This could only occur -if the CmpFrames contained a relatively large number of nested Frames. - -%\item A bug has been fixed which could cause a program to crash if -%FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet} -%had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The -%problem could only occur if the nested structure was loaded from a data -%c+ -%file (using \htmlref{astRead}{astRead}). -%c- -%f+ -%file (using AST\_READ). -%f- -% -\item Further improvements have been made to the simplification of -compound Mappings, including fixes for several bugs which could cause -indefinite looping or unwanted error messages. - -\item Some memory leaks have been fixed. - -\item A small number of documentation errors have been corrected. -\end{enumerate} - -\subsection{Changes Introduced in V1.4} - -The following describes the most significant changes which have occurred -in the AST library between versions V1.3 and V1.4 (not the most recent -version): - -\begin{enumerate} -\item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of -\htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a -flexible and transportable way using arithmetic operations and -mathematical functions similar to those available in C. - -\item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation functions -used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{astIntraReg}{astIntraReg}) now -require a ``this'' pointer as their first parameter. \textbf{Existing -implementations will not continue to work correctly with this version -of AST unless this parameter is added.} There is no need for existing -software to make use of this pointer, but it must be present. - -This change has been introduced so that transformation functions can gain -access to IntraMap attributes. - -\item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap -class. This allows the transformation functions used by IntraMaps to -adapt to produce the required transformation on a per-IntraMap basis -(\secref{ss:intraflag}). - -\item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the -length of major and minor tick marks on coordinate axes, may now be -subscripted using an axis number. This allows tick marks of different -lengths to be used on each axis. It also allows tick marks to be -suppressed on one axis only by setting the length to zero. - -\item The value of the Plot attribute NumLab, which controls the -plotting of numerical labels on coordinate axes, no longer has any -effect on whether labelling of a coordinate grid is interior or -exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute). - -\item The \htmlref{FitsChan}{FitsChan} class now provides some support for the -IRAF-specific ``ZPX'' sky projection, which is converted transparently -into the equivalent FITS ``ZPN'' projection (see the description of the -\htmlref{Encoding}{Encoding} attribute for details). - -\item The FitsChan class now recognises the coordinate system ``ICRS'' -(International Celestial Reference \htmlref{System}{System}) as equivalent to -``FK5''. This is an interim measure and full support for the -(exceedingly small) difference between ICRS and FK5 will be added at a -future release. - -Note that ``ICRS'' is not yet recognised as a coordinate system by other -classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the -importation of foreign data. - -\item A bug in the FitsChan class has been fixed which could result in -longitude values being incorrect by 180 degrees when using cylindrical -sky projections, such as the FITS ``CAR'' projection. - -\item A bug in the FitsChan class has been fixed which could result in -the FITS sky projection parameters ProjP(0) to ProjP(9) being -incorrectly named PROJP1 to PROJP10 when written out as FITS cards. - -\item A bug in the FitsChan class has been fixed which could cause -confusion between the FITS-IRAF and FITS-WCS encoding schemes if both -a CD matrix and a PC matrix are erroneously present in a FITS header. - -\item Some minor memory leaks have been fixed. - -\item A small number of documentation errors have been corrected. -\end{enumerate} - -\subsection{Changes Introduced in V1.5} - -The following describes the most significant changes which have -occurred in the AST library between versions V1.4 and V1.5 (not the most -recent version): - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft -FITS WCS standard, described in the two papers ``Representation of world -coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th -November, 1999), and ``Representation of celestial coordinates in FITS'' -(M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are -available at -\url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}. - -The FITS-WCS encoding now uses these updated conventions. The main -changes are: - -\begin{itemize} -\item Rotation and scaling of pixel axes is now represented by a matrix -of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and -\texttt{CDELTj} keywords. -\item \htmlref{Projection}{Projection} parameters are now associated with particular axes and -are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm} -keywords. -\item The tangent plane projection (``TAN'') can now include optional -polynomial correction terms. -\item An entire set of keywords must be supplied for each set of secondary -axis descriptions, and each such keyword must finish with a single -character indicating which set it belongs to. This means that keywords -which previously occupied eight characters have been shorten to seven to -leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}. -\end{itemize} - -\item Two new encodings have been added to the FitsChan class: -\begin{description} - -\item [FITS-PC] This encoding uses the conventions of the now superseded -FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords -\texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation. -These are the conventions which were used by the FITS-WCS encoding prior -to version 1.5 of AST. This encoding is provided to allow existing data -which use these conventions to be read. It should not in general be used -to create new data. - -\item [FITS-AIPS] This encoding is based on the conventions described in the -document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen -(revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu -/fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and -\texttt{CDELTi} keywords to describe axis rotation and scaling. - -\end{description} - -\item The FitsChan class now provides some support for the IRAF-specific -``TNX'' sky projection, which is converted transparently into the -equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding} -attribute for details). - -\item FrameSets originally read from a DSS encoded FITS header can now be -written out using the FITS-WCS encoding (a TAN projection with correction -terms will be used) in addition to the DSS encoding. The reverse is also -possible: FrameSets originally read from a FITS-WCS encoded FITS header -and which use a TAN projection can now be written out using the DSS -encoding. - -\item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet} -conforms to the FITS-WCS model has been improved so that FrameSets -including more complex mixtures of parallel and serial Mappings -can be written out using the FITS-WCS encoding. - -\item The FitsChan class has been changed so that long strings included in -the description of an \htmlref{Object}{Object} can be saved and restored without truncation -when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles, -mathematical expressions, \emph{etc.} were truncated if they exceeded the -capacity of a single FITS header card. They are now split over several -header cards so that they can be restored without truncation. Note, this -facility is only available when using NATIVE encoding. - -\item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which -can be used to select potentially dangerous conditions under which -warnings should be issued. These conditions include (for instance) -unsupported features within non-standard projections, missing keywords -for which default values will be used, \emph{etc}. - -\item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the -FITS-WCS encoding in the FitsChan class: -\begin{itemize} -\item Projection parameters are now associated with a particular axis and -are specified using a new set of attributes called PVj\_m. Here, ``j'' is -the index of an axis of WcsMap, and ``m'' is the index of the projection -parameter. -\item The old attributes ProjP(0) to ProjP(9) are still available but are -now deprecated in favour of the new PVj\_m attributes. They are interpreted -as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of -the latitude axis. -\item The GLS projection projection has been renamed as SFL, but the -AST\_\_GLS type has been retained as an alias for AST\_\_SFL. -\end{itemize} - -\end{enumerate} - -\subsection{Changes Introduced in V1.6} - -The following describes the most significant changes which have -occurred in the AST library between versions V1.5 and V1.6: - -\begin{enumerate} - -\item The C interface to several methods (\htmlref{astTranN}{astTranN}, \htmlref{astMark}{astMark} and -\htmlref{astPolyCurve}{astPolyCurve}) have been changed to make them easier to call from C++. -Parameters which previously had type ``double (*)[]'' have been changed -to the simpler ``double *''. Using the old types may result in non-fatal -compiler warnings, but should not change the behaviour of the methods. - -\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups -of tick marks to be skipped when using very small gaps. - -\item A bug has been fixed in the Plot class which could cause axes to be -labeled outside the visible window, resulting in no axes being visible. - -\item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the -WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of -the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding -Frames in the returned FrameSet. When writing a FrameSet to a FITS header -the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the -header. - -\item The FITS-WCS encoding used by the FitsChan class now attempts to -retain the identification letter associated with multiple axis -descriptions. When reading a FrameSet from a FITS header, the identification -letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a -FrameSet to a FITS header, the identification letter is read from the -Ident attribute of each Frame. The letter to associate with each Frame -can be changed by assigning a new value to the Frame's Ident attribute. - -\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the -FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to -``Unknown'' if the CTYPE keywords in the supplied header refers to an -unknown celestial coordinate system. Previously, a Frame was used instead -of a SkyFrame. - -\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the -FitsChan class no longer report an error if the FITS header contains no -CTYPE keywords. It is assumed that a missing CTYPE keyword implies that -the world coordinate system is linear and identically equal to -``intermediate world coordinates''. - -\item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute -of the FitsChan class. This value causes warnings to be issued if CTYPE -keywords are missing from foreign encodings. - -\item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan -class. This is a read-only, space separated list of all the known condition -names which can be specified in the Warnings attribute. - -\item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in -a FrameSet read using a foreign encoding. The Title is based on the Domain -name of the Frame. If the Frame has no Domain name, the default Title -supplied by the Frame class is retained. - -\item The FitsChan class uses the comments associated with CTYPE -keywords as axis labels when reading a foreign encoding. This behaviour -has been modified so that the default labels provided by the Frame class -are retained (instead of using the CTYPE comments) if any of the CTYPE -comments are identical. - -\item A new ``interpolation'' scheme identified by the symbolic constant -AST\_\_BLOCKAVE has been added to the AST\_RESAMPLE$<$X$>$ set of -functions. The new scheme calculates each output pixel value by finding -the mean of the input pixels in a box centred on the output pixel. - -\item The SkyFrame class can now be used to represent an arbitrary spherical -coordinate system by setting its System attribute to ``Unknown''. - -\item The indices of the latitude and longitude axes of a SkyFrame can -now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The -effects of any axis permutation is taken into account. - -\item A new attribute called Ident has been added to the \htmlref{Object}{Object} class. -This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID) -its value is transferred to the new Object when a copy is made. - -\item A bug has been fixed which could prevent complex CmpFrames -behaving correctly (for instance, resulting in the failure of attempts -to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself). - -\end{enumerate} - -\subsection{Changes Introduced in V1.7} - -The following describes the most significant changes which have -occurred in the AST library between versions V1.6 and V1.7: - -\begin{enumerate} - -\item The \htmlref{Frame}{Frame} class has a new method called -\htmlref{astAngle}{astAngle} -which returns the angle subtended by two points at a third point within a -2 or 3 dimensional Frame. - -\item The Frame class has a new method called -\htmlref{astOffset2}{astOffset2} -which calculates a position which is offset away from a given starting -point by a specified distance along a geodesic curve which passes -through the starting point at a given position angle. It can only be used -with 2-dimensional Frames. - -\item The Frame class has a new method called -\htmlref{astAxDistance}{astAxDistance} -which returns the increment between two supplied axis values. For -axes belonging to SkyFrames, the returned value is normalized into -the range $\pm\pi$. - -\item The Frame class has a new method called -\htmlref{astAxOffset}{astAxOffset} -which returns an axis value a given increment away from a specified axis -value. For axes belonging to SkyFrames, the returned value is normalized into -the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude -axes). - -\item The \htmlref{Plot}{Plot} class has a new method called -\htmlref{astGenCurve}{astGenCurve} -which allows generalised user-defined curves to be drawn. The curve is -defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve -into the corresponding position in the current Frame of the Plot. The new -method then maps these current Frame position into graphics coordinates, -taking care of any non-linearities or discontinuities in the mapping. - -\item The Plot class has a new method called -\htmlref{astGrfSet}{astGrfSet} -which allows the underlying primitive graphics functions to be selected -at run-time. Previously, the functions used by the Plot class to produce -graphics could only be selected at link-time, using the options of the -\htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride -the functions established at link-time, by specifying alternative -primitive graphics routines. In addition, the two new Plot methods -\htmlref{astGrfPush}{astGrfPush} and \htmlref{astGrfPop}{astGrfPop} -allow the current graphics routines to be saved and restore on a -first-in-last-out stack, allowing temporary changes to be made to the set -of registered graphics routines. - -\item The DrawAxes attribute of the Plot class can now be specified -independantly for each axis, by appending the axis index to the -end of the attribute name. - -\item A bug has been fixed in the Plot class which could result in axis -labels being drawn on inappropriate edges of the plotting box when using -``interior'' labelling. - -\item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps -to be corrupted after transforming any points. - -\item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause -inappropriate ordering of headers within a FitsChan when writing or -reading objects using NATIVE encodings. - -\item A bug has been fixed in the FitsChan class which could cause the -celestial longitude of a pixel to be estimated incorrectly by 180 degrees -if the reference point is at either the north or the south pole. - -\end{enumerate} - - -\subsection{Changes Introduced in V1.8-2} - -The following describes the most significant changes which have -occurred in the AST library between versions V1.7 and V1.8-2: - -\begin{enumerate} - -\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows - longitude values to be displayed in the range $-\pi$ to $+\pi$, instead - of the usual range zero to $2.\pi$. - -\item Some new -functions (\htmlref{astAngle}{astAngle}, \htmlref{astAxAngle}{astAxAngle}, \htmlref{astResolve}{astResolve}, \htmlref{astOffset2}{astOffset2}, \htmlref{astAxOffset}{astAxOffset}, -\htmlref{astAxDistance}{astAxDistance}) -have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space -to be performed without needing to know the underlying geometry -of the co-ordinate system (for instance, whether it is Cartesian or -spherical). - -Note, version 1.8-1 contained many of these facilities, but -some have been changed in version 1.8-2. Particularly, positions angles -are now referred to the second Frame axis for \emph{all} classes of Frames -(including SkyFrames), and the -astBear function has been replaced by astAxAngle. - -\end{enumerate} - -\subsection{Changes Introduced in V1.8-3} - -The following describes the most significant changes which -occurred in the AST library between versions V1.8-2 and V1.8-3: - -\begin{enumerate} - -\item A new method called \htmlref{astDecompose}{astDecompose} has been added to the \htmlref{Mapping}{Mapping} class -which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and -\htmlref{CmpFrame}{CmpFrame} objects. - -\item Functions within proj.c and wcstrig.c have been renamed to avoid name -clashes with functions in more recent versions of Mark Calabretta's wcslib -library. - -\end{enumerate} - -\subsection{Changes Introduced in V1.8-4} - -The following describes the most significant changes which -occurred in the AST library between versions V1.8-3 and V1.8-4: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be -used to select the default reference frame and equinox to be used if -a FitsChan with foreign encoding contains no indication of the -reference frame or equinox. - -\item A bug has been fixed in the FitsChan class which could prevent -\htmlref{astWrite}{astWrite} from creating a set of FITS headers from an otherwise valid -\htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding. - -\item A bug has been fixed in the FitsChan class which could cause -\htmlref{astRead}{astRead} to mis-interpret the FITS CROTA keyword when using FITS-AIPS -encoding. - -\end{enumerate} - -\subsection{Changes Introduced in V1.8-5} - -The following describes the most significant changes which -occurred in the AST library between versions V1.8-4 and V1.8-5: - -\begin{enumerate} - -\item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2, -Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2. -These allow graphical attributes (colour, width, etc) to be set for each -axis individually. Previously, graphical attributes could only be set for -both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs, -TextLabs and Ticks. - -\end{enumerate} - - -\subsection{Changes Introduced in V1.8-7} - -The following describes the most significant changes which -occurred in the AST library between versions V1.8-5 and V1.8-7: - -\begin{enumerate} - -\item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class -which controls the way CAR projections are handled when reading a -\htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR -projection to represent a simple linear transformation between pixel -coordinates and celestial sky coordinates. This is not consistent with -the definition of the CAR projection in the draft FITS-WCS standard, which -requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native -spherical coordinates to celestial spherical coordinates, thus making the -Mapping non-linear. Setting CarLin to 1 forces -\htmlref{astRead}{astRead} -to ignore the FITS-WCS standard and treat any CAR projections as simple -linear Mappings from pixel coordinates to celestial coordinates. - -\item A bug has been fixed which could result in axis Format attributes -set by the user being ignored under certain circumstances. - -\item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class -has been fixed. This bug could result in extra ticks marks being displayed at -inappropriate positions. This bug manifested itself, for instance, if the -Mapping represented by the Plot was a simple Cartesian to Polar Mapping. -In this example, the bug caused tick marks to be drawn at negative radius -values. - -\item A bug has been fixed which could prevent attribute settings from -being read correctly by -\htmlref{astSet}{astSet}, -etc., on certain platforms (MacOS, for instance). - -\end{enumerate} - -\subsection{Changes Introduced in V1.8-8} - -The following describes the most significant changes which -occurred in the AST library between versions V1.8-7 and V1.8-8: - -\begin{enumerate} - -\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause -problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS -information stored in the form of Digitised Digitised Sky Survey (DSS) -keywords. These problems only occurred for DSS fields in the southern -hemisphere, and resulted in pixel positions being mapped to sky positions -close to the corresponding \emph{northern} hemispshere field. - -\item A new method called -\htmlref{astBoundingBox}{astBoundingBox} -has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of -the previous graphical output produced by a Plot method. - -\item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class -which suppresses the graphical output normally produced by Plot methods. -All the calculations needed to produce the normal output are still -performed however, and so the bounding box returned by the new -astBoundingBox -method is still usable. - -\item Bugs have been fixed related to the appearance of graphical output -produced by the Plot class. These bugs were to do with the way in which -graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.) -interacted with the corresponding generic element (e.g. -\texttt{Colour(axes)}, etc.). - -\end{enumerate} - - -\subsection{Changes Introduced in V1.8-13} - -The following describes the most significant changes which occurred -in the AST library between versions V1.8-8 and V1.8-13: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords -are only produced by \htmlref{astWrite}{astWrite} when necessary. For zenithal projections such as -TAN, the LONPOLE keyword can always take its default value and so is -not included in the FITS header produced by astWrite. -Previously, the unnecessary production of a LONPOLE keyword could prevent -FrameSets being written out using encodings which do not support the -LONPOLE keyword (such as FITS-IRAF). - -\item The FitsChan class has been modified to retain leading and trailing -spaces within COMMENT cards. - -\item The FitsChan class has been modified to only use CTYPE comments as -axis labels if all non-celestial axes have unique non-blank comments -(otherwise the CTYPE keyword values are used as labels). - -\item The FitsChan class has been modified so that it does not append a -trailing ``Z'' character to the end of DATE-OBS keyword values. - -\item The FitsChan class has been modified to use latest list of FITS-WCS -projections, as described in the FITS-WCS paper II, ``Representations of -celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23 -April 2002). Support has been retained for the polynomial correction -terms which previous drafts have allowed to be associated with TAN -projections. - -\item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN -(which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN -projection type now represents a simple TAN projection and has no -associated projection parameters. In addition, the usage of projection -parameters has been brought into line with the the FITS-WCS paper II. - -\item The WcsMap class has been modified so that a ``get'' operation on a -projection parameter attribute will return the default value defined in the -FITS-WCS paper II if no value has been set for the attribute. Previously, a -value of AST\_\_BAD was returned in such a situation. - -\item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which -allow a ``plottable range'' to be specified for each Frame axis. The grid -produced by the \htmlref{astGrid}{astGrid} method will not extend beyond these limits. - -\end{enumerate} - -\subsection{Changes Introduced in V2.0} - -Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by -applications linked with earlier versions of AST. This applies to Frame -descriptions created using: -\begin{itemize} -\item the \htmlref{Channel}{Channel} class -\item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used -\item the \htmlref{astShow}{astShow} function -\end{itemize} - -Applications must be re-linked with AST V2.0 in order to be able to read -Frame descriptions created by AST v2.0. - -The following describes the most significant changes which have -occurred in the AST library between versions V1.8-13 and V2.0 (the -current version): - -\begin{enumerate} - -\item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame} -class has been changed from ``CMP'' to a string formed by concatenating -the Domain attributes of the two component Frames, separated by a minus -sign. If both component Domains are blank, then the old default of -``CMP'' is retained for the CmpFrame Domain. - -\item The implementation of the -\htmlref{astWrite}{astWrite} function -within the FitsChan class has been modified. It will now attempt to -produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the -number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the -\htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This -has always been possible with NATIVE encoding, but has not previously -been possible for foreign encodings. The WCSAXES keyword is used to store -the number of WCS axes in the FITS header. - -\item Another change to the -astWrite function -within the FitsChan class is that the ordering of ``foreign'' axes -(\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix -as diagonal as possible - any element of axis transposition is removed by -this re-ordering as recommended in FITS-WCS paper I. Previously the -ordering was determined by the order of the axes in the Current Frame of -the supplied FrameSet. This change does not affect NATIVE encoding. - -\item Support for spectral coordinate systems has been introduced -throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}. -The SpecFrame is a 1-dimensional Frame which can be used to describe -positions within an electromagnetic spectrum in various systems -(wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred -to various standards of rest (topocentric, geocentric, heliocentric -LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral -axis values between these various systems and standards of rest. Note, -FitsChans which have a foreign encoding (\emph{i.e.} any encoding other -than NATIVE) are not yet able to read or write these new classes. - -\item Facilities have been added to the Frame class which allow -differences in axis units to be taken into account when finding a Mapping -between two Frames. In previous versions of AST, the Unit attribute was a -purely descriptive item intended only for human readers - changing the -value of Unit made no difference to the behaviour of the Frame. As of -version 2.0, the Unit attribute can influence the nature of the Mappings -between Frames. For instance, if the -astFindrame or \htmlref{astConvert}{astConvert} -method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m'' -and another Axis with Unit set to ``km'', then the method will return a -\htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes. -These facilities assume that units are specified following the rules -included in FITS-WCS paper I (\emph{Representation of World -Coordinates in FITS}, Greisen \& Calabretta). - -In order to minimise the risk of breaking existing software, the default -behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.} -to retain the previous behaviour). However, the new Frame method -\htmlref{astSetActiveUnit}{astSetActiveUnit} -may be used to ``activate'' (or deactivate) the new facilities within a -specific Frame. Note, the new SpecFrame class is different to the simple -Frame class in that the new facilities for handling units are always active -within a SpecFrame. - -\item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been -moved to the parent Frame class. This enables all sub-classes of Frame -(such as the new SpecFrame class) to share these attributes, and to provide -suitable options for each class. - -\item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows -control over the alignment process performed by the methods -\htmlref{astFindFrame}{astFindFrame} and astConvert. - - -\item The CmpFrame class has been modified so that attributes of a -component Frame can be accessed without needing to extract the Frame first. -To do this, append an axis index to the end of the attribute name. For -instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order), -then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the -``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute -of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently -``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the -CmpFrame will refer to the System attribute of the SpecFrame, whereas the -``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the -System attribute of the SkyFrame (the ``System'' attribute without an axis -specifier will refer to the System attribute of the CmpFrame as a whole, -since System is an attribute of all Frames, and a CmpFrame is a Frame and -so has its own System value which is independant of the System attributes -of its component Frames). - -\item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit -overlapping axis labels, and the abbreviation of redundant leading fields -within sexagesimal axis labels, have been improved to avoid some anomolous -behaviour in previous versions. - -\item The curve drawing algorithm used by the Plot class has been -modified to reduce the chance of it ``missing'' small curve sections, -such as may be produced if a grid line cuts across the plot very close to -a corner. Previously, these missed sections could sometimes result in -axis labels being omitted. - -\item A new function -(\htmlref{astVersion}{astVersion}) -has been added to return the version of the AST library in use. - -\item Bugs have been fixed in the Plot class which caused serious problems -when plotting high precision data. These problems could range from the -omission of some tick marks to complete failure to produce a plot. - -\end{enumerate} - -Programs which are statically linked will need to be re-linked in -order to take advantage of these new facilities. - - -\subsection{Changes Introduced in V3.0} - -The following describes the most significant changes which -occurred in the AST library between versions V2.0 and V3.0: - -\begin{enumerate} - -\item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring -the FITS-WCS encoding into line with the current versions of the FITS-WCS -papers (see -\url{http://www.atnf.csiro.au/people/mcalabre/WCS/}): - -\begin{itemize} - -\item The rotation and scaling of the pixel axes may now be specified using -either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute -called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which -set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS -header. - -\item The FITS-WCS encoding now supports most of the conventions -described in FITS-WCS paper III for the description of spectral -coordinates. The exceptions are that the SSYSOBS keyword is not -supported, and WCS stored in tabular form (as indicated by the ``-TAB'' -algorithm code) is not supported. - - -\item User-specified fiducial points for WCS projections are now -supported by FitsChans which use FITS-WCS encoding. This use keywords -PVi\_0, PVi\_1 and PVi\_2 for the longitude axis. - -\item When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3 -and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE -and LATPOLE keywords which may be present. When writing a FITS-WCS header, -both forms are written out. - -\item The number of WCS axes is stored in the WCSAXES keyword if its value -would be different to that of the NAXIS keyword. - -\item Helio-ecliptic coordinates are now supported by FitsChans which use -FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The -resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all -the usual facilities, such as conversion to other celestial systems, are -available. - -\item The FITS-WCS encoding now supports most of the conventions -described in FITS-WCS paper III for the description of spectral -coordinates. The exceptions are that the SSYSOBS keyword is not -supported, and WCS stored in tabular form (as indicated by the ``-TAB'' -algorithm code) is not supported. - -\item When reading a FITS-WCS header, a FitsChan will now ignore any -distortion codes which are present in CTYPE keywords. Here, a ``distortion -code'' is the final group of four characters in a CTYPE value of the -form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception -to this is that the ``-SIP'' distortion code (as used by the Spitzer -Space Telescope project - see -\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is -interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent -the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes -can only be read, not written. A FrameSet which uses a PolyMap will not -in general be able to be written out to a FitsChan using any foreign -encoding (although NATIVE encoding can of course be used). - -\item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values -``BadVal'' (which gives warnings about conversion errors when reading -FITS keyword values), ``Distortion'' (which gives warnings about -unsupported distortion codes within CTYPE values), and ``BadMat'' (which -gives a warning if the rotation/scaling matrix cannot be inverted). - -\item When writing a FrameSet to a FitsChan which uses a non-Native -encoding, the comment associated with any card already in the FitsChan -will be retained if the keyword value being written is the same as the -keyword value already in the FitsChan. - -\item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN -projection with polynomial distortion terms) can now be written to a -FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard -``-TAN'' code is used within the CTYPE values, and the distortion -coefficients are encoded in keywords of the form `` QVi\_ma'', which are -directly analogous to the standard ``PVi\_ma'' projection parameter keywords. -Thus a FITS reader which does not recognise the QV keywords will still -be able to read the header, but the distortion will be ignored. - -\item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value -of the Encoding attribute. - -\item A new appendix has been added to SUN/210 and SUN/211 giving details -of the implementation provided by the FitsChan class of the -conventions contained in the first four FITS-WCS papers. -\end{itemize} - -\item The SkyFrame class now supports two new coordinate systems ``ICRS'' -and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames -has been changed from ``FK5'' to ``ICRS''. - -\item The -\htmlref{astRate}{astRate} -function has been added which allows an estimate to be made of the rate of -change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs. - -\item All attribute names for Frames of any class may now include an optional -axis specifier. This includes those attributes which describe a property -of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be -specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases -such as this, where the attribute describes a property of the whole -Frame, axis specifiers will usually be ignored. The exception is that a -\htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the -attribute name relates to the primary Frame containing the specified -axis, rather than to the CmpFrame as a whole. - -\item A new subclass of Mapping, the PolyMap, has been added which -performs a general N-dimensional polynomial mapping. - -\item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which -models the spectral dispersion produced by a grating, prism or grism. - -\item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds -constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap} -with unit scaling on all axes). - -\item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice -and placement of numerical axis labels. - -\item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the -longitude value to be returned when a Cartesian position corresponding to -either the north or south pole is transformed into spherical coordinates. - -\item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output -celestial coordinates which have a latitude of plus or minus 90 degrees. - -\item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been -changed so that they now return the fixed native coordinates of the -projection reference point, rather than the native coordinates of the -user-defined fiducial point. - -\item Notation has been changed in both the WcsMap and FitsChan classes to -reflect the convention used in the FITS-WCS papers that index ``i'' refers -to a world coordinate axis, and index ``j'' refers to a pixel axis. - -\item Changes have been made to several Mapping classes in order to allow -the -\htmlref{astSimplify}{astSimplify} -function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not -possible. - -\item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions -between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates. - -\item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the -refractive index of air as given in the current version of FITS-WCS paper -III. Also, the forward and inverse transformations between frequency and -air-wavelength have been made more compatible by using an iterative -procedure to calculate the inverse. - -\end{enumerate} - -\subsection{Changes Introduced in V3.1} - -The following describes the most significant changes which have -occurred in the AST library between versions V3.0 and V3.1 (the -current version): - -\begin{enumerate} -\item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which -reads and writes AST objects in the form of XML. -\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect -graphical attributes to be used for various parts of the plot if either -axis has no tick marks (i.e. if both major and minor tick marks have zero -length). -\end{enumerate} - -Programs which are statically linked will need to be re-linked in -order to take advantage of these new facilities. - - -\subsection{Changes Introduced in V3.2} - -The following describes the most significant changes which have -occurred in the AST library between versions V3.1 and V3.2: - -\begin{enumerate} - -\item A new -function \htmlref{astPutCards}{astPutCards} -has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header -cards to be stored in a FitsChan in a single call, providing an alternative to -the existing -astPutCards function. - -\item Some signficant changes have been made to the simplification of Mappings - which should resultin a greater degree of simplication taking place.Some - bugs have also been fixed which could result in an infinite loop being - entered when attempting to simplify certain Mappings. - -\item The FitsChan class now translates the spectral algorithm codes -``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to -the corresponding ``-X2P'' form when reading a spectral axis description -from a set of FITS header cards. - -\item A bug has been fixed in the FitsChan class which could cause -keywords associated with alternate axis descriptions to be mis-interpreted. - -\item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance -of sub-strings within text strings such as axis labels, titles, \emph{etc}, -by producing super-scripts, sub-scripts, changing the font colour, size, -\emph{etc}. See attribute \htmlref{Escape}{Escape}. - -\item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been -changed from 0.001 to 0.01. This should not usually cause any significant -visible change to the plot, but should make the plotting faster. You may -need to set a lower value for Tol if you are producing a particularly -large plot. - -\item The algorithm for finding the default value for the Gap attribute -has been changed. This attribute specifies the gap between major axis -values in an annotated grid drawn by the Plot class. The change in -algorithm may cause the default value to be different to previous versions -in cirtain circumstances. - -\item Some bugs have been fixed in the Plot class which could cause the -system to hang for a long time while drawing certain all-sky grids -(notable some of the FITS Quad-cube projections). - -\item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition -of the ``g'' option. this option is similar to the older ``l'' option in that -it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as -delimiters between the sexagesimal fields of the celestial position. The -difference is that the ``g'' option includes graphics escape sequences -in the returned formatted string which result in the field delimiter -characters being drawn as super-scripts when plotted as numerical axis values -by a Plot. - -\item The Plot class has been extended to include facilities for producing -logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel. - -\item New functions astGCap and astGScales have been added to the interface -defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so -that the \verb+-mygrf+ switch loads dummy versions of the new grf -functions. This means that applications should continue to build without -any change. However, the facilities for interpreting escape sequences -within strings drawn by the Plot class will not be available unless the -new grf functions are implemented. If you choose to implement them, you -should modify your linking procedure to use the \verb+-grf+ switch in -place of the older \verb+-mygrf+ switch. See the description of the ast\_link -command for details of the new switches. Also note that the astGQch -function, whilst included in verb+grf.h+ in pervious versions of AST, was -not actually called. As of this version of AST, calls are made to the -astGQch function, and so any bugs in the implementation of astGQch may -cause spurious behaviour when plotting text strings. - -\item A new 'static' method called \htmlref{astEscapes}{astEscapes} has been added which is used -to control and enquire whether astGetC and \htmlref{astFormat}{astFormat} will strip any graphical -escape sequences which may be present out of the returned value. - -\item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It -allows XML written by the XmlChan class to include an explicit namespace -prefix on each element. - -\item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It -specifies the format in which AST objects should be written. - -\item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap -takes its forward transformation from an existing Mapping, and its inverse -transformation from another existing Mapping. - -\item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to -include erroneous axis numbers when referring to missing parameter values. - -\end{enumerate} - -\subsection{Changes Introduced in V3.3} - -The following describes the most significant changes which have -occurred in the AST library between versions V3.2 and V3.3: - -\begin{enumerate} - -\item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the -origin -of celestial coordinates to be moved to any specified point. See the new -attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}. - -\item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra -Frames representing cartesian projection plane coordinates (``intermediate -world coordinates'' in the parlance of FITS-WCS) to be created when -reading -WCS information from a foreign FITS header. This option is controlled by -a new attribute called \htmlref{Iwc}{Iwc}. - -\item The FitsChan class which been modified to interpret FITS-WCS CAR -projection headers correctly if the longitude reference pixel (CRPIX) is -very large. - -\item The FITS-AIPS++ encoding in the FitsChan class now recognised -spectral axes if they conform to the AIPS convention in which the -spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB" -where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD, -HEL or OBS. Such spectral axes can be both read and written. - -\item The FitsChan class now has a FITS-AIPS++ encoding which represents -WCS information using FITS header cards recognised by the AIPS++ project. -Support for spectral axes is identical to the FITS-AIPS encoding. - -\item The organisation of the AST distribution and the commands for -building it have been changed. Whereas AST used to be built and installed -with \verb+./mk build; ./mk install+, it now builds using the more standard -idiom \verb+./configure; make; make install+. The installation location is -controlled by the \verb+--prefix+ argument to ./configure (as is usual -for other packages which use this scheme). Note that the INSTALL environment -variable now has a \emph{different} meaning to that which it had -before, and it should generally be \emph{unset}. Also, there is no need to -set the SYSTEM variable. - -\item Shared libraries are now installed in the same directory as the -static libraries. In addition, links to sharable libraries are installed -with names which include version information, and ``libtool libraries'' -are also installed (see -\url{http://www.gnu.org/software/libtool/manual.html}). - -\item The \verb+ast_dev+ script has been removed. Instead, the location of -the AST include files should be specified using the -I option when -compiling. - - -\end{enumerate} - - -\subsection{Changes Introduced in V3.4} - -The following describes the most significant changes which have -occurred in the AST library between versions V3.3 and V3.4: - -\begin{enumerate} - -\item The \htmlref{Mapping}{Mapping} class has a new method -(\htmlref{astLinearApprox}{astLinearApprox}) -which calculates the co-efficients of a linear approximation to a Mapping. - -\item The Format attribute for simple Frames and SkyFrames has been extended. -It has always been possible, in both classes, to specify a precision by -including a dot in the Format value followed by an integer (\emph{e.g.} -``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}). -The precision can now also be specified using an asterisk in place of the -integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the -precision to be derived on the basis of the Digits attribute value. - -\item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the -Digits attribute is chosen to be the smallest value which results in no -pair of adjacent labels being identical. For instance, if an annotated -grid is being drawn describing a SkyFrame, and the Format(1) value is set -to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as -superscripts), and the Digits(1) value is unset, then the seconds field -will have a number of decimal places which results in no pair of labels -being identical. - -\item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a -sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes -associated with dual sideband spectral data. - -\item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS'' -projection code, converting them to the corresponding modern ``-SFL'' code, -provided that the celestial axes are not rotated. - -\item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows -the reading and writing of FITS headers using the conventions of the CLASS -package - see -\url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}). - -\end{enumerate} - - -\subsection{Changes Introduced in V3.5} - -The following describes the most significant changes which have -occurred in the AST library between versions V3.4 and V3.5: - -\begin{enumerate} - -\item AST now provides facilities for representing regions of various -shapes within a coordinate system. The \htmlref{Region}{Region} class provides general -facilities which are independent of the specific shape of region being -used. Various sub-classes of Region are also now available which provide -means of creating Regions of specific shape. Facilities provided by the -Region class include testing points to see if they are inside the -Region, testing two Regions for overlap, transforming Regions from one -coordinate system to another \emph{etc}. - -\item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which -can be used to describe various systems for describing ovserved value at a -single fixed spectral position. - -\item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which -can be used to describe a 2-d frame spanned by a spectral position axis -and and an observed value axis. - -\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates -a previously created Mapping. The inputs of the RateMap correspond to the -inputs of the encapsulated Mapping. All RateMaps have just a single -output which correspond to the rate of change of a specified output of -the encapsulated Mapping with respect to a specified input. - -\item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}. -This system is an equatorial system based on the mean dynamical equator and -equinox at J2000, and differs slightly from an FK5(J2000) system. - -\item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to -store a collection of vector or scalar values or Objects, indexed by a -character string rather than an integer. - -\item The parameter list for the -\htmlref{astRate}{astRate} -method of the Mapping class has been modified. It no longer returns a second -derivative estimate. Existing code which uses this method will need to be -changed. - -\item Methods -(astSetFits<X>) -have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named -keywords to be changed or added. - -\end{enumerate} - - -\subsection{Changes Introduced in V3.6} - -The following describes the most significant changes which -occurred in the AST library between versions V3.5 and V3.6: - -\begin{enumerate} - -\item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame} -starts with a percent character (``\verb+%+''), then axis values are -now formatted and unformatted as a decimal radians value, using the -Format syntax of a simple \htmlref{Frame}{Frame}. - -\item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the -clipping performed by AST at the plot boundary. - -\item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a -PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys -are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}. -The new PolyMap class always writes new styles keys but can read either -old or new style keys. Consequently, PolyMap dumps written by this -version of AST cannot be read by older versions of AST. - -\item A mimimal cut down subset of the C version of SLALIB is now -included with the AST distribution and built as part of building AST. -This means that it is no longer necessary to have SLALIB installed -separately at your site. The SLALIB code included with AST is distrubuted -under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to -link with this internal slalib subset. However, the ``-csla'' option can -still be used to force linking with an external full C SLALIB library. -A new option ``-fsla'' has been introduced which forces linking with the -external full Fortran SLALIB library. - -\end{enumerate} - -\subsection{Changes Introduced in V3.7} - -The following describes the most significant changes which -occurred in the AST library between versions V3.6 and V3.7: - -\begin{enumerate} - -\item Support for time coordinate systems has been introduced -throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}. -The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe -moments in time (either absolute or relative) in various systems (MJD, -Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC, -UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time -values between these various systems and time scales. Note, -FitsChans which have a foreign encoding (\emph{i.e.} any encoding other -than NATIVE) are not able to read or write these new classes. - -\end{enumerate} - - -\subsection{Changes Introduced in V4.0} - -The following describes the most significant changes which -occurred in the AST library between versions V3.7 and V4.0: - -\begin{enumerate} - -\item Experimental support for reading IVOA Space-Time-Coordinates (STC-X) -descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included -for a subset of V1.20 of the draft STC specification. - -\item A new set of methods (AST\_REBIN<X>/astRebin<X>) has been added to -the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing -AST\_RESAMPLE<X>/astResample<X> methods. - -\end{enumerate} - - -\subsection{Changes Introduced in V4.1} - -The following describes the most significant changes which -occurred in the AST library between versions V4.0 and V4.1: - -\begin{enumerate} - -\item A new control flag has been added to the AST\_RESAMPLE<X>/astResample<X> -functions which produces approximate flux conservation. - -\item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to -ast.h. These specify kernels for astResample and astRebin -based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the -first order Bessel function of the first kind). - -\item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding -to horizon (azimuth/elevation) coordinates. - -\item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and -``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values. - -\item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify -the geodetic longitude and latitude of the observer. - -\item The ClockLon and ClockLat attributes have been removed from the -\htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been -removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and -ObsLat attributes of the parent Frame class instead. However, the old -attribute names can be used as synonyms for ObsLat and ObsLon. Also, -dumps created using the old scheme can be read succesfully by AST V4.1 -and converted to the new form. - -\item A new -function \htmlref{astMapSplit}{astMapSplit} -has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component -Mappings which, when combined in parallel, are equivalent to the original -Mapping. - -\item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from -``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame -to represent offsets from some origin position, you must now set the -SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in -addition to assigning the required origin position to the SkyRef attribute. - -\end{enumerate} - -\subsection{Changes Introduced in V4.2} - -The following describes the most significant changes which -occurred in the AST library between versions V4.1 and V4.2: - -\begin{enumerate} - -\item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the -option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the -DSBSpecFrame to represent the offset from the local oscillator frequency, -rather than either of the two sidebands. - -\item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS -keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric -apparent velocity of the standard of rest). FitsChan also strips out VELOSYS -keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding. - -\item The FitsChan class has a new method called -\htmlref{astRetainFits}{astRetainFits} -that indicates that the current card in the FitsChan should not be -stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan. -Unless this method is used, all cards that were involved in the creation -of the AST Object will be stripped from the FitsChan afte a read operation. - -\item A problem with unaligned memory access that could cause bus errors on -Solaris has been fixed. - -\item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base -Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the -Object. Note, this is the size of the internal in-memory representation of -the Object, not the size of the textual representation produced by -writing the Object out through a \htmlref{Channel}{Channel}. - -\item A new function -\htmlref{astTune}{astTune} -has been added which can be used to get and set global AST tuning -parameters. At the moment there are only two such parameter, both of -which are concerned with memory management within AST. - -\item A new method called -\htmlref{astTranGrid}{astTranGrid} -has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular -grid of points covering a rectangular region within the input space of a -Mapping, and then transforms this set of points into the output space of the -Mapping, using a piecewise-continuous linear approximation to the Mapping -if appropriate in order to achive higher speed. - -\item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A -SwitchMap represents several alternate Mappings, each of which is used to -transforms input positions within a different region of the input -coordinate space. - -\item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A -SelectorMap tests each input position to see if it falls within one of -several Regions. If it does, the index of the \htmlref{Region}{Region} containing the -input position is returned as the Mapping output. - -\item The behaviour of the -\htmlref{astConvert}{astConvert} -method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been -modified. If no conversion between positions in the Frame and CmpFrame -can be found, an attempt is now made to find a conversion between the -Frame and one of two component Frames contained within the CmpFrame. Thus -is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a -SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad -values for the extra axes (i.e. for the SpecFrame axis in the above example). - -\item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the -\verb+-fsla+ and \verb+-csla+ options, and always link against the -minimal cut-down version of SLALIB distributed as part of AST. - -\end{enumerate} - -\subsection{Changes Introduced in V4.3} - -The following describes the most significant changes which occurred in the -AST library between versions V4.2 and V4.3: - -\begin{enumerate} - -\item The -astGetFitsS -function now strips trailing white space from the returned string, if the -original string contains 8 or fewer characters - -\item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified -whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the -source) should be accessed as an apparent radial velocity or a redshift. -Note, any existing software that assumes that SourceVel always represents -a velocity in km/s should be changed to allow for the possibility of -SourceVel representing a redshift value. - -\end{enumerate} - - -\subsection{Changes Introduced in V4.4} - -The following describes the most significant changes which occurred in -the AST library between versions V4.3 and V4.4: - -\begin{enumerate} - -\item The -\htmlref{astFindFrame}{astFindFrame} -function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more -specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame} -or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as -the ``template'' when calling -astFindFrame, -and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the -current Frame is a CmpFrame), then the component Frames within the CmpFrame -will be searched for an instance of the supplied template Frame, and, if -found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the -required axes from the CmpFrame) will be returned by -astFindFrame. -Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template -Frame must be set so that they cover a range that includes the number of axes -in the target CmpFrame. - -\item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes -now allow the MaxAxes and MinAxes attributes to be set freely to any value. -In previous versions of AST, any attempt to change the value of MinAxes -or MaxAxes was ignored, resulting in them always taking the default values. - -\item The DSBSpecFrame class has a new attribute called AlignSB that -specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when -aligning two DSBSpecFrames using -\htmlref{astConvert}{astConvert}. - -\item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to -store a value for the difference between the UT1 and UTC timescales at -the epoch referred to by the Frame. - -\item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and -\htmlref{ObsLon}{ObsLon} has been increased. - -\item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This -attribute is used to control how two SkyFrames are aligned by -astConvert. -If the template and target SkyFrames both have a non-zero value for -AlignOffset, then alignment occurs between the offset coordinate systems -(that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). - -\item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be -used to force exterior (rather than interior) tick marks to be produced. -By default, exterior ticks are only produced if this would result in -more than 3 tick marks being drawn. - -\item The TimeFrame class now supports conversion between angle based -timescales such as UT1 and atomic based timescales such as UTC. - -\end{enumerate} - -\subsection{Changes Introduced in V4.5} - -The following describes the most significant changes that -occurred in the AST library between versions V4.4 and V4.5: - -\begin{enumerate} - - - -\item All FITS-CLASS headers are now created with a frequency axis. If the -\htmlref{FrameSet}{FrameSet} supplied to -\htmlref{astWrite}{astWrite} -contains a velocity axis (or any other form -of spectral axis) it will be converted to an equivalent frequency axis -before being used to create the FITS-CLASS header. - -\item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed -from the velocity of the source to the velocity of the reference channel. - -\item Addition of a new method call -\htmlref{astPurgeWCS}{astPurgeWCS} -to the \htmlref{FitsChan}{FitsChan} -class. This method removes all WCS-related header cards from a FitsChan. - -\item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used -to comminicate context information between an application and any -graphics functions registered with the Plot class via the -\htmlref{astGrfSet}{astGrfSet} function. -\item Functions registered with the Plot class using -astGrfSet -now take a new additional integer parameter, ``grfcon''. The Plot class -sets this parameter to the value of the Plot's GrfContext attribute before -calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING -CODE THAT USES -astGrfSet -TO BE MODIFIED TO INCLUDE THE NEW PARAMETER. -\item The -astRebinSeq functions -now have an extra parameter that is used to record the total number of input -data values added into the output array. This is necessary to correct a -flaw in the calculation of output variances based on the spread of input -values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO -INCLUDE THE NEW PARAMETER (CALLED "NUSED"). -\item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection. -\item A new flag ``AST\_\_VARWGT'' can be supplied to -astRebinSeq. -This causes the input data values to be weighted using the reciprocals of -the input variances (if supplied). - -\item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that -returns the normalised value of the Unit attribute for an axis. Here, -``normalisation'' means cancelling redundant units, etc. So for instance, a -Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''. - -\item A new -function \htmlref{astShowMesh}{astShowMesh} -has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering -the surface of a Region by writing out a table of axis values to standard -output. - -\item The Plot class now honours the value of the LabelUp attribute even if -numerical labels are placed around the edge of the Plot. Previously -LabelUp was only used if the labels were drawn within the interior of -the plot. The LabelUp attribute controls whether numerical labels are -drawn horizontally or parallel to the axis they describe. - -\item A bug has been fixed that could segmentation violations when setting -attribute values. - -\end{enumerate} - -\subsection{Changes Introduced in V4.6} - -The following describes the most significant changes which have -occurred in the AST library between versions V4.5 and V4.6: - -\begin{enumerate} - -\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset -from UTC to Local Time is specified by a new TimeFrame attribute called -\htmlref{LTOffset}{LTOffset}. - -\item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows -the creation of 3-dimensional annotated coordinate grids. - -\item A correction for diurnal aberration is now included when -converting between AZEL and other celestial coordinate systems. The -correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the -geodetic latitude of the observer). - -\item A bug has been fixed which caused the DUT1 attribute to be ignored -by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other -celestial coordinate systems. - -\end{enumerate} - -\subsection{Changes Introduced in V5.0} - -The following describes the most significant changes which -occurred in the AST library between versions V4.6 and V5.0: - -\begin{enumerate} - - -\item The AST library is now thread-safe (assuming that the POSIX pthreads -library is available when AST is built). Many of the macros defined in -the ast.h header file have changed. It is therefore necessary to -re-compile all source code that includes ast.h. - -\item New methods \htmlref{astLock}{astLock} and \htmlref{astUnlock}{astUnlock} allow an AST \htmlref{Object}{Object} to be locked -for exclusive use by a thread. - -\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset -from UTC to Local Time is specified by a new TimeFrame attribute called -\htmlref{LTOffset}{LTOffset}. - -\item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls -whether or not to report an error if unexpected data items are found -within an AST Object description read from an external data source. Note, -the default behaviour is now not to report such errors. This differs from -previous versions of AST which always reported an error is unexpected -input items were encountered. - -\end{enumerate} - -\subsection{Changes Introduced in V5.1} - -The following describes the most significant changes which occurred in the -AST library between versions V5.0 and V5.1: - -\begin{enumerate} - -\item The \htmlref{astUnlock}{astUnlock} function now has an extra parameter that controls whether -or not an error is reported if the \htmlref{Object}{Object} is currently locked by another -thread. - -\item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can -be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval} -could be used for this purpose. - -\item The values of the AST\_\_THREADSAFE macro (defined in ast.h) have -been changed from ``yes'' and ``no'' to ``1'' and ``0''. - -\item Improvements have been made to the way that Prisms are simplified -when -\htmlref{astSimplify}{astSimplify} -is called. The changes mean that more types of Prism will now simplify -into a simpler class of Region. - -\item The \htmlref{PointList}{PointList} class has a new method, -astPoints, -that copies the axis values from the PointList into a supplied array. - -\item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that -gives the number of points stored in the PointList. - -\item The handling of warnings within different classes of \htmlref{Channel}{Channel} has -been rationalised. The XmlStrict attribute and -astXmlWarnings -function have been removed. The same functionality is now available via -the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new -attribute called \htmlref{ReportLevel}{ReportLevel}, and the new -\htmlref{astWarnings}{astWarnings} -function. This new function can be used on any class of Channel. Teh -\htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as -header cards within the FitsChan, but it also now stores warnings in the -parent Channel structure, from where they can be retrieved using the -astWarnings -function. - -\item A new function called -astIntercept -has been added to the \htmlref{Frame}{Frame} class. This function finds the point of -intersection beteeen two geodesic curves. - -\item A bug in the type-checking of Objects passed as arguments to constructor -functions has been fixed. This bug could lead to applications crashing or -showing strange behaviour if an inappropriate class of Object was -supplied as an argument to a constructor. - -\item The -\htmlref{astPickAxes}{astPickAxes} -function will now return a Region, if possible, when applied to a Region. If -this is not possible, a Frame will be returned as before. - -\item The choice of default tick-mark for time axes has been improved, to avoid -previous issues which could result in no suitable gap being found, or -inappropriate tick marks when using formatted dates. - -\item A new function called -\htmlref{astTestFits}{astTestFits} -has been added to the FitsChan class. This function tests a FitsChan to -see if it contains a defined value for specified FITS keyword. - -\item The AST\_\_UNDEF<X> parameters used to flag undefined FITS keyword values -have been removed. Use the new -astTestFits -function instead. - -\item The astIsUndef<X> functions used to test FITS keyword values -have been removed. Use the new astTestFits function instead. - -\end{enumerate} - -\subsection{Changes Introduced in V5.2} - -The following describes the most significant changes which -occurred in the AST library between versions V5.1 and V5.2: - -\begin{enumerate} - -\item A new method called -\htmlref{astSetFitsCM}{astSetFitsCM} -has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a -FitsChan (that is, a card with no keyword name or equals sign). - -\item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It -records the geodetic altitude of the observer, in metres. It defaults to -zero. It is used when converting times to or from the TDB timescale, or -converting spectral positions to or from the topocentric rest frame, or -converting sky positions to or from horizon coordinates. The FitsChan -class will include its effect when creating a set of values for the -OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a -set of OBSGEO-X/Y/Z keyword values from a FITS header. - -\item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap} -conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument - -the observer's geodetic altitude. - -\item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the -IVOA STC definition of a Polygon. Specifically, the inside of a polygon -is now the area to the left of each edge as the vertices are traversed in -an anti-clockwise manner, as seen from the inside of the celestial sphere. -Previously, AST used the anti-clockwise convention, but viewed from the -outside of the celestial sphere instead of the inside. Any Polygon saved -using previous versions of AST will be identified and negated automatically -when read by AST V5.2. - -\item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows -conversion of suitable AST Objects to and from IVOA STC-S format. - -\item A new method called -\htmlref{astRemoveRegions}{astRemoveRegions} -has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound) -Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either -removes them, or replaces them with UnitMaps (or equivalent Frames). It -can be used to remove the masking effects of Regions from a compound -Mapping or Frame. - -\item A new method called -\htmlref{astDownsize}{astDownsize} -has been added to the Polygon class. It produces a new Polygon that -contains a subset of the vertices in the supplied Polygon. The subset is -chosen to retain the main features of the supplied Polygion, in so far -as that is possible, within specified constraints. - -\item A new constructor called -astOutline -has been added to the Polygon class. Given a 2D data array, it identifies -the boundary of a region within the array that holds pixels with -specified values. It then creates a new Polygon to describe this boundary -to a specified accuracy. - -\item A new set of methods, called -astMapGetElem<X> -has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector -valued entry to be returned. - -\item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It -controls whether the -astMapGet... -family of functions report an error if an entry with the requested key does -not exist in the KeyMap. - -\end{enumerate} - -\subsection{Changes Introduced in V5.3} - -The following describes the most significant changes which -occurred in the AST library between versions V5.2 and V5.3: - -\begin{enumerate} - -\item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the -\htmlref{astFindFrame}{astFindFrame} and \htmlref{astConvert}{astConvert} -functions have been changed. The changes mean that a Frame can now be -aligned with an instance of a sub-class of Frame, so long as the number -of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic -2-dimensional Frame with Domain ``SKY'' will now align succesfully with -a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a -\htmlref{UnitMap}{UnitMap}. - -\item The arrays that supply input values for astMapPut1<X> are now -declared ``const''. - -\item Added method -\htmlref{astMatchAxes}{astMatchAxes} -to the Frame class. This method allows corresponding axes within two -Frames to be identified. - -\item The -\htmlref{astAddFrame}{astAddFrame} -method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}. -\end{enumerate} - -\subsection{Changes Introduced in V5.3-1} - -The following describes the most significant changes which have -occurred in the AST library between versions V5.3 and V5.3-1: - -\begin{enumerate} - -\item The utility functions provided by the AST memory management layer -are now documented in an appendix. - -\item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A -new method called -\htmlref{astMapPutU}{astMapPutU} -will store an entry with undefined value in a keymap. Methods that -retrieve values from a KeyMap -(astMapGet0<X>, etc.) -ignore entries with undefined values when searching for an entry with a given -key. - -\item The KeyMap class has a new method called -\htmlref{astMapCopy}{astMapCopy} -that copies entries from one KeyMap to another KeyMap. - -\item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If -non-zero, -an error is reported if an attempt is made to add any new entries -to a KeyMap (the value associated with any old entry may still be changed -without error). The default is -zero. - -\item The \htmlref{Object}{Object} class has a new method called \htmlref{astHasAttribute}{astHasAttribute}/AST\_HASATTRIBUTE -that returns a boolean value indicating if a specified Object has a named -attribute. - -\item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called -IsLatAxis and IsLonAxis that can be used to determine the nature of a -specified SkyFrame axis. - -\item A bug has been fixed in the -astRebin(Seq) -methods that could cause flux to be lost from the edges of the supplied array. - -\item A bug has been fixed in the -astRebin(Seq) -methods that caused the first user supplied parameter to be interpreted as the -full width of the spreading kernel, rather than the half-width. - -\item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except -that units strings are still case sensitive). - -\item A new \htmlref{Mapping}{Mapping} method, -\htmlref{astQuadApprox}{astQuadApprox}, -produces a quadratic least-squares fit to a 2D Mapping. - -\item A new Mapping method, -\htmlref{astSkyOffsetMap}{astSkyOffsetMap}, -produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame -coordinates. - -\item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation -in the text created by -\htmlref{astWrite}{astWrite}. -The StcsIndent and XmlIndent attributes have been removed. - -\item All classes of Channel now use the string ``<bad>'' to represent the -floating point value AST\_\_BAD, rather than the literal formatted value -(typically ``-1.79769313486232e+308'' ). - -\item The KeyMap class now uses the string ``<bad>'' to represent the -floating point value AST\_\_BAD, rather than the literal formatted value -(typically ``-1.79769313486232e+308'' ). - -\item The KeyMap class has a new method called -astMapPutElem<X> -that allows a value to be put into a single element of a vector entry in -a KeyMap. The vector entry is extended automatically to hold the new -element if required. - -\item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator -frequency is less than the absoliute value of the intermediate frequency. - -\end{enumerate} - - -\subsection{Changes Introduced in V5.3-2} - -The following describes the most significant changes which -occurred in the AST library between versions V5.3-1 and V5.3-2: - -\begin{enumerate} - -\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength -axes to be assigned the units ``m/s'' when reading WCS information from a -FITS header. - -\item The -\htmlref{astSet}{astSet} function -now allows literal commas to be included in string attribute values. String -attribute values that include a literal comma should be enclosed in quotation -marks. - -\item A bug in FitsChan has been fixed that caused ``-SIN'' projection -codes within FITS-WCS headers to be mis-interpreted, resulting in no -\htmlref{FrameSet}{FrameSet} being read by \htmlref{astRead}{astRead}. - -\item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls -the order in which keys are returned by the -\htmlref{astMapKey}{astMapKey} -function. Keys can be sorted alphabetically or by age, or left unsorted. - -\item Access to KeyMaps holding thousands of entries is now significantly -faster. - -\item KeyMaps can now hold word (i.e. -short integer) -values. - -\end{enumerate} - - -\subsection{Changes Introduced in V5.4-0} - -The following describes the most significant changes which -occurred in the AST library between versions V5.3-2 and V5.4-0: - -\begin{enumerate} - -\item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing -of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper -III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}. -See the documentation for TabOK for more information. - -\item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in -which each entry represents a cell in a two-dimensional table. - -\item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a -Table that has an associated FitsChan holding headers appropriate to a -FITS binary table. - -\item KeyMaps can now hold byte values. These are held in variables -of type -"unsigned char". - -\item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to -make the handling of keys case insensitive. - -\item a memory leak associated with the use of the -astMapPutElem<X> -functions has been fixed. - -\item A new method called -\htmlref{astMapRename}{astMapRename} -has been added to rename existing entry in a KeyMap. -\end{enumerate} - -\subsection{Changes Introduced in V5.5-0} - -The following describes the most significant changes which -occurred in the AST library between versions V5.4-0 and V5.5-0: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather -than a boolean value. If TabOK is set to a non-zero positive integer -before invoking the -\htmlref{astWrite}{astWrite} -method, its value is used as the version number for any table that is -created as a consequence of the write operation. This is the value stored -in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the -binary table header. In previous versions of AST, the value used for these -headers could not be controlled and was fixed at 1. If TabOK is set to a -negative or zero value, the -TAB algorithm will not be supported by -either the -astWrite or \htmlref{astRead}{astRead} -methods. - -\end{enumerate} - - - -\subsection{Changes Introduced in V5.6-0} - -The following describes the most significant changes which -occurred in the AST library between versions V5.5-0 and V5.6-0: - -\begin{enumerate} - -\item -New functions \htmlref{astBBuf}{astBBuf} and \htmlref{astEBuf}{astEBuf} -have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical -output produced by other Plot methods. - -\item New functions astGBBuf and astGEBuf have been added to the interface -defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so -that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf -functions. This means that applications that use the \verb+-grf_v3.2+ -switch should continue to build without any change. However, the new public -functions astBBuf and astEBuf -will report an error unless the new grf functions are implemented. If you -choose to implement them, you should modify your linking procedure to -use the \verb+-grf+ (or \verb+-grf_v5.6+ ) switch in place of the older -\verb+-grf_v3.2+ switch. See the description of the ast\_link command for -details of these switches. - -\item New method -\htmlref{astGetRegionMesh}{astGetRegionMesh} -returns a set of positions covering the boundary, or volume, of a supplied -\htmlref{Region}{Region}. - -\end{enumerate} - - -\subsection{ChangesIntroduced in V5.6-1} - -The following describes the most significant changes which -occurred in the AST library between versions V5.6-0 and V5.6-1: - -\begin{enumerate} - -\item Tables can now have any number of parameters describing the global -properties of the \htmlref{Table}{Table}. - -\item Frames now interpret the unit string ``A'' as meaning ``Ampere'' -rather than ``Angstrom'', as specified by FITS-WCS paper I. - -\item A bug has been fixed in the -\htmlref{astFindFrame}{astFindFrame} -method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match -a target frame of a less specialised class. For example, this bug would -allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer -happens. - -\end{enumerate} - -\subsection{Changes Introduced in V5.7-0} - -The following describes the most significant changes which -occurred in the AST library between versions V5.6-1 and V5.7-0: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has -been extended to include reading TNX headers that use a Chebyshev -representation for the distortion polynomial. - -\item The FitsChan class support for the IRAF-specific ``ZPX'' projection has -been extended to include reading ZPX headers that use simple or Chebyshev -representation for the distortion polynomial. - -\item A bug has been fixed in the FitsChan class that caused headers -including the Spitzer ``-SIP'' distortion code to be read incorrectly if no -inverse polynomial was specified in the header. - -\item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It -can be used to indicate that FITS headers that specify a TAN projection -should be interpreted according to the ``distorted TAN'' convention -included in an early draft of FITS-WCS paper II. Such headers are created -by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}). - -\item The \htmlref{PolyMap}{PolyMap} class now provides a method called -\htmlref{astPolyTran}{astPolyTran} -that adds an inverse transformation to a PolyMap by sampling the forward -transformation on a regular grid, and then fitting a polynomial function -from the resulting output values to the grid of input values. - -\end{enumerate} - -\subsection{Changes Introduced in V5.7-1} - -The following describes the most significant changes which -occurred in the AST library between versions V5.7-0 and V5.7-1: - -\begin{enumerate} - -\item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified -text files, without the need to provide source and sink functions when -the Channel is created. The files to use are specified by the new -attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}. - -\item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS -keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header. - -\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the --SIP (Spitzer) distortion code within the CTYPE values, but which does -not provide an inverse polynomial correction, the FitsChan class will now -use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the -inverse polynomial correction. - -\end{enumerate} - - -\subsection{Changes Introduced in V5.7-2} - -The following describes the most significant changes which -occurred in the AST library between versions V5.7-1 and V5.7-2: - -\begin{enumerate} - -\item The \htmlref{Object}{Object} class has a new function \htmlref{astToString}{astToString} (C only), which creates -an in-memory textual serialisation of a given AST Object. A corresponding -new function called \htmlref{astFromString}{astFromString} re-creates the Object from its -serialisation. - -\item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to -evaluate the inverse the inverse transformation if no inverse -transformation is defined when the PolyMap is created. - -\item The \htmlref{FitsChan}{FitsChan} class has a new method -\htmlref{astWriteFits}{astWriteFits} -which writes out all cards currently in the FitsChan to the associated -external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the -sink function supplied when the FitsChan was created), and then empties -the FitsChan. - -\item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which -holds the number of keywords for which values are held in a FitsChan. - -\item The FitsChan -astGetFits<X> -methods can now be used to returned the value of the current card. - -\item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which -holds the data type of the keyword value for the current card. - -\item The FitsChan class has a new method -\htmlref{astReadFits}{astReadFits} -which forces the FitsChan to reads cards from the associated external -source and appends them to the end of the FitsChan. - -\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the --SIP (Spitzer) distortion code within the CTYPE values, but which does -not provide an inverse polynomial correction, and for which the PolyTran -method of the PolyMap class fails to create an accurate estimate of the -inverse polynomial correction, then an iterative method will be used to -evaluate the inverse correction for each point transformed. - -\end{enumerate} - -\subsection{Changes Introduced in V6.0} - -The following describes the most significant changes which -occurred in the AST library between versions V5.7-2 and V6.0: - -\begin{enumerate} - -\item This version of AST is the first that can be used with the Python -AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}. - -\item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the -non-standard ``TPV'' projection code within a CTYPE keyword value. This -code is used by SCAMP (see www.astromatic.net/software/scamp) to -represent a distorted TAN projection. - -\item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as -incorrectly rotated numerical axis labels) if the graphics coordinates have -unequal scales on the X and Y axes. - -- The graphics escape sequences used to produce graphical sky axis labels -can now be changed using the new -function \htmlref{astTuneC}{astTuneC}. - -\end{enumerate} - -\subsection{Changes Introduced in V6.0-1} - -The following describes the most significant changes which -occurred in the AST library between versions V6.0 and V6.0-1: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion -code within FITS headers that describe non-celestial axes, as well as -celestial axes. - -\item A bug has been fixed that could cause inappropriate equinox values to -be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set. - -\item The versioning string for AST has changed from -``$<major>.<minor>-<release>$'' to ``$<major>.<minor>.<release>$''. - -\end{enumerate} - -\subsection{Changes Introduced in V7.0.0} - -The following describes the most significant changes which -occurred in the AST library between versions V6.0-1 and V7.0.0: - -\begin{enumerate} - -\item Fundamental positional astronomy calculations are now performed -using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{} -otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB -library re-written in C). Copies of these libraries are bundled with AST -and so do not need to be obtained or built separately, although external -copies of SOFA and PAL can be used if necessary by including the -``\texttt{--with-external\_pal}'' option when configuring AST. - -\end{enumerate} - -\subsection{Changes Introduced in V7.0.1} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.0 and V7.0.1: - -\begin{enumerate} - -\item The levmar and wcslib code distributed within AST is now stored in the -main AST library (libast.so) rather than in separate libraries. - -\end{enumerate} - -\subsection{Changes Introduced in V7.0.2} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.1 and V7.0.2: - -\begin{enumerate} - -\item The libast\_pal library is no longer built if the -``--with-external\_pal'' option is used when AST is configured. - -\end{enumerate} - -\subsection{Changes Introduced in V7.0.3} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.2 and V7.0.3: - -\begin{enumerate} - -\item A bug has been fixed which could cause an incorrect axis to be used when -accessing axis attributes within CmpFrames. This could happen if axes -within the \htmlref{CmpFrame}{CmpFrame} have been permuted. - -\item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two -values of the SkyRef and/or SkyRefP attributes to be reversed. - -\item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border -around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately. -Previously, component Regions nested deeply inside a CmpRegion may have -been completely or partially ignored. - -\item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation -violation if the MinTick attribute was set to zero. - -\item The astResampleX set of methods now includes astResampleK and -astResampleUK that handles 64 bit integer data. - -\end{enumerate} - - -\subsection{Changes Introduced in V7.0.4} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.3 and V7.0.4: - - -\begin{enumerate} - -\item The previously private grf3d.h header file is now installed into -prefix/include. - -\end{enumerate} - - -\subsection{Changes Introduced in V7.0.5} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.4 and V7.0.5: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO -convention for representing distorted TAN projections, based on the use -of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial. - -\end{enumerate} - - -\subsection{Changes Introduced in V7.0.6} - -The following describes the most significant changes which -occurred in the AST library between versions V7.0.5 and V7.0.6: - -\begin{enumerate} - -\item A bug has been fixed in astRebinSeq<X> which could result in -incorrect normalisation of the final binned data and variance values. - -\item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1 -and CNPIX2 now default to zero if absent. Previously an error was reported. - -\end{enumerate} - - -\subsection{Changes Introduced in V7.1.0} - -The following describes the most significant changes which occurred in the -AST library between versions V7.0.6 and V7.1.0: - -\begin{enumerate} - -\item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve -flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied -when calling -astRebinSeq<X>. -Without this flag, each output value is a weighted mean of the neighbouring -input values. - -\item A new flag AST\_\_NONORM can be used with astRebinSeq<X> to indicate that -normalisation of the output arrays is not required. In this case no -weights array need be supplied. - -\item A bug has been fixed in -\htmlref{astAddFrame}{astAddFrame} method -that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet} -when the AST\_\_ALLFRAMES flag is supplied for the -"iframe" parameter. - -\item The -\htmlref{astRate}{astRate} method -has been re-written to make it faster and more reliable. - -\end{enumerate} - -\subsection{Changes Introduced in V7.1.1} - -The following describes the most significant changes which -occurred in the AST library between versions V7.1.0 and V7.1.1: - -\begin{enumerate} - -\item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute -\htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions -are now created - one for the offset coordinates and one for the absolute -coordinates. If such a header is subsequently read back into AST, the -original offset SkyFrame is recreated. - -\item A bug has been fixed in FitsChan that caused inappropriate CTYPE values -to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the -current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a -SkyFrame with \htmlref{System}{System}=Unknown). - -\end{enumerate} - -\subsection{Changes Introduced in V7.2.0} - -The following describes the most significant changes which -occurred in the AST library between versions V7.1.1 and V7.2.0: - -\begin{enumerate} - -\item A new method call -\htmlref{astMapDefined}{astMapDefined} -has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has -a defined value in a given KeyMap. - -\end{enumerate} - -\subsection{Changes Introduced in V7.3.0} - -The following describes the most significant changes which -occurred in the AST library between versions V7.2.0 and V7.3.0: - -\begin{enumerate} - -\item The interface for the astRebinSeq<X> family of functions has -been changed in order to allow a greater number of pixels to be pasted -into the output array. The "nused" parameter is now a pointer to a -"int64\_t" variable, instead of an "int". APPLICATION CODE SHOULD BE -CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC -BEHAVIOUR. - -\item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be -associated with multiple Mappings, any one of which can be used to -connect the Frame to the other Frames in the FrameSet. The choice of -which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the -FrameSet class. - -\item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident} -attribute are now left unchanged by the -c \htmlref{astSimplify}{astSimplify} function. -f AST\_SIMPLIFY routine. - -\end{enumerate} - -\subsection{Changes Introduced in V7.3.1} - -The following describes the most significant changes which -occurred in the AST library between versions V7.3.0 and V7.3.1: - -\begin{enumerate} - -\item Fix a bug that could cauise a segmentation violation when reading -certain FITS headers that use a TNX projection. - -\end{enumerate} - -\subsection{Changes Introduced in V7.3.2} - -The following describes the most significant changes which -occurred in the AST library between versions V7.3.1 and V7.3.2: - -\begin{enumerate} - -\item Fix support for reading FITS header that use a GLS projection. -Previously, an incorrect transformation was used for such projections if -any CRVAL or CROTA value was non-zero. - -\item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and -``KeyAgeDown'' that retain the position of an existing entry if its value -is changed. See the \htmlref{SortBy}{SortBy} attribute. - -\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords -for sky axes to be treated as radians rather than degrees when reading a -FITS header, if the corresponding CTYPE values included no projection code. - -\end{enumerate} - -\subsection{Changes Introduced in V7.3.3} - -The following describes the most significant changes which -occurred in the AST library between versions V7.3.2 and V7.3.3: - -\begin{enumerate} - -\item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold -the keyword name and comment of the current card. - -\item When using the FitsChan class to read FITS-WCS headers that include -polynomial distortion in the SIP format, any inverse transformation specified -in the header is now ignored and a new inverse is created to replace it based -on the supplied forward transformation. Previously, an inverse was created -only if the header did not include an inverse. The accuracy of the inverse -transformation has also been improved, although it may now be slower to -evaluate in some circumstances. - -\end{enumerate} - -\subsection{Changes Introduced in V7.3.4} - -The following describes the most significant changes which -occurred in the AST library between versions V7.3.3 and V7.3.4: - -\begin{enumerate} - -\item By default, the simplification of Polygons no longer checks that the -edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices}, -can be set to zero in order to re-instate this check. - -\item The \htmlref{Polygon}{Polygon} class has a new mathod, -astConvex, -that returns a Polygon representing the shortest polygon (i.e. convex -hull) enclosing a specified set of pixel values within a supplied array. - -\end{enumerate} - -\subsection{Changes Introduced in V8.0.0} - -The following describes the most significant changes which -occurred in the AST library between versions V7.3.4 and V8.0.0: - -\begin{enumerate} - -\item AST is now distributed under the Lesser GPL licence. - -\item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack -package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform -least squares fitting of N-dimensional polynomials. - -\item Use of the IAU SOFA library has been replaced by ERFA library, which is -a re-badged copy of SOFA distributed under a less restrictive license. A -copy of ERFA is included within AST. - -\end{enumerate} - -\subsection{Changes Introduced in V8.0.1} - -The following describes the most significant changes which -occurred in the AST library between versions V8.0.0 and V8.0.1: - -\begin{enumerate} - -\item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the - \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}. -\item The order of WCS axes within new FITS-WCS headers created by \htmlref{astWrite}{astWrite} - can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}. -\item Supported added for FITS XPH (polar HEALPIX) projection. -\item The macro used to invoke the \htmlref{astAppendString}{astAppendString} utility function has - changed to allow printf-style converstions to be included in the - supplied text. Any code that uses this macro must be re-compiled. -\item The astRebin and astRebinSeq family of functions now include support - for arrays with char (byte) and unsigned char (unsigned byte) data types. - -\end{enumerate} - -\subsection{Changes Introduced in V8.0.2} -The following describes the most significant changes which -occurred in the AST library between versions V8.0.1 and V8.0.2: - -\begin{enumerate} -\item For security reasons, the change introduced to \htmlref{astAppendString}{astAppendString} in - V8.0.1 has been moved to a new function called \htmlref{astAppendStringf}{astAppendStringf}, and - astAppendString itself has been reverted to its V8.0.0 version. - Any software that has been built against V8.0.1 will need to be - re-compiled and re-linked against V8.0.2. -\end{enumerate} - - -\subsection{Changes Introduced in V8.0.3} -The following describes the most significant changes which -occurred in the AST library between versions V8.0.2 and V8.0.3: - -\begin{enumerate} - -\item Methods -astRebin, astRebinSeq, astResample and \htmlref{astTranGrid}{astTranGrid} -now report an error if an array is specified that has more pixels than -can be counted by a 32 bit integer. -\item The hypertext documentation is now generated using Tex4HT rather -than latex2html. The format of the hypertext docs has changed significantly. -\item Another bug fix associated with reading CAR projections from -FITS-WCS headers. -\item Constructor options strings of the form ``\texttt{..., "\%s", text );}'' -can now be supplied. This avoids a security issue associated with the -alternative form ``\texttt{..., text );}''. -\end{enumerate} - -\subsection{Changes Introduced in V8.0.4} -The following describes the most significant changes which -occurred in the AST library between versions V8.0.3 and V8.0.4: - -\begin{enumerate} - -\item The behaviour of the -\htmlref{astAddFrame}{astAddFrame} method has been changed slightly. Previously, astAddFrame -modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and -\htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes -to the current Frame of the modified FrameSet also affected the supplied -Frame object. Now, deep copies of the Mapping and Frame objects (rather -than references) are stored within the modified FrameSet. This means that -subsequent changes to the modified FrameSet will now have no effect on -the supplied Frame. - -\item The choice of default tick-mark gaps for time axes has been -improved, to avoid a previous issue which could result in no suitable gap -being found. - -- A new method called -\htmlref{astRegionOutline}{astRegionOutline} -has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST -\htmlref{Region}{Region}. - -\item A bug has been fixed that could cause astSimplfy to enter an infinite loop. - -\item Some improvements have been made to the Mapping simplification process -that allow more Mappings to be simplified. - -\item The Frame class has a new read-only attribute called InternalUnit, -which gives the units used for the unformatted (i.e. floating-point) axis -values used internally by application code. For most Frames, the -InternalUnit value is just the same as the Unit value (i.e. formatted and -unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class -always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of -Unit, indicating that floating-point SkyFrame axis values are always in units -of radians. - -\item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies -the relative error of the values in the table. It is used to decide if -the LutMap can be simplified to a straight line. - -\end{enumerate} - - -\subsection{Changes Introduced in V8.0.5} -The following describes the most significant changes which -occurred in the AST library between versions V8.0.4 and V8.0.5: - -\begin{enumerate} - -\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies -the smallest significant distance within the SkyFrame. It is used to -decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit -transformation. The default value is 0.001 arc-seconds. - -\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal -characters within FITS keyword names (i.e. characters not allowed by the -FITS standard) being detected. This bug could under some circumstances -cause a subsequent segmentation violation to occur. - -\item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS -keyword name is encountered that contains any illegal characters. See -attribute ``\htmlref{Warnings}{Warnings}'' and -function ``\htmlref{astWarnings}{astWarnings}''. - -\end{enumerate} - -\subsection{Changes Introduced in V8.1.0} -The following describes the most significant changes which -occurred in the AST library between versions V8.0.5 and V8.1.0: - -\begin{enumerate} - -\item The configure script has a new option ``--without-fortran'' that allows -AST to be built in situations where no Fortran compiler is available. The -resulting library has no Fortran interface and so cannot be used within -Fortran applications. Also, the link scripts do not attempt to include the -fortran runtime libraries. - -\end{enumerate} - -\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes -Introduced in V8.2} -The following describes the most significant changes which -occurred in the AST library between versions V8.1.0 and V8.2.0: - -\begin{enumerate} - -\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts -a vector to a unit vector relative to a specified centre, plus length. A -UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates -represent a unit vector parallel to the supplied input vector, and the -(N+1)'th output coordinate is the length of the input vector. - -\item The restriction that Mappings are immutable has been extended to all -Mapping classes. This means that attributes representing parameters of -a Mapping's forward or inverse transformation cannot be changed after -the Mapping has been created. In order to minimise the risk to existing -software, this rule does not apply to Mappings that have not yet been -included in other objects such as CmpMaps or FrameSets, or which have not -yet been cloned. In other words, an error is reported if an attempt is -made to change the nature of a Mapping's transformation, but only if the -reference count of the Mapping is greater than one. The Mapping classes -affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}. - -\end{enumerate} - - -\subsection{Changes Introduced in V8.3} -The following describes the most significant changes which -occurred in the AST library between versions V8.2.0 and V8.3.0: - -\begin{enumerate} - -\item A new method called \htmlref{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} - -\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes -Introduced in V8.4} -The following describes the most significant changes which have -occurred in the AST library between versions V8.3.0 and V8.4.0 (the -current version): - -\begin{enumerate} - -\item The PAL library files included in the AST distribution have been updated -to PAL version 0.9.7. - -\item Multiple identical NormMaps in series will now be simplified to a -single \htmlref{NormMap}{NormMap}. - -\item A NormMap that encapsulates a basic \htmlref{Frame}{Frame} will now be simplified to a -\htmlref{UnitMap}{UnitMap}. - -\item The \htmlref{astTimeAdd}{astTimeAdd} -method of the \htmlref{TimeMap}{TimeMap} class now include an extra argument that gives the -number of values supplied in the arguments array. Note, any existing code -that uses this method will need to be changed. - -\item The \htmlref{astSlaAdd}{astSlaAdd} -method of the \htmlref{SlaMap}{SlaMap} class now include an extra argument that gives the -number of values supplied in the arguments array. Note, any existing code -that uses this method will need to be changed. - -\item The \htmlref{astSpecAdd}{astSpecAdd} -method of the \htmlref{SpecMap}{SpecMap} class now include an extra argument that gives the -number of values supplied in the arguments array. Note, any existing code -that uses this method will need to be changed. - -\item Multiple identical NormMaps in series will now be simplified to a -single NormMap. - -\item A NormMap that encapsulates a basic Frame will now be simplified to a -UnitMap. - -\item If the -\htmlref{astMapRegion}{astMapRegion} -method is used to map a \htmlref{Region}{Region} into a new Frame that has fewer axes than -the original Region, and if the inverse transformation of the supplied -\htmlref{Mapping}{Mapping} does not specify a value for the missing axes, then those axes -are removed entirely from the Region. Previously they were retained, but -automatically supplied with bad values. This affects the number of mesh -points per axes for such Regions, and so affects the accuracy of overlap -determination. - -\end{enumerate} - -Programs which are statically linked will need to be re-linked in -order to take advantage of these new facilities. - -\end{document} |