#
AST Class Descriptions

Axis Store axis information The Axis class is used to store information associated with a particular axis of a FrameFrame. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from astWriteastWrite). Constructor Function None. Inheritance The Axis class inherits from the ObjectObject class. Box A box region with sides parallel to the axes of a Frame The Box class implements a RegionRegion which represents a box with sides parallel to the axes of a FrameFrame (i.e. an area which encloses a given range of values on each axis). A Box is similar to an IntervalInterval, 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 SkyFrameSkyFrame will look more like a fan than a box (the PolygonPolygon class can be used to create a box-like region close to a pole). Constructor Function astBoxastBox Inheritance The Box class inherits from the Region class. Attributes The Box class does not define any new attributes beyond those which are applicable to all Regions. Functions The Box class does not define any new functions beyond those which are applicable to all Regions. Channel Basic (textual) I/O channel The Channel class implements low-level input/output for the AST library. Writing an ObjectObject 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 " source" and " sink" 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 SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Constructor Function astChannelastChannel Inheritance The Channel class inherits from the Object class. Attributes In addition to those attributes common to all Objects, every Channel also has the following attributes:

CommentComment: Include textual comments in output?

FullFull: Set level of output detail

IndentIndent: Indentation increment between objects

ReportLevelReportLevel: Selects the level of error reporting

SinkFileSinkFile: The path to a file to which the Channel should write

SkipSkip: Skip irrelevant data?

SourceFileSourceFile: The path to a file from which the Channel should read

StrictStrict: Generate errors instead of warnings? Functions In addition to those functions applicable to all Objects, the following functions may also be applied to all Channels:

astWarningsastWarnings: Return warnings from the previous read or write

astPutChannelDataastPutChannelData: Store data to pass to source or sink functions

astReadastRead: Read an Object from a Channel

astWriteastWrite: Write an Object to a Channel ChebyMap Map coordinates using Chebyshev polynomial functions A ChebyMap is a form of MappingMapping which performs a Chebyshev polynomial transformation. Each output coordinate is a linear combination of Chebyshev polynomials of the first kind, of order zero up to a specified maximum order, evaluated at the input coordinates. The coefficients to be used in the linear combination are specified separately for each output coordinate.

For a 1-dimensional ChebyMap, the forward transformation is defined as follows:

f(x) = c0.T0(x' ) 241#241 c1.T1(x' ) 241#241 c2.T2(x' ) 241#241 ...

where: Tn(x' ) is the nth Chebyshev polynomial of the first kind:

T0(x' ) = 1

T1(x' ) = x'

Tn241#2411(x' ) = 2.x' .Tn(x' ) 241#241 Tn-1(x' )

x' is the inpux axis value, x, offset and scaled to the range [-1, 1] as x ranges over a specified bounding box, given when the ChebyMap is created. The input positions, x, supplied to the forward transformation must fall within the bounding box - bad axis values (AST__BAD) are generated for points outside the bounding box.

For an N-dimensional ChebyMap, the forward transformation is a generalisation of the above form. Each output axis value is the sum of " ncoeff" terms, where each term is the product of a single coefficient value and N factors of the form Tn(x' _i), where " x' _i" is the normalised value of the i' th input axis value.

The forward and inverse transformations are defined independantly by separate sets of coefficients, supplied when the ChebyMap is created. If no coefficients are supplied to define the inverse transformation, the astPolyTranastPolyTran method of the parent PolyMapPolyMap class can instead be used to create an inverse transformation. The inverse transformation so generated will be a Chebyshev polynomial with coefficients chosen to minimise the residuals left by a round trip (forward transformation followed by inverse transformation). Constructor Function astChebyMapastChebyMap Inheritance The ChebyMap class inherits from the PolyMap class. Attributes The ChebyMap class does not define any new attributes beyond those which are applicable to all PolyMaps. Functions In addition to those functions applicable to all PolyMap, the following functions may also be applied to all ChebyMaps:

astChebyDomainastChebyDomain: Get the bounds of the domain of the ChebyMap Circle A circular or spherical region within a Frame The Circle class implements a RegionRegion which represents a circle or sphere within a FrameFrame. Constructor Function astCircleastCircle Inheritance The Circle class inherits from the Region class. Attributes The Circle class does not define any new attributes beyond those which are applicable to all Regions. Functions In addition to those functions applicable to all Regions, the following functions may also be applied to all Circles:

astCircleParsastCirclePars: Get the geometric parameters of the Circle CmpFrame Compound Frame A CmpFrame is a compound FrameFrame 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 MappingMapping, a CmpFrame can also be used as a Mapping. Normally, a CmpFrame is simply equivalent to a UnitMapUnitMap, but if either of the component Frames within a CmpFrame is a RegionRegion (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. Constructor Function astCmpFrameastCmpFrame Inheritance The CmpFrame class inherits from the Frame class. 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 SpecFrameSpecFrame and a SkyFrameSkyFrame, then the CmpFrame will recognise the " EquinoxEquinox" attribute and forward access requests to the component SkyFrame. Likewise, it will recognise the " RestFreqRestFreq" 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. Functions The CmpFrame class does not define any new functions beyond those which are applicable to all Frames. CmpMap Compound Mapping A CmpMap is a compound MappingMapping which allows two component Mappings (of any class) to be connected together to form a more complex Mapping. This connection may either be " in series" (where the first Mapping is used to transform the coordinates of each point and the second mapping is then applied to the result), or " in parallel" (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. Constructor Function astCmpMapastCmpMap Inheritance The CmpMap class inherits from the Mapping class. Attributes The CmpMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The CmpMap class does not define any new functions beyond those which are applicable to all Mappings. CmpRegion A combination of two regions within a single Frame A CmpRegion is a RegionRegion 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 FrameFrame, but it must be possible for the astConvertastConvert function to determine a MappingMapping 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 SkyFrameSkyFrame 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. Constructor Function astCmpRegionastCmpRegion Inheritance The CmpRegion class inherits from the Region class. Attributes The CmpRegion class does not define any new attributes beyond those which are applicable to all Regions. Functions The CmpRegion class does not define any new functions beyond those which are applicable to all Regions. DSBSpecFrame Dual sideband spectral coordinate system description A DSBSpecFrame is a specialised form of SpecFrameSpecFrame 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 " lower side band" (LSB) and one from the " upper side band" (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 " Local Oscillator" (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 SideBandSideBand 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 " central" 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 " intermediate frequency" (IFIF). 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. Constructor Function astDSBSpecFrameastDSBSpecFrame Inheritance The DSBSpecFrame class inherits from the SpecFrame class. Attributes In addition to those attributes common to all SpecFrames, every DSBSpecFrame also has the following attributes:

AlignSideBandAlignSideBand: Should alignment occur between sidebands?

DSBCentreDSBCentre: The central position of interest.

IFIF: The intermediate frequency used to define the LO frequency.

ImagFreqImagFreq: The image sideband equivalent of the rest frequency.

SideBandSideBand: Indicates which sideband the DSBSpecFrame represents. Functions The DSBSpecFrame class does not define any new functions beyond those which are applicable to all SpecFrames. DssMap Map points using a Digitised Sky Survey plate solution The DssMap class implements a MappingMapping 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. Constructor Function The DssMap class does not have a constructor function. A DssMap is created only as a by-product of reading a FrameSetFrameSet (using astReadastRead) from a FitsChanFitsChan which contains FITS header cards describing a DSS plate solution, and whose EncodingEncoding attribute is set to " DSS" . The result of such a read, if successful, is a FrameSet whose base and current Frames are related by a DssMap. Inheritance The DssMap class inherits from the Mapping class. Attributes The DssMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The DssMap class does not define any new functions beyond those which are applicable to all Mappings. Ellipse An elliptical region within a 2-dimensional Frame The Ellipse class implements a RegionRegion which represents a ellipse within a 2-dimensional FrameFrame. Constructor Function astEllipseastEllipse Inheritance The Ellipse class inherits from the Region class. Attributes The Ellipse class does not define any new attributes beyond those which are applicable to all Regions. Functions In addition to those functions applicable to all Regions, the following functions may also be applied to all Ellipses:

astEllipseParsastEllipsePars: Get the geometric parameters of the Ellipse FitsChan I/O Channel using FITS header cards to represent Objects A FitsChan is a specialised form of ChannelChannel which supports I/O operations involving the use of FITS (Flexible Image Transport SystemSystem) header cards. Writing an ObjectObject to a FitsChan (using astWriteastWrite) 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 " header cards" conforming to FITS conventions. Any sequence of FITS-conforming header cards may be stored, apart from the " END" card whose existence is merely implied. The cards may be accessed in any order by using the FitsChan' s integer CardCard attribute, which identifies a " current" card, to which subsequent operations apply. Searches based on keyword may be performed (using astFindFitsastFindFits), new cards may be inserted (astPutFitsastPutFits, astPutCardsastPutCards, astSetFits1#1X2#2astSetFits1#1X2#2) and existing ones may be deleted (astDelFitsastDelFits), extracted (astGetFits1#1X2#2astGetFits1#1X2#2), or changed (astSetFits1#1X2#2).

When you create a FitsChan, you have the option of specifying " source" and " sink" 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 SourceFileSourceFile 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 SinkFileSinkFile 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 astReadastRead).

Coordinate system information may be described using FITS header cards using several different conventions, termed " encodings" . When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan' s EncodingEncoding 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 astRetainFitsastRetainFits 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. Constructor Function astFitsChanastFitsChan Inheritance The FitsChan class inherits from the Channel class. Attributes In addition to those attributes common to all Channels, every

FitsChan also has the following attributes:

AllWarningsAllWarnings: A list of the available conditions

AltAxesAltAxes: Controls generation of FITS-WCS alternate axis descriptions

CardCard: Index of current FITS card in a FitsChan

CardCommCardComm: The comment of the current FITS card in a FitsChan

CardNameCardName: The keyword name of the current FITS card in a FitsChan

CardTypeCardType: The data type of the current FITS card in a FitsChan

CarLinCarLin: Ignore spherical rotations on CAR projections?

CDMatrixCDMatrix: Use a CD matrix instead of a PC matrix?

CleanClean: Remove cards used whilst reading even if an error occurs?

DefB1950DefB1950: Use FK4 B1950 as default equatorial coordinates?

EncodingEncoding: System for encoding Objects as FITS headers

FitsAxisOrderFitsAxisOrder: Sets the order of WCS axes within new FITS-WCS headers

FitsDigitsFitsDigits: Digits of precision for floating-point FITS values

FitsRoundingFitsRounding: Controls rounding of floating-point FITS values

ForceTabForceTab: Force use of the FITS " -TAB" algorithm?

IgnoreBadAltIgnoreBadAlt: Ignore unreadable alternate axis descriptions?

IwcIwc: Add a FrameFrame describing Intermediate World Coords?

NcardNcard: Number of FITS header cards in a FitsChan

NkeyNkey: Number of unique keywords in a FitsChan

PolyTanPolyTan: Use PVi_mPVi_m keywords to define distorted TAN projection?

SipOKSipOK: Use Spitzer Space Telescope keywords to define distortion?

SipReplaceSipReplace: Replace SIP inverse transformation?

TabOKTabOK: Should the FITS " -TAB" algorithm be recognised?

WarningsWarnings: Produces warnings about selected conditions Functions In addition to those functions applicable to all Channels, the following functions may also be applied to all FitsChans:

astDelFitsastDelFits: Delete the current FITS card in a FitsChan

astEmptyFitsastEmptyFits: Delete all cards in a FitsChan

astFindFitsastFindFits: Find a FITS card in a FitsChan by keyword

astGetFits1#1X2#2astGetFits1#1X2#2: Get a keyword value from a FitsChan

astGetTablesastGetTables: Retrieve any FitsTables from a FitsChan

astPurgeWCSastPurgeWCS: Delete all WCS-related cards in a FitsChan

astPutCardsastPutCards: Stores a set of FITS header card in a FitsChan

astPutFitsastPutFits: Store a FITS header card in a FitsChan

astPutTableastPutTable: Store a single FitsTableFitsTable in a FitsChan

astPutTablesastPutTables: Store multiple FitsTables in a FitsChan

astReadFitsastReadFits: Read cards in through the source function

astRemoveTablesastRemoveTables: Remove one or more FitsTables from a FitsChan

astRetainFitsastRetainFits: Ensure current card is retained in a FitsChan

astSetFits1#1X2#2astSetFits1#1X2#2: Store a new keyword value in a FitsChan

astShowFitsastShowFits: Display the contents of a FitsChan on standard output

astTableSourceastTableSource: Register a source function for FITS table access

astTestFitsastTestFits: Test if a keyword has a defined value in a FitsChan

astWriteFitsastWriteFits: Write all cards out to the sink function

AST_SHOWFITS: Display the contents of a FitsChan on standard output FitsTable A representation of a FITS binary table The FitsTable class is a representation of a FITS binary table. It inherits from the TableTable class. The parent Table is used to hold the binary data of the main table, and a FitsChanFitsChan (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 " -TAB" 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: " heap" 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. Constructor Function astFitsTableastFitsTable Inheritance The FitsTable class inherits from the Table class. Attributes The FitsTable class does not define any new attributes beyond those which are applicable to all Tables. Functions In addition to those functions applicable to all Tables, the following functions may also be applied to all FitsTables:

astColumnNullKastColumnNullK: Get/set the null value for a column of a FitsTable

astColumnSizeastColumnSize: Get number of bytes needed to hold a full column of data

astGetColumnDataastGetColumnData: Retrieve all the data values stored in a column

astGetTableHeaderastGetTableHeader: Get the FITS headers from a FitsTable

astPutColumnDataastPutColumnData: Store data values in a column

astPutTableHeaderastPutTableHeader: Store FITS headers within a FitsTable FluxFrame Measured flux description A FluxFrame is a specialised form of one-dimensional FrameFrame 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' s SystemSystem 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 SpecValSpecVal attribute). Thus this class is more appropriate for use with images rather than spectra. Constructor Function astFluxFrameastFluxFrame Inheritance The FluxFrame class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every FluxFrame also has the following attributes:

SpecValSpecVal: The spectral position at which the flux values are measured. Functions The FluxFrame class does not define any new functions beyond those which are applicable to all Frames. Frame Coordinate system description 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 TitleTitle (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. Constructor Function astFrameastFrame When used as a MappingMapping, a Frame implements a unit (null) transformation in both the forward and inverse directions (equivalent to a UnitMapUnitMap). The NinNin and NoutNout attribute values are both equal to the number of Frame axes. Inheritance The Frame class inherits from the Mapping class. 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):

AlignSystemAlignSystem: Coordinate system used to align Frames

Bottom(axis)Bottom(axis): Lowest axis value to display

Digits/Digits(axis)Digits/Digits(axis): Number of digits of precision

Direction(axis)Direction(axis): Display axis in conventional direction?

DomainDomain: Coordinate system domain

DtaiDtai: Difference between the TAI and UTC timescale

Dut1Dut1: Difference between the UT1 and UTC timescale

EpochEpoch: Epoch of observation

Format(axis)Format(axis): Format specification for axis values

InternalUnit(axis)InternalUnit(axis): Physical units for unformated axis values

Label(axis)Label(axis): AxisAxis label

MatchEndMatchEnd: Match trailing axes?

MaxAxesMaxAxes: Maximum number of Frame axes to match

MinAxesMinAxes: Minimum number of Frame axes to match

NaxesNaxes: Number of Frame axes

NormUnit(axis)NormUnit(axis): Normalised physical units for formatted axis values

ObsAltObsAlt: Geodetic altitude of observer

ObsLatObsLat: Geodetic latitude of observer

ObsLonObsLon: Geodetic longitude of observer

PermutePermute: Permute axis order?

PreserveAxesPreserveAxes: Preserve axes?

Symbol(axis)Symbol(axis): Axis symbol

SystemSystem: Coordinate system used to describe the domain

TitleTitle: Frame title

Top(axis)Top(axis): Highest axis value to display

Unit(axis)Unit(axis): Physical units for formatted axis values Functions In addition to those functions applicable to all Mappings, the following functions may also be applied to all Frames:

astAngleastAngle: Calculate the angle subtended by two points at a third point

astAxAngleastAxAngle: Find the angle from an axis, to a line through two points

astAxDistanceastAxDistance: Calculate the distance between two axis values

astAxNormastAxNorm: Normalises an array of axis values

astAxOffsetastAxOffset: Calculate an offset along an axis

astConvertastConvert: Determine how to convert between two coordinate systems

astDistanceastDistance: Calculate the distance between two points in a Frame

astFindFrameastFindFrame: Find a coordinate system with specified characteristics

astFormatastFormat: Format a coordinate value for a Frame axis

astGetActiveUnitastGetActiveUnit: Determines how the Unit attribute will be used

astIntersectastIntersect: Find the intersection between two geodesic curves

astMatchAxesastMatchAxes: Find any corresponding axes in two Frames

astNormastNorm: Normalise a set of Frame coordinates representing one point

astNormPointsastNormPoints: Normalise a collection of points

astOffsetastOffset: Calculate an offset along a geodesic curve

astOffset2astOffset2: Calculate an offset along a geodesic curve in a 2D Frame

astPermAxesastPermAxes: Permute the order of a Frame' s axes

astPickAxesastPickAxes: Create a new Frame by picking axes from an existing one

astResolveastResolve: Resolve a vector into two orthogonal components

astSetActiveUnitastSetActiveUnit: Specify how the Unit attribute should be used

astUnformatastUnformat: Read a formatted coordinate value for a Frame axis

AST_NORMPOINTS: Normalise a collection of points FrameSet Set of inter-related coordinate systems 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 MappingMapping 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 " base" FrameFrame and a " current" 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' s BaseBase and CurrentCurrent 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 " native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the " apparent" 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 TitleTitle 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 " native" coordinates into " apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see astInvertastInvert), 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 RegionRegion is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the masking effects produced by any Regions included in the path between the Frames. Constructor Function astFrameSetastFrameSet Inheritance The FrameSet class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every FrameSet also has the following attributes:

AllVariantsAllVariants: List of all variant mappings stored with current Frame

BaseBase: FrameSet base Frame index

CurrentCurrent: FrameSet current Frame index

NframeNframe: Number of Frames in a FrameSet

VariantVariant: 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' s class. (For example, the EquinoxEquinox attribute, defined by the SkyFrameSkyFrame 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. Functions In addition to those functions applicable to all Frames, the following functions may also be applied to all FrameSets:

astAddFrameastAddFrame: Add a Frame to a FrameSet to define a new coordinate system

astAddVariantastAddVariant: Add a variant Mapping to the current Frame

astGetFrameastGetFrame: Obtain a pointer to a specified Frame in a FrameSet

astGetMappingastGetMapping: Obtain a Mapping between two Frames in a FrameSet

astMirrorVariantsastMirrorVariants: Make the current Frame mirror variant Mappings in another Frame

astRemapFrameastRemapFrame: Modify a Frame' s relationship to the other Frames in a FrameSet

astRemoveFrameastRemoveFrame: Remove a Frame from a FrameSet GrismMap Transform 1-dimensional coordinates using a grism dispersion equation A GrismMap is a specialised form of MappingMapping which transforms 1-dimensional coordinates using the spectral dispersion equation described in FITS-WCS paper III " Representation of spectral coordinates in FITS" . This describes the dispersion produced by gratings, prisms and grisms.

When initially created, the forward transformation of a GrismMap transforms input " grism parameter" values into output wavelength values. The " grism parameter" is a dimensionless value which is linearly related to position on the detector. It is defined in FITS-WCS paper III as " the offset on the detector from the point of intersection of the camera axis, measured in units of the effective local length" . The units in which wavelength values are expected or returned is determined by the values supplied for the GrismWaveRGrismWaveR, GrismNRPGrismNRP and GrismGGrismG attribute: whatever units are used for these attributes will also be used for the wavelength values. Constructor Function astGrismMapastGrismMap Inheritance The GrismMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every GrismMap also has the following attributes:

GrismNRGrismNR: The refractive index at the reference wavelength

GrismNRPGrismNRP: Rate of change of refractive index with wavelength

GrismWaveRGrismWaveR: The reference wavelength

GrismAlphaGrismAlpha: The angle of incidence of the incoming light

GrismGGrismG: The grating ruling density

GrismMGrismM: The interference order

GrismEpsGrismEps: The angle between the normal and the dispersion plane

GrismThetaGrismTheta: Angle between normal to detector plane and reference ray Functions The GrismMap class does not define any new functions beyond those which are applicable to all Mappings. Interval A region representing an interval on one or more axes of a Frame The Interval class implements a RegionRegion which represents upper and/or lower limits on one or more axes of a FrameFrame. 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 SkyFrameSkyFrame coordinates). A BoxBox should usually be used in these cases since this requires the user to think about suitable upper and lower limits, Constructor Function astIntervalastInterval Inheritance The Interval class inherits from the Region class. Attributes The Interval class does not define any new attributes beyond those which are applicable to all Regions. Functions The Interval class does not define any new functions beyond those which are applicable to all Regions. IntraMap Map points using a private transformation function The IntraMap class provides a specialised form of MappingMapping 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 astIntraRegastIntraReg before creating an IntraMap. Constructor Function astIntraMapastIntraMap (also see astIntraReg) Inheritance The IntraMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every IntraMap also has the following attributes:

IntraFlagIntraFlag: IntraMap identification string Functions The IntraMap class does not define any new functions beyond those which are applicable to all Mappings. KeyMap Store a set of key/value pairs 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 KeyCaseKeyCase 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 ObjectObject pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a MappingMapping 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. Constructor Function astKeyMapastKeyMap Inheritance The KeyMap class inherits from the Object class. Attributes In addition to those attributes common to all Objects, every KeyMap also has the following attributes:

KeyCaseKeyCase: Sets the case in which keys are stored

KeyErrorKeyError: ReportReport an error if the requested key does not exist?

SizeGuessSizeGuess: The expected size of the KeyMap.

SortBySortBy: Determines how keys are sorted in a KeyMap.

MapLockedMapLocked: Prevent new entries being added to the KeyMap? Functions In addition to those functions applicable to all Objects, the following functions may also be applied to all KeyMaps:

astMapCopyastMapCopy: Copy all entries from one KeyMap into another

astMapCopyEntryastMapCopyEntry: Copy a single entry from one KeyMap into another

astMapDefinedastMapDefined: Does a KeyMap contain a defined value for a key?

astMapGet01#1X2#2astMapGet01#1X2#2: Get a named scalar entry from a KeyMap

astMapGet11#1X2#2astMapGet11#1X2#2: Get a named vector entry from a KeyMap

astMapGetCastMapGetC: Get a scalar or vector entry as a single string.

astMapGetElem1#1X2#2astMapGetElem1#1X2#2: Get an element of a named vector entry from a KeyMap

astMapHasKeyastMapHasKey: Does the KeyMap contain a named entry?

astMapKeyastMapKey: Return the key name at a given index in the KeyMap

astMapLenCastMapLenC: Get the length of a named character entry in a KeyMap

astMapLengthastMapLength: Get the length of a named entry in a KeyMap

astMapPut01#1X2#2astMapPut01#1X2#2: Add a new scalar entry to a KeyMap

astMapPut11#1X2#2astMapPut11#1X2#2: Add a new vector entry to a KeyMap

astMapPutElem1#1X2#2astMapPutElem1#1X2#2: Puts a value into a vector entry in a KeyMap

astMapPutUastMapPutU: Add a new entry to a KeyMap with an undefined value

astMapRemoveastMapRemove: Removed a named entry from a KeyMap

astMapRenameastMapRename: Rename an existing entry in a KeyMap

astMapSizeastMapSize: Get the number of entries in a KeyMap

astMapTypeastMapType: Return the data type of a named entry in a map LutMap Transform 1-dimensional coordinates using a lookup table A LutMap is a specialised form of MappingMapping 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. Constructor Function astLutMapastLutMap Inheritance The LutMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every LutMap also has the following attributes:

LutEpsilonLutEpsilon: The relative error of the values in the table.

LutInterpLutInterp: The interpolation method to use between table entries. Functions The LutMap class does not define any new functions beyond those which are applicable to all Mappings. Mapping Inter-relate two coordinate systems This class provides the basic facilities for transforming a set of coordinates (representing " input" points) to give a new set of coordinates (representing " output" 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. Constructor Function None. Inheritance The Mapping class inherits from the ObjectObject class. Attributes In addition to those attributes common to all Objects, every Mapping also has the following attributes:

InvertInvert: Mapping inversion flag

IsLinearIsLinear: Is the Mapping linear?

IsSimpleIsSimple: Has the Mapping been simplified?

NinNin: Number of input coordinates for a Mapping

NoutNout: Number of output coordinates for a Mapping

ReportReport: Report transformed coordinates?

TranForwardTranForward: Forward transformation defined?

TranInverseTranInverse: Inverse transformation defined? Functions In addition to those functions applicable to all Objects, the following functions may also be applied to all Mappings:

astDecomposeastDecompose: Decompose a Mapping into two component Mappings

astTranGridastTranGrid: Transform a grid of positions

astInvertastInvert: Invert a Mapping

astLinearApproxastLinearApprox: Calculate a linear approximation to a Mapping

astMapBoxastMapBox: Find a bounding box for a Mapping

astMapSplitastMapSplit: Split a Mapping up into parallel component Mappings

astQuadApproxastQuadApprox: Calculate a quadratic approximation to a 2D Mapping

astRateastRate: Calculate the rate of change of a Mapping output

astRebin1#1X2#2astRebin1#1X2#2: Rebin a region of a data grid

astRebinSeq1#1X2#2astRebinSeq1#1X2#2: Rebin a region of a sequence of data grids

astResample1#1X2#2astResample1#1X2#2: Resample a region of a data grid

astRemoveRegionsastRemoveRegions: Remove any Regions from a Mapping

astSimplifyastSimplify: Simplify a Mapping

astTran1astTran1: Transform 1-dimensional coordinates

astTran2astTran2: Transform 2-dimensional coordinates

astTranNastTranN: Transform N-dimensional coordinates

astTranPastTranP: Transform N-dimensional coordinates held in separate arrays MathMap Transform coordinates using mathematical expressions A MathMap is a MappingMapping 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 IntraMapIntraMap), 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. Constructor Function astMathMapastMathMap Inheritance The MathMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every MathMap also has the following attributes: SeedSeed: Random number seed

SimpFISimpFI: Forward-inverse MathMap pairs simplify?

SimpIFSimpIF: Inverse-forward MathMap pairs simplify? Functions The MathMap class does not define any new functions beyond those which are applicable to all Mappings. MatrixMap Map coordinates by multiplying by a matrix A MatrixMap is form of MappingMapping 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. Constructor Function astMatrixMapastMatrixMap Inheritance The MatrixMap class inherits from the Mapping class. Attributes The MatrixMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The MatrixMap class does not define any new functions beyond those which are applicable to all Mappings. Moc An arbitrary region of the sky expressed as a collection of HEALPix cells The Moc class uses the IVOA MOC (Multi-Order Coverage) recommendation to describe a region on the sky. The region is made up of an arbitrary collection of cells from the HEALPix sky tessellation, and thus may represent any area on the sky, subject to the constraint that the edges of the area correspond to edges of the HEALPix cells. See the MOC recommendation for further information (http://www.ivoa.net/documents/MOC/).

The Moc class describes an arbitrary collection of cells on the sky, whereas other subclasses of RegionRegion describe exact geometric shapes in any arbitrary domain. This results in some differences between Mocs and other types of Region, the main one being that Mocs have no associated uncertainty.

The MOC recommendation requires that a MOC always describes a sky area using the ICRS coordinate system. However, the Moc class, like other subclasses of Region, allows its attributes to be changed so that it represents the equivalent area in any celestial coordinate system that can be mapped to ICRS. See attribute AdaptiveAdaptive.

In practice, to use this class an empty Moc object (i.e. a Moc describing a null area of the sky) should first be created using the astMocastMoc constructor. Areas of the sky should then be added into the empty Moc using one or more of the class methods.

If it is required to write a Moc out to a FITS binary table, the data value and headers to put in the table can be obtained using methods astGetMocDataastGetMocData and astGetMocHeaderastGetMocHeader The MOC described by an existing FITS binary table can be added into a Moc object using the astAddMocDataastAddMocData method.

Note, this class is limited to MOCs for which the number of cells in the normalised MOC can be represented in a four byte signed integer. Constructor Function astMoc Inheritance The Moc class inherits from the Region class. Attributes In addition to those attributes common to all Regions, every Moc also has the following attributes: MaxOrderMaxOrder: the highest HEALPix order used in the MOC

MaxResMaxRes: the best resolution of the MOC, in arc-seconds

MinOrderMinOrder: the HEALPix order at which to search when converting to MOC

MinResMinRes: the resolution at which to search, in arc-seconds

MocAreaMocArea: the area of the MOC

MocLengthMocLength: the table length used to describe a MOC in FITS

MocTypeMocType: the data type used to describe a MOC in FITS Functions In addition to those functions applicable to all Regions, the following functions may also be applied to all Mocs:

astAddCellastAddCell: Adds a single HEALPix cell into an existing Moc

astAddMocDataastAddMocData: Adds a FITS binary table into an existing Moc

astAddMocStringastAddMocString: Adds a JSON or string-encoded MOC into an existing Moc

astAddPixelMask1#1X2#2astAddPixelMask1#1X2#2: Adds a pixel mask to an existing Moc

astAddRegionastAddRegion: Adds a Region to an existing Moc

astGetCellastGetCell: Identify the next cell included in a Moc

astGetMocDataastGetMocData: Get the FITS binary table data describing a Moc

astGetMocHeaderastGetMocHeader: Get the FITS binary table headers describing a Moc

astGetMocStringastGetMocString: Get the JSON or string-encoded form of a Moc

astTestCellastTestCell: Test if a single HEALPix cell is included in a Moc MocChan I/O Channel for textual representations of Mocs A MocChan is a specialised form of ChannelChannel which supports the reading and writing of AST MocMoc objects as text, using the conventions of the JSON and string encodings described in the IVOA' s MOC recommendation, version 1.1. Writing a Moc to a MocChan (using astWriteastWrite) will, if the Moc is suitable, generate a textual description of that Moc, and reading from a MocChan will create a new Moc from its textual description. See the Moc class for further information.

Normally, when you use a MocChan, you should provide " source" and " sink" 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, a MocChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Constructor Function astMocChanastMocChan Inheritance The MocChan class inherits from the Channel class. Attributes In addition to those attributes common to all Channels, every MocChan also has the following attributes:

MocFormatMocFormat: Whether to use JSON or string format

MocLineLenMocLineLen: Controls output buffer length Functions The MocChan class does not define any new functions beyond those which are applicable to all Channels. NormMap Normalise coordinates using a supplied Frame The NormMap class implements a MappingMapping which normalises coordinate values using the astNormastNorm function of a supplied FrameFrame. 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 astSimplifyastSimplify function will replace neighbouring pairs of forward and inverse NormMaps by a single UnitMapUnitMap (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 CmpMapCmpMap contains a NormMap, the CmpMap will still cancel with its own inverse. Constructor Function astNormMapastNormMap Inheritance The NormMap class inherits from the Mapping class. Attributes The NormMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The NormMap class does not define any new functions beyond those which are applicable to all Mappings. NullRegion A boundless region within a Frame The NullRegion class implements a RegionRegion with no bounds within a FrameFrame. If the NegatedNegated 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). Constructor Function astNullRegionastNullRegion Inheritance The NullRegion class inherits from the Region class. Attributes The NullRegion class does not define any new attributes beyond those which are applicable to all Regions. Functions The NullRegion class does not define any new functions beyond those which are applicable to all Regions. Object Base class for all AST Objects 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. Constructor Function None. Inheritance The Object base class does not inherit from any other class. Attributes All Objects have the following attributes:

ClassClass: Object class name

IDID: Object identification string

IdentIdent: Permanent Object identification string

NobjectNobject: Number of Objects in class

ObjSizeObjSize: The in-memory size of the Object in bytes

RefCountRefCount: Count of active Object pointers

UseDefsUseDefs: Allow use of default values for Object attributes? Functions The following functions may be applied to all Objects:

astAnnulastAnnul: Annul a pointer to an Object

astBeginastBegin: Begin a new AST context

astClearastClear: Clear attribute values for an Object

astCloneastClone: Clone a pointer to an Object

astCopyastCopy: Copy an Object

astCreatedAtastCreatedAt: Returns information about where an object was created

astDeleteastDelete: Delete an Object

astEndastEnd: End an AST context

astEscapesastEscapes: Control whether graphical escape sequences are removed

astExemptastExempt: Exempt an Object pointer from AST context handling

astExportastExport: Export an Object pointer to an outer context

astGet1#1X2#2astGet1#1X2#2: Get an attribute value for an Object

astHasAttributeastHasAttribute: Test if an Object has a named attribute

astImportastImport: Import an Object pointer to the current context

astIsA1#1Class2#2astIsA1#1Class2#2: Test class membership

astLockastLock: Lock an Object for use by the calling thread

astToStringastToString: Create an in-memory serialisation of an Object

astSameastSame: Do two AST pointers refer to the same Object?

astSetastSet: Set attribute values for an Object

astSet1#1X2#2astSet1#1X2#2: Set an attribute value for an Object

astShowastShow: Display a textual representation of an Object on standard output

astTestastTest: Test if an attribute value is set for an Object

astThreadastThread: Get the thread (if any) that has locked an Object

astTuneastTune: Set or get an integer AST tuning parameter

astTuneCastTuneC: Set or get a character AST tuning parameter

astUnlockastUnlock: Unlock an Object for use by other threads

astFromStringastFromString: Re-create an Object from an in-memory serialisation

astVersionastVersion: Return the verson of the AST library being used. PcdMap Apply 2-dimensional pincushion/barrel distortion A PcdMap is a non-linear MappingMapping 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 34#34 ( 1 241#241 C 34#34 R 34#34 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 DiscoDisco).

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. Constructor Function astPcdMapastPcdMap Inheritance The PcdMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every PcdMap also has the following attributes:

DiscoDisco: PcdMap pincushion/barrel distortion coefficient

PcdCen(axis)PcdCen(axis): Centre coordinates of pincushion/barrel distortion Functions The PcdMap class does not define any new functions beyond those which are applicable to all Mappings. PermMap Coordinate permutation Mapping A PermMap is a MappingMapping 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. Constructor Function astPermMapastPermMap Inheritance The PermMap class inherits from the Mapping class. Attributes The PermMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The PermMap class does not define any new functions beyond those which are applicable to all Mappings. Plot Provide facilities for 2D graphical output This class provides facilities for producing 2D graphical output. A Plot is a specialised form of FrameSetFrameSet, in which the base FrameFrame describes a " graphical" 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 " physical" 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 MappingMapping 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 astCurveastCurve, astGenCurveastGenCurve and astPolyCurveastPolyCurve). A Plot also provides facilities for drawing markers or symbols (astMarkastMark), text (astTextastText) and grid lines (astGridLineastGridLine). It is also possible to draw curvilinear axes with optional coordinate grids (astGridastGrid). 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 CurrentCurrent attribute. You may also set up clipping (see astClipastClip) 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). Constructor Function astPlotastPlot Inheritance The Plot class inherits from the FrameSet class. Attributes In addition to those attributes common to all FrameSets, every Plot also has the following attributes:

Abbrev: Abbreviate leading fields?

BorderBorder: Draw a border around valid regions of a Plot?

ClipClip: Clip lines and/or markers at the Plot boundary?

ClipOpClipOp: Combine Plot clipping limits using a boolean OR?

Colour(element)Colour(element): Colour index for a Plot element

DrawAxes(axis)DrawAxes(axis): Draw axes for a Plot?

DrawTitleDrawTitle: Draw a title for a Plot?

EscapeEscape: Allow changes of character attributes within strings?

Edge(axis)Edge(axis): Which edges to label in a Plot

Font(element)Font(element): Character font for a Plot element

Gap(axis)Gap(axis): IntervalInterval between linearly spaced major axis values

GrfGrf: Select the graphics interface to use.

GridGrid: Draw grid lines for a Plot?

InvisibleInvisible: Draw graphics in invisible ink?

LabelAt(axis)LabelAt(axis): Where to place numerical labels for a Plot

LabelUnits(axis)LabelUnits(axis): Use axis unit descriptions in a Plot?

LabelUp(axis)LabelUp(axis): Draw numerical Plot labels upright?

LabellingLabelling: Label and tick placement option for a Plot

LogGap(axis)LogGap(axis): Interval between logarithmically spaced major axis values

LogPlot(axis)LogPlot(axis): Map the plot onto the screen logarithmically?

LogTicks(axis)LogTicks(axis): Space the major tick marks logarithmically?

MajTickLen(axis)MajTickLen(axis): Length of major tick marks for a Plot

MinTickLen(axis)MinTickLen(axis): Length of minor tick marks for a Plot

MinTick(axis)MinTick(axis): Density of minor tick marks for a Plot

NumLab(axis)NumLab(axis): Draw numerical axis labels for a Plot?

NumLabGap(axis)NumLabGap(axis): Spacing of numerical axis labels for a Plot

Size(element)Size(element): Character size for a Plot element

Style(element)Style(element): Line style for a Plot element

TextGapTypeTextGapType: Controls interpretation of TextLabGap and TitleGapTitleGap

TextLab(axis)TextLab(axis): Draw descriptive axis labels for a Plot?

TextLabGap(axis)TextLabGap(axis): Spacing of descriptive axis labels for a Plot

TickAllTickAll: Draw tick marks on all edges of a Plot?

TitleGapTitleGap: Vertical spacing for a Plot title

TolTol: Plotting tolerance

Width(element)Width(element): Line width for a Plot element Functions In addition to those functions applicable to all FrameSets, the following functions may also be applied to all Plots:

astBBufastBBuf: Begin a new graphical buffering context

astBorderastBorder: Draw a border around valid regions of a Plot

astBoundingBoxastBoundingBox: Returns a bounding box for previously drawn graphics

astClipastClip: Set up or remove clipping for a Plot

astCurveastCurve: Draw a geodesic curve

astEBufastEBuf: End the current graphical buffering context

astGenCurveastGenCurve: Draw a generalized curve

astGetGrfContextastGetGrfContext: Get the graphics context for a Plot

astGrfPopastGrfPop: Retrieve previously saved graphics functions

astGrfPushastGrfPush: Save the current graphics functions

astGrfSetastGrfSet: Register a graphics routine for use by a Plot

astGridastGrid: Draw a set of labelled coordinate axes

astGridLineastGridLine: Draw a grid line (or axis) for a Plot

astMarkastMark: Draw a set of markers for a Plot

astPolyCurveastPolyCurve: Draw a series of connected geodesic curves

astRegionOutlineastRegionOutline: Draw the outline of an AST RegionRegion

astTextastText: Draw a text string for a Plot 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. " (Grid1)" and " (Grid2)" ) or together (e.g. " (Grid)" ):

Axes: AxisAxis lines drawn through tick marks using astGrid

Axis1: Axis line drawn through tick marks on axis 1 using astGrid

Axis2: Axis line drawn through tick marks on axis 2 using astGrid

Border: The Plot border drawn using astBorder, astGrid or astRegionOutline

Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve

Grid: Grid lines drawn using astGridLine or astGrid

Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid

Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid

Markers: Graphical markers (symbols) drawn using astMark

NumLab: Numerical axis labels drawn using astGrid

NumLab1: Numerical labels for axis 1 drawn using astGrid

NumLab2: Numerical labels for axis 2 drawn using astGrid

Strings: Text strings drawn using astText

TextLab: Descriptive axis labels drawn using astGrid

TextLab1: Descriptive label for axis 1 drawn using astGrid

TextLab2: Descriptive label for axis 2 drawn using astGrid

Ticks: Tick marks (both major and minor) drawn using astGrid

Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid

Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid

TitleTitle: The Plot title drawn using astGrid Plot3D Provide facilities for 3D graphical output A Plot3D is a specialised form of PlotPlot that provides facilities for producing 3D graphical output, including fully annotated 3D coordinate grids. The base FrameFrame in a Plot3D describes a 3-dimensional " graphical" 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 " drawn" 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 " grf3d" 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 ast_linkast_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 " eye" /" camera" 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 " physical" 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 CurrentCurrent attribute.

Like any FrameSetFrameSet, 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 MappingMapping, 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 astClipastClip function. Nor does it support the specification of graphics primitive functions at run-time using the astGrfSetastGrfSet, astGrfPopastGrfPop, astGrfPushastGrfPush and astGetGrfContextastGetGrfContext functions. Constructor Function astPlot3DastPlot3D Inheritance The Plot3D class inherits from the Plot class. Attributes In addition to those attributes common to all Plots, every Plot3D also has the following attributes:

Norm: Normal vector defining the 2D plane used for text and markers

RootCornerRootCorner: 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, DrawTitleDrawTitle, TitleGapTitleGap, 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 " _XY" , " _XZ" or " _YZ" to the end of the Plot attribute name. For instance, " GridGrid_YZ" refers to the " Grid" attribute for the plane spanning the second (Y) and third (Z) axes of the 3-d plot. 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: astBoundingBoxastBoundingBox, astClip, astCurveastCurve, astGenCurveastGenCurve, astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, astGridLineastGridLine, astPolyCurveastPolyCurve. PointList A collection of points in a Frame The PointList class implements a RegionRegion which represents a collection of points in a FrameFrame. Constructor Function astPointListastPointList Inheritance The PointList class inherits from the Region class. Attributes In addition to those attributes common to all Regions, every PointList also has the following attributes:

ListSizeListSize: The number of positions stored in the PointList Functions The PointList class does not define any new functions beyond those which are applicable to all Regions. PolyMap Map coordinates using polynomial functions A PolyMap is a form of MappingMapping which performs a general polynomial transformation. Each output coordinate is a polynomial function of all the input coordinates. The coefficients are specified separately for each output coordinate. The forward and inverse transformations are defined independantly by separate sets of coefficients. If no inverse transformation is supplied, the default behaviour is to use an iterative method to evaluate the inverse based only on the forward transformation (see attribute IterInverseIterInverse). Constructor Function astPolyMapastPolyMap Inheritance The PolyMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every PolyMap also has the following attributes:

IterInverseIterInverse: Provide an iterative inverse transformation?

NiterInverseNiterInverse: Maximum number of iterations for iterative inverse

TolInverseTolInverse: Target relative error for iterative inverse Functions In addition to those functions applicable to all Objects, the following functions may also be applied to all Mappings:

astPolyCoeffsastPolyCoeffs: Retrieve the coefficients of a PolyMap transformation

astPolyTranastPolyTran: Fit a PolyMap inverse or forward transformation Polygon A polygonal region within a 2-dimensional Frame The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional FrameFrame. 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 SkyFrameSkyFrame then the geodesics will be great circles. Note, for a basic Frame 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, assuming the Frame axes are displayed in the usual right-handed coordinate convention - X axis (axis 1) points to the right and the Y axis (axis 2) points upwards. 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). Constructor Function astPolygonastPolygon Inheritance The Polygon class inherits from the RegionRegion class. Attributes In addition to those attributes common to all Regions, every Polygon also has the following attributes: SimpVerticesSimpVertices: Simplify by transforming the vertices? Functions In addition to those functions applicable to all Regions, the following functions may also be applied to all Polygons:

astDownsizeastDownsize: Reduce the number of vertices in a Polygon.

astConvex1#1X2#2astConvex1#1X2#2: Create a Polygon giving the convex hull of a pixel array

astOutline1#1X2#2astOutline1#1X2#2: Create a Polygon outlining values in a pixel array Prism An extrusion of a region into higher dimensions A Prism is a RegionRegion 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 (M241#241N) 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 CircleCircle, using an IntervalInterval 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. Constructor Function astPrismastPrism Inheritance The Prism class inherits from the Region class. Attributes The Prism class does not define any new attributes beyond those which are applicable to all Regions. Functions The Prism class does not define any new functions beyond those which are applicable to all Regions. RateMap Mapping which represents differentiation A RateMap is a MappingMapping 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 " encapsulated Mapping" 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. Constructor Function astRateMapastRateMap Inheritance The RateMap class inherits from the Mapping class. Attributes The RateMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The RateMap class does not define any new functions beyond those which are applicable to all Mappings. Region Represents a region within a coordinate system 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 CircleCircle, BoxBox, etc, which implement Regions with particular shapes.

All sub-classes of Region require a FrameFrame 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 " encapsulated Frame" 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 astFormatastFormat function may be used on a Region to format an axis value.

In addition, since Frame inherits from MappingMapping, a Region is also a sort of Mapping. Transforming positions by supplying a Region to one of the astTran1#1X2#2 functions is the way to determine if a given position is inside or outside the Region (but see also the convenience function astPointInRegionastPointInRegion). When used as a Mapping, most classes of Frame are equivalent to a UnitMapUnitMap. 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 " inverse transformation" 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 astRemoveRegionsastRemoveRegions function can be used to remove the " masking" effect of any Regions contained within a compound Mapping or FrameSetFrameSet. 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' s say a Circle (a subclass of Region) is created, a SkyFrameSkyFrame 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 SystemSystem attribute and this attribute will be set to " FK4" . 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 astSimplifyastSimplify 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. Constructor Function None. Inheritance The Region class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every Region also has the following attributes:

AdaptiveAdaptive: Should the area adapt to changes in the coordinate system?

NegatedNegated: Has the original region been negated?

ClosedClosed: Should the boundary be considered to be inside the region?

MeshSizeMeshSize: Number of points used to create a mesh covering the Region

FillFactorFillFactor: Fraction of the Region which is of interest

BoundedBounded: Is the Region bounded?

Every Region also inherits any further attributes that belong to the encapsulated Frame, regardless of that Frame' s class. (For example, the EquinoxEquinox attribute, defined by the SkyFrame class, is inherited by any Region which represents a SkyFrame.) Functions In addition to those functions applicable to all Frames, the following functions may also be applied to all Regions:

astGetRegionBoundsastGetRegionBounds: Get the bounds of a box containing a Region

astGetRegionFrameastGetRegionFrame: Get a copy of the Frame represent by a Region

astGetRegionFrameSetastGetRegionFrameSet: Get a copy of the Frameset encapsulated by a Region

astGetRegionMeshastGetRegionMesh: Get a mesh of points covering a Region

astGetRegionPointsastGetRegionPoints: Get the positions that define a Region

astGetUncastGetUnc: Obtain uncertainty information from a Region

astGetRegionDiscastGetRegionDisc: Get the bounds of disc containing a Region

astMapRegionastMapRegion: Transform a Region into a new coordinate system

astNegateastNegate: Toggle the value of the Negated attribute

astOverlapastOverlap: Determines the nature of the overlap between two Regions

astPointInRegionastPointInRegion: Test if a single point is inside a Region

astMask1#1X2#2astMask1#1X2#2: Mask a region of a data grid

astSetUncastSetUnc: Associate a new uncertainty with a Region

astShowMeshastShowMesh: Display a mesh of points on the surface of a Region SelectorMap A Mapping that locates positions within one of a set of alternate Regions A SelectorMap is a MappingMapping that identifies which RegionRegion 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 FrameFrame. The number of inputs (NinNin 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 UnitMapUnitMap when the compound Mapping is simplified using astSimplifyastSimplify.

In practice, SelectorMaps are often used in conjunction with SwitchMaps. Constructor Function astSelectorMapastSelectorMap Inheritance The SelectorMap class inherits from the Mapping class. Attributes The SelectorMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The SelectorMap class does not define any new functions beyond those which are applicable to all Mappings. ShiftMap Add a constant value to each coordinate A ShiftMap is a linear MappingMapping which shifts each axis by a specified constant value. Constructor Function astShiftMapastShiftMap Inheritance The ShiftMap class inherits from the Mapping class. Attributes The ShiftMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The ShiftMap class does not define any new functions beyond those which are applicable to all Mappings. SkyAxis Store celestial axis information The SkyAxis class is used to store information associated with a particular axis of a SkyFrameSkyFrame. It is used internally by the AST library and has no constructor function. You should encounter it only within textual output (e.g. from astWriteastWrite). Constructor Function None. Inheritance The SkyAxis class inherits from the AxisAxis class. SkyFrame Celestial coordinate system description A SkyFrame is a specialised form of FrameFrame which describes celestial longitude/latitude coordinate systems. The particular celestial coordinate system to be represented is specified by setting the SkyFrame' s SystemSystem attribute (currently, the default is ICRS) qualified, as necessary, by a mean EquinoxEquinox value and/or an EpochEpoch.

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, SkyRefIsSkyRefIs, SkyRefP and AlignOffsetAlignOffset.

All the coordinate values used by a SkyFrame are in radians. These may be formatted in more conventional ways for display by using astFormatastFormat. For a SkyFrame, the Unit attribute describes the formatted value of a SkyFrame axis, and may for instance be " h:m:s" , 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 " rad" (i.e. radians), indicating that the unformatted (i.e. floating point) axis values used by application code are always in units of radians Constructor Function astSkyFrameastSkyFrame Inheritance The SkyFrame class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every SkyFrame also has the following attributes:

AlignOffsetAlignOffset: Align SkyFrames using the offset coordinate system?

AsTime(axis)AsTime(axis): Format celestial coordinates as times?

EquinoxEquinox: Epoch of the mean equinox

IsLatAxis: Is the specified axis the latitude axis?

IsLonAxis: Is the specified axis the longitude axis?

LatAxisLatAxis: Index of the latitude axis

LonAxisLonAxis: Index of the longitude axis

NegLonNegLon: Display longitude values in the range [-pi,pi]?

ProjectionProjection: Sky projection description.

SkyRef: Position defining location of the offset coordinate system

SkyRefIsSkyRefIs: Selects the nature of the offset coordinate system

SkyRefP: Position defining orientation of the offset coordinate system

SkyTolSkyTol: Smallest significant shift in sky coordinates Functions In addition to those functions applicable to all Frames, the following functions may also be applied to all SkyFrames:

astSkyOffsetMapastSkyOffsetMap: Obtain a MappingMapping from absolute to offset coordinates SlaMap Sequence of celestial coordinate conversions An SlaMap is a specialised form of MappingMapping 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 astSlaAddastSlaAdd 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. Constructor Function astSlaMapastSlaMap (also see astSlaAdd) Inheritance The SlaMap class inherits from the Mapping class. Attributes The SlaMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions In addition to those functions applicable to all Mappings, the following function may also be applied to all SlaMaps:

astSlaAddastSlaAdd: Add a celestial coordinate conversion to an SlaMap SpecFluxFrame Compound spectrum/flux Frame A SpecFluxFrame combines a SpecFrameSpecFrame and a FluxFrameFluxFrame into a single 2-dimensional compound FrameFrame. Such a Frame can for instance be used to describe a PlotPlot of a spectrum in which the first axis represents spectral position and the second axis represents flux. Constructor Function astSpecFluxFrameastSpecFluxFrame Inheritance The SpecFluxFrame class inherits from the CmpFrameCmpFrame class. 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 " StdOfRestStdOfRest" 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. Functions The SpecFluxFrame class does not define any new functions beyond those which are applicable to all CmpFrames. SpecFrame Spectral coordinate system description A SpecFrame is a specialised form of one-dimensional FrameFrame 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' s SystemSystem 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 SpecOriginSpecOrigin attribute, a SpecFrame can be made to represent offsets from a given spectral position, rather than absolute spectral values. Constructor Function astSpecFrameastSpecFrame Inheritance The SpecFrame class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every SpecFrame also has the following attributes:

AlignSpecOffsetAlignSpecOffset: Align SpecFrames using the offset coordinate system?

AlignStdOfRestAlignStdOfRest: Standard of rest in which to align SpecFrames

RefDecRefDec: Declination of the source (FK5 J2000)

RefRARefRA: Right ascension of the source (FK5 J2000)

RestFreqRestFreq: Rest frequency

SourceSysSourceSys: Source velocity spectral system

SourceVelSourceVel: Source velocity

SourceVRFSourceVRF: Source velocity rest frame

SpecOriginSpecOrigin: The zero point for SpecFrame axis values

StdOfRestStdOfRest: Standard of rest

Several of the Frame attributes inherited by the SpecFrame class refer to a specific axis of the Frame (for instance Unit(axis)Unit(axis), 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, " Unit" is allowed in place of " Unit(1)" . Functions In addition to those functions applicable to all Frames, the following functions may also be applied to all SpecFrames:

astSetRefPosastSetRefPos: Set reference position in any celestial system

astGetRefPosastGetRefPos: Get reference position in any celestial system SpecMap Sequence of spectral coordinate conversions A SpecMap is a specialised form of MappingMapping 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 astSpecAddastSpecAdd 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. Constructor Function astSpecMapastSpecMap (also see astSpecAdd) Inheritance The SpecMap class inherits from the Mapping class. Attributes The SpecMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions In addition to those functions applicable to all Mappings, the following function may also be applied to all SpecMaps:

astSpecAddastSpecAdd: Add a spectral coordinate conversion to an SpecMap SphMap Map 3-d Cartesian to 2-d spherical coordinates A SphMap is a MappingMapping 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). Constructor Function astSphMapastSphMap Inheritance The SphMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every SphMap also has the following attributes:

UnitRadiusUnitRadius: SphMap input vectors lie on a unit sphere?

PolarLongPolarLong: The longitude value to assign to either pole Functions The SphMap class does not define any new functions beyond those which are applicable to all Mappings. SplineMap Map coordinates using spline functions A SplineMap is a class of MappingMapping that has two input axes and two output axes and contains a pair of two-dimensional splines (stored in B-spline form). Each output coordinate of a SplineMap is the value of one of these two-dimensional splines defined over the two input coordinates. The two splines (one generating the first output coordinate and the other generating the second output coordinate) share the same order and the same knot positions, but have coefficients that are specified separately. No extrapolation is performed - input positions that are outside the area covered by the supplied knots cannot be transformed (but see attribute OutUnitOutUnit).

An iterative method is used to evaluate the inverse transformation based on the forward transformation (see attributes InvTolInvTol and InvNiterInvNiter). This puts some restrictions on how the SplineMap class is used. Specifically, the output axis values must represent perturbed input axis values, rather than representing the perturbations themselves. It also requires that the perturbations be small. In other words, if the input axis values are (x,y), the output axis values are (u,v) and the perturbations in u and v are Pu(x,y) and Pv(x,y), then:

u = x 241#241 Pu(x,y)

v = y 241#241 Pv(x,y)

The perturbations should be sufficiently small to ensure that u always increases with x and that v always increases with y. The knots and coefficients of the B-splines supplied when the SplineMap is constructed should ensure that each B-spline value represents the sum of the input axis value and the perturbation. For instance, the first supplied B-spline should have value x 241#241 Pu(x,y) and not just Pu(x,y). Constructor Function astSplineMapastSplineMap Inheritance The SplineMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every SplineMap also has the following attributes:

InvNiterInvNiter: Maximum number of iterations for iterative inverse

InvTolInvTol: Target relative error for iterative inverse

OutUnitOutUnit: Determines how out-of-bounds input positions are handled.

SplineKxSplineKx: The order of the splines along the input X axis.

SplineKySplineKy: The order of the splines along the input Y axis.

SplineNxSplineNx: The number of spline coefficients along the input X axis.

SplineNySplineNy: The number of spline coefficients along the input Y axis. Functions In addition to those functions applicable to all Mappings, the following functions may also be applied to all SplineMaps:

astSplineKnotsastSplineKnots: Retrieve the knots of a SplineMap

astSplineCoeffsastSplineCoeffs: Retrieve the coefficients of a SplineMap Stc Represents an instance of the IVOA STC class 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/309#309arots/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 StcCatalogEntryLocationStcCatalogEntryLocation, StcResourceProfileStcResourceProfile, StcSearchLocationStcSearchLocation and StcObsDataLocationStcObsDataLocation. Constructor Function astStc Inheritance The Stc class inherits from the RegionRegion class. Attributes In addition to those attributes common to all Regions, every Stc also has the following attributes:

RegionClassRegionClass: The class name of the encapsulated Region. Functions In addition to those functions applicable to all Regions, the following functions may also be applied to all Stc' s:

astGetStcRegionastGetStcRegion: Get a pointer to the encapsulated Region

astGetStcCoordastGetStcCoord: Get information about an AstroCoords element

astGetStcNCoordastGetStcNCoord: Returns the number of AstroCoords elements in an Stc StcCatalogEntryLocation Correspond to the IVOA STCCatalogEntryLocation class The StcCatalogEntryLocation class is a sub-class of StcStc used to describe the coverage of the datasets contained in some VO resource.

See http://hea-www.harvard.edu/309#309arots/nvometa/STC.html Constructor Function astStcCatalogEntryLocationastStcCatalogEntryLocation Inheritance The StcCatalogEntryLocation class inherits from the Stc class. Attributes The StcCatalogEntryLocation class does not define any new attributes beyond those which are applicable to all Stcs. Functions The StcCatalogEntryLocation class does not define any new functions beyond those which are applicable to all Stcs. StcObsDataLocation Correspond to the IVOA ObsDataLocation class The StcObsDataLocation class is a sub-class of StcStc used to describe the coordinate space occupied by a particular observational dataset.

See http://hea-www.harvard.edu/309#309arots/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 FrameFrame 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 ObsLonObsLon and ObsLatObsLat attributes of the Frame encapsulated within the Stc representing the observation location (this assumes the observatory is located at sea level). Constructor Function astStcObsDataLocationastStcObsDataLocation Inheritance The StcObsDataLocation class inherits from the Stc class. Attributes The StcObsDataLocation class does not define any new attributes beyond those which are applicable to all Stcs. Functions The StcObsDataLocation class does not define any new functions beyond those which are applicable to all Stcs. StcResourceProfile Correspond to the IVOA STCResourceProfile class The StcResourceProfile class is a sub-class of StcStc used to describe the coverage of the datasets contained in some VO resource.

See http://hea-www.harvard.edu/309#309arots/nvometa/STC.html Constructor Function astStcResourceProfileastStcResourceProfile Inheritance The StcResourceProfile class inherits from the Stc class. Attributes The StcResourceProfile class does not define any new attributes beyond those which are applicable to all Stcs. Functions The StcResourceProfile class does not define any new functions beyond those which are applicable to all Stcs. StcSearchLocation Correspond to the IVOA SearchLocation class The StcSearchLocation class is a sub-class of StcStc used to describe the coverage of a query.

See http://hea-www.harvard.edu/309#309arots/nvometa/STC.html Constructor Function astStcSearchLocationastStcSearchLocation Inheritance The StcSearchLocation class inherits from the Stc class. Attributes The StcSearchLocation class does not define any new attributes beyond those which are applicable to all Stcs. Functions The StcSearchLocation class does not define any new functions beyond those which are applicable to all Stcs. StcsChan I/O Channel using STC-S to represent Objects A StcsChan is a specialised form of ChannelChannel which supports STC-S I/O operations. Writing an ObjectObject to an StcsChan (using astWriteastWrite) 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 astReadastRead, the returned AST Object may be 1) a PointListPointList describing the STC AstroCoords (i.e. a single point of interest within the coordinate frame described by the STC-S description), or 2) a RegionRegion 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 KeyMapKeyMap 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 StcsAreaStcsArea, StcsCoordsStcsCoords and StcsPropsStcsProps 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 " AREA" , holding a Region to be used to define the AstroCoordsArea. It may also contain an entry with the key " COORDS" , holding a Region (a PointList) to be used to create the AstroCoords. It may also contain an entry with key " PROPS" , 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 " PROPS" 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 " source" and " sink" 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 XmlChanXmlChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied.

Support for STC-S is currently based on the IVOA document " STC-S: Space-Time Coordinate (STC) Metadata Linear String Implementation" , 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:

When reading an STC-S phrase, case is ignored except when reading units strings.

There is no support for multiple intervals specified within a TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval.

If the ET timescale is specified, TT is used instead.

If the TEB timescale is specified, TDB is used instead.

The LOCAL timescale is not supported.

The AST TimeFrameTimeFrame and SkyFrameSkyFrame classes do not currently allow a reference position to be specified. Consequently, any 1#1refpos2#2 specified within the Time or Space sub-phrase of an STC-S document is ignored.

The Convex identifier for the space sub-phrase is not supported.

The GEO_C and GEO_D space frames are not supported.

The UNITSPHERE and SPHER3 space flavours are not supported.

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).

The spectral and redshift sub-phrases do not support the following 1#1refpos2#2 values: LOCAL_GROUP_CENTER, UNKNOWNRefPos, EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO.

Error values are supported but error ranges are not.

Resolution, PixSize and Size values are ignored.

Space velocity sub-phrases are ignored. Constructor Function astStcsChanastStcsChan Inheritance The StcsChan class inherits from the Channel class. Attributes In addition to those attributes common to all Channels, every StcsChan also has the following attributes:

StcsAreaStcsArea: Return the CoordinateArea component after reading an STC-S?

StcsCoordsStcsCoords: Return the Coordinates component after reading an STC-S?

StcsLengthStcsLength: Controls output buffer length

StcsPropsStcsProps: Return the STC-S properties after reading an STC-S? Functions The StcsChan class does not define any new functions beyond those which are applicable to all Channels. SwitchMap A Mapping that encapsulates a set of alternate Mappings A SwitchMap is a MappingMapping 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 (NinNin attribute value) and the same number of outputs (NoutNout attribute value). The SwitchMap itself inherits these same values for its Nin and Nout attributes. Each of these Mappings represents a " route" through the switch, and are referred to as " route" 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 " selector" Mapping. Each SwitchMap encapsulates two selector Mappings in addition to its route Mappings; one for use with the SwitchMap' s forward transformation (called the " forward selector Mapping" ), and one for use with the SwitchMap' s inverse transformation (called the " inverse selector Mapping" ). 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 " output" to " input" ), each supplied " output" position is first transformed by the inverse transformation of the inverse selector Mapping. This produces a selector value for each " output" 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 " output" position to produce the SwitchMap " input" position. If the selector index value is outside the bounds of the array of route Mappings, then the SwitchMap " input" 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 SelectorMapSelectorMap 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 UnitMapUnitMap when the compound Mapping is simplified using astSimplifyastSimplify. Constructor Function astSwitchMapastSwitchMap Inheritance The SwitchMap class inherits from the Mapping class. Attributes The SwitchMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The SwitchMap class does not define any new functions beyond those which are applicable to all Mappings. Table A 2-dimensional table of values The Table class is a type of KeyMapKeyMap 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 " 1#1COL2#2(i)" where " 1#1COL2#2" is the upper-case name of a table column and " i" 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 astAddColumnastAddColumn 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 astAddParameterastAddParameter 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. Constructor Function astTableastTable Inheritance The Table class inherits from the KeyMap class. Attributes In addition to those attributes common to all KeyMaps, every Table also has the following attributes:

ColumnLenC(column)ColumnLenC(column): The largest string length of any value in a column

ColumnLength(column)ColumnLength(column): The number of elements in each value in a column

ColumnNdim(column)ColumnNdim(column): The number of axes spanned by each value in a column

ColumnType(column)ColumnType(column): The data type of each value in a column

ColumnUnit(column): The unit string describing each value in a column

NcolumnNcolumn: The number of columns currently in the Table

NrowNrow: The number of rows currently in the Table

NparameterNparameter: The number of global parameters currently in the Table Functions In addition to those functions applicable to all KeyMaps, the following functions may also be applied to all Tables:

astAddColumnastAddColumn: Add a new column definition to a Table

astAddParameterastAddParameter: Add a new global parameter definition to a Table

astColumnNameastColumnName: Return the name of the column with a given index

astColumnShapeastColumnShape: Return the shape of the values in a named column

astHasColumnastHasColumn: Checks if a column exists in a Table

astHasParameterastHasParameter: Checks if a global parameter exists in a Table

astParameterNameastParameterName: Return the name of the parameter with a given index

astPurgeRowsastPurgeRows: Remove all empty rows from a Table

astRemoveColumnastRemoveColumn: Remove a column from a Table

astRemoveParameterastRemoveParameter: Remove a global parameter from a Table

astRemoveRowastRemoveRow: Remove a row from a Table TimeFrame Time coordinate system description A TimeFrame is a specialised form of one-dimensional FrameFrame 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 SystemSystem attribute. Optionally, a zero point can be specified (using attribute TimeOriginTimeOrigin) 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 TimeScaleTimeScale 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 " TT" (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). Constructor Function astTimeFrameastTimeFrame Inheritance The TimeFrame class inherits from the Frame class. Attributes In addition to those attributes common to all Frames, every TimeFrame also has the following attributes:

AlignTimeScaleAlignTimeScale: Time scale in which to align TimeFrames

LTOffsetLTOffset: The offset of Local Time from UTC, in hours.

TimeOriginTimeOrigin: The zero point for TimeFrame axis values

TimeScaleTimeScale: 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 Unit(axis)Unit(axis), 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, " Unit" is allowed in place of " Unit(1)" . Functions In addition to those functions applicable to all Frames, the following functions may also be applied to all TimeFrames:

astCurrentTimeastCurrentTime: Return the current system time TimeMap Sequence of time coordinate conversions A TimeMap is a specialised form of 1-dimensional MappingMapping 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 astTimeAddastTimeAdd 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. Constructor Function astTimeMapastTimeMap (also see astTimeAdd) Inheritance The TimeMap class inherits from the Mapping class. Attributes The TimeMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions In addition to those functions applicable to all Mappings, the following function may also be applied to all TimeMaps:

astTimeAddastTimeAdd: Add a time coordinate conversion to an TimeMap TranMap Mapping with specified forward and inverse transformations A TranMap is a MappingMapping 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. Constructor Function astTranMapastTranMap Inheritance The TranMap class inherits from the Mapping class. Attributes The TranMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The TranMap class does not define any new functions beyond those which are applicable to all Mappings. UnitMap Unit (null) Mapping A UnitMap is a unit (null) MappingMapping 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 NinNin and NoutNout attributes of a UnitMap are always equal and are specified when it is created. Constructor Function astUnitMapastUnitMap Inheritance The UnitMap class inherits from the Mapping class. Attributes The UnitMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The UnitMap class does not define any new functions beyond those which are applicable to all Mappings. UnitNormMap Convert a vector to a unit vector and its norm, relative to a specified centre 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 NinNin outputs are in the same order as the input; the final output is the norm. If the norm is 0, then the output of the forward transformation is AST__BAD for each component of the unit vector and 0 for the norm (the final value).

The inverse transformation of a UnitNormMap multiplies each component of the provided vector by the provided norm and adds the specified centre. The output contains one fewer coordinate than the input: the initial Nin inputs are in the same order as the output; the final input is the norm. If the provided norm is 0 then the other input values are ignored, and the output vector is the centre.

Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre; the norm is 5, so the output is [0.8, 0.6, 5].

UnitNormMap enables radially symmetric transformations, as follows: apply a UnitNormMap to produce a unit vector and norm (radius)

apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged

apply the same UnitNormMap in the inverse direction to produce the result Constructor Function astUnitNormMapastUnitNormMap Inheritance The UnitNormMap class inherits from the MappingMapping class. Attributes The UnitNormMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The UnitNormMap class does not define any new functions beyond those which are applicable to all Mappings. WcsMap Implement a FITS-WCS sky projection This class is used to represent sky coordinate projections as described in the FITS world coordinate system (FITS-WCS) paper II " Representations of Celestial Coordinates in FITS" 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 MappingMapping 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 " TAN with polynomial correction terms" projection which is refered to here by the code " TPN" . Using the FITS-WCS terminology, the transformation is between " native spherical" and " projection plane" coordinates (also called " intermediate world 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 WcsTypeWcsType attribute and the coordinates on which it acts may be determined using the WcsAxis(lonlat)WcsAxis(lonlat) attribute.

Each WcsMap also allows up to 100 " projection parameters" to be associated with each axis. These specify the precise form of the projection, and are accessed using PVi_mPVi_m attribute, where " i" is the integer axis index (starting at 1), and m is an integer " parameter index" 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. Constructor Function astWcsMapastWcsMap Inheritance The WcsMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every WcsMap also has the following attributes:

NatLatNatLat: Native latitude of the reference point of a FITS-WCS projection

NatLonNatLon: Native longitude of the reference point of a FITS-WCS projection

PVi_mPVi_m: FITS-WCS projection parameters

PVMax: Maximum number of FITS-WCS projection parameters

WcsAxis(lonlat)WcsAxis(lonlat): FITS-WCS projection axes

WcsTypeWcsType: FITS-WCS projection type Functions The WcsMap class does not define any new functions beyond those which are applicable to all Mappings. WinMap Map one window on to another by scaling and shifting each axis A Winmap is a linear MappingMapping 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. Constructor Function astWinMapastWinMap Inheritance The WinMap class inherits from the Mapping class. Attributes The WinMap class does not define any new attributes beyond those which are applicable to all Mappings. Functions The WinMap class does not define any new functions beyond those which are applicable to all Mappings. XmlChan I/O Channel using XML to represent Objects A XmlChan is a specialised form of ChannelChannel which supports XML I/O operations. Writing an ObjectObject to an XmlChan (using astWriteastWrite) 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 " source" and " sink" 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 SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Constructor Function astXmlChanastXmlChan Inheritance The XmlChan class inherits from the Channel class. Attributes In addition to those attributes common to all Channels, every XmlChan also has the following attributes:

XmlFormatXmlFormat: SystemSystem for formatting Objects as XML

XmlLengthXmlLength: Controls output buffer length

XmlPrefixXmlPrefix: The namespace prefix to use when writing Functions The XmlChan class does not define any new functions beyond those which are applicable to all Mappings. YamlChan I/O Channel that uses YAML to represent Objects A YamlChan is a specialised form of ChannelChannel which supports YAML I/O operations. Writing an ObjectObject to a YamlChan (using astWriteastWrite) will, if the Object is suitable, generate an YAML description of that Object, and reading from a YamlChan will create a new Object from its YAML description.

YAML itself does not define a way to store coordinate systems or transformations - such definitions must be provided by a suitable WCS-oriented schema. The scheme to use is defined by the YamlEncodingYamlEncoding attribute. Currently, the only schema supported by this class is " ASDF" , defined by the Space Telescope Science Institute. (see http://asdf-standard.readthedocs.io). At some point in the future support will be added for the AST NATIVE scheme.

Normally, when you use a YamlChan, you should provide " source" and " sink" 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, a YamlChan can be told to read or write from specific text files using the SinkFileSinkFile and SourceFileSourceFile attributes, in which case no sink or source function need be supplied. Constructor Function astYamlChanastYamlChan This class uses the limyaml library to read and write yaml. If the libyaml library cannot be found when the AST library is configured, then an error will be reported if any YamlChan methods are invoked. Inheritance The YamlChan class inherits from the Channel class. Attributes In addition to those attributes common to all Channels, every YamlChan also has the following attributes:

VerboseReadVerboseRead: Echo YAML text to standard output as it is read?

PreserveNamePreserveName: Save the ASDF name attributes as AST IdentIdent values?

YamlEncodingYamlEncoding: The external formatting system to use. Functions The YamlChan class does not define any new functions beyond those which are applicable to all Channels. ZoomMap Zoom coordinates about the origin The ZoomMap class implements a MappingMapping which performs a " zoom" 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. Constructor Function astZoomMapastZoomMap Inheritance The ZoomMap class inherits from the Mapping class. Attributes In addition to those attributes common to all Mappings, every ZoomMap also has the following attributes:

ZoomZoom: ZoomMap scale factor Functions The ZoomMap class does not define any new functions beyond those which are applicable to all Mappings.