_link11_adam AST<BR>A Library for Handling<BR>World Coordinate Systems<BR>in Astronomy

SUN/211.30

Starlink Project
Starlink User Note 211.30

R.F. Warren-Smith & D.S. Berry

6th Jan 2022

Copyright (C) 2021 East Asian Observatory

AST
A Library for Handling
World Coordinate Systems
in Astronomy

V9.2

Programmer’s Guide
(C Version)

pdfpict       pdfpict       pdfpict

Abstract

The AST library provides a comprehensive range of facilities for attaching world coordinate systems to astronomical data, for retrieving and interpreting that information in a variety of formats, including FITS-WCS, and for generating graphical output based on it.

This programmer’s manual should be of interest to anyone writing astronomical applications which need to manipulate coordinate system data, especially celestial or spectral coordinate systems. AST is portable and environment-independent.

Contents

1 Introduction
 1.1 What Problems Does AST Tackle?
 1.2 Other Design Objectives
 1.3 What Does “AST” Stand For?
2 Overview of AST Concepts
 2.1 Relationships Between Coordinate Systems
 2.2 Mappings Available
 2.3 Compound Mappings
 2.4 Representing Coordinate Systems
 2.5 Networks of Coordinate Systems
 2.6 Input/Output Facilities
 2.7 Producing Graphical Output
3 How To…
 3.1 …Obtain and Install AST
 3.2 …Structure an AST Program
 3.3 …Build an AST Program
 3.4 …Read a WCS Calibration from a Dataset
 3.5 …Validate WCS Information
 3.6 …Display AST Data
 3.7 …Convert Between Pixel and World Coordinates
 3.8 …Test if a WCS is a Celestial Coordinate System
 3.9 …Test if a WCS is a Spectral Coordinate System
 3.10 …Format Coordinates for Display
 3.11 …Display Coordinates as they are Transformed
 3.12 …Read Coordinates Entered by a User
 3.13 …Create a New WCS Calibration
 3.14 …Modify a WCS Calibration
 3.15 …Write a Modified WCS Calibration to a Dataset
 3.16 …Display a Graphical Coordinate Grid
 3.17 …Switch to Plot a Different Celestial Coordinate Grid
 3.18 …Give a User Control Over the Appearance of a Plot
4 An AST Object Primer
 4.1 AST Objects
 4.2 Object Creation and Pointers
 4.3 The Object Hierarchy
 4.4 Displaying Objects
 4.5 Getting Attribute Values
 4.6 Setting Attribute Values
 4.7 Testing, Clearing and Defaulting Attributes
 4.8 Transforming Coordinates
 4.9 Managing Object Pointers
 4.10 AST Pointer Contexts—Begin and End
 4.11 Exporting, Importing and Exempting AST Pointers
 4.12 AST Objects within Multi-threaded Applications
  4.12.1 Locking AST Objects for Exclusive Use
  4.12.2 AST Pointer Contexts
 4.13 Copying Objects
 4.14 C Pointer Types
 4.15 Error Detection
 4.16 Sharing the Error Status
5 Inter-Relating Coordinate Systems (Mappings)
 5.1 The Mapping Class
 5.2 The Mapping Model
 5.3 Changing Attributes of a Mapping
 5.4 Input and Output Coordinate Numbers
 5.5 Forward and Inverse Transformations
 5.6 Inverting Mappings
 5.7 Finding the Rate of Change of a Mapping Output
 5.8 Reporting Coordinate Transformations
 5.9 Handling Missing (Bad) Coordinate Values
 5.10 Example—the UnitMap
 5.11 Example—the PermMap
6 Compound Mappings (CmpMaps)
 6.1 Combining Mappings in Series
 6.2 Combining Mappings in Parallel
 6.3 The Component Mappings
 6.4 Creating More Complex Mappings
 6.5 Example—Transforming Between Two Calibrated Images
 6.6 Over-Complex Compound Mappings
 6.7 Simplifying Compound Mappings
7 Representing Coordinate Systems (Frames)
 7.1 The Frame Model
 7.2 Creating a Frame
 7.3 Using a Frame as a Mapping
 7.4 Frame Axis Attributes
 7.5 Frame Attributes
 7.6 Formatting Axis Values
 7.7 Normalising Frame Coordinates
 7.8 Reading Formatted Axis Values
 7.9 Permuting Frame Axes
 7.10 Selecting Frame Axes
 7.11 Calculating Distances, Angles and Offsets
 7.12 The Domain Attribute
 7.13 Conventions for Domain Names
 7.14 The Unit Attribute
  7.14.1 The Syntax for Unit Strings
  7.14.2 Side-effects of Changing the Unit attribute
8 Celestial Coordinate Systems (SkyFrames)
 8.1 The SkyFrame Model
 8.2 Creating a SkyFrame
 8.3 Specifying a Particular Celestial Coordinate System
 8.4 Attributes which Qualify Celestial Coordinate Systems
 8.5 Using Default SkyFrame Attributes
 8.6 Formatting Celestial Coordinates
 8.7 Reading Formatted Celestial Coordinates
 8.8 Representing Offsets from a Specified Sky Position
9 Spectral Coordinate Systems (SpecFrames)
 9.1 The SpecFrame Model
 9.2 Creating a SpecFrame
 9.3 Specifying a Particular Spectral Coordinate System
 9.4 Attributes which Qualify Spectral Coordinate Systems
 9.5 Using Default SpecFrame Attributes
 9.6 Creating Spectral Cubes
 9.7 Handling Dual-Sideband Spectra
  9.7.1 Aligning Dual-Sideband Spectra
10 Time Systems (TimeFrames)
 10.1 The TimeFrame Model
 10.2 Creating a TimeFrame
 10.3 Specifying a Particular Time System
 10.4 Attributes which Qualify Time Coordinate Systems
11 Compound Frames (CmpFrames)
 11.1 Creating a CmpFrame
 11.2 The Attributes of a CmpFrame
12 An Introduction to Coordinate System Conversions
 12.1 Converting between Celestial Coordinate Systems
 12.2 Converting between Spectral Coordinate Systems
 12.3 Converting between Time Coordinate Systems
 12.4 Handling SkyFrame Axis Permutations
 12.5 Converting Between Frames
 12.6 The Choice of Alignment System
13 Coordinate System Networks (FrameSets)
 13.1 The FrameSet Model
 13.2 Creating a FrameSet
 13.3 Adding New Frames to a FrameSet
 13.4 The Base and Current Frames
 13.5 Referring to the Base and Current Frames
 13.6 Using a FrameSet as a Mapping
 13.7 Extracting a Mapping from a FrameSet
 13.8 Using a FrameSet as a Frame
 13.9 Extracting a Frame from a FrameSet
 13.10 Removing a Frame from a FrameSet
14 Higher Level Operations on FrameSets
 14.1 Creating FrameSets with astConvert
 14.2 Converting between FrameSet Coordinate Systems
 14.3 Example—Registering Two Images
 14.4 Re-Defining a FrameSet Coordinate System
 14.5 Example—Binning an Image
 14.6 Maintaining the Integrity of FrameSets
 14.7 Merging FrameSets
15 Saving and Restoring Objects (Channels)
 15.1 The Channel Model
 15.2 Creating a Channel
 15.3 Writing Objects to a Channel
 15.4 Reading Objects from a Channel
 15.5 Saving and Restoring Multiple Objects
 15.6 Validating Input
 15.7 Storing an ID String with an Object
 15.8 The Textual Output Format
 15.9 Controlling the Amount of Output
 15.10 Controlling Commenting
 15.11 Editing Textual Output
 15.12 Mixing Objects with other Text
 15.13 Reading Objects from Files
 15.14 Writing Objects to Files
 15.15 Reading and Writing Objects to other Places
16 Storing AST Objects in FITS Headers (FitsChans)
 16.1 The Native FITS Encoding
 16.2 The FitsChan Model
 16.3 Creating a FitsChan
 16.4 Addressing Cards in a FitsChan
 16.5 Writing Native Objects to a FitsChan
 16.6 Extracting Individual Cards from a FitsChan
 16.7 The Native FitsChan Output Format
 16.8 Adding Individual Cards to a FitsChan
 16.9 Adding Concatenated Cards to a FitsChan
 16.10 Reading Native Objects From a FitsChan
 16.11 Saving and Restoring Multiple Objects in a FitsChan
 16.12 Mixing Native Objects with Other FITS Cards
 16.13 Finding and Changing Cards in a FitsChan
 16.14 Source and Sink Functions for FitsChans
17 Using Foreign FITS Encodings
 17.1 The Foreign FITS Encodings
 17.2 Limitations of Foreign Encodings
 17.3 Identifying Foreign Encodings on Input
 17.4 Reading Foreign WCS Information from a FITS Header
 17.5 Removing WCS Information from FITS Headers—the Destructive Read
 17.6 Propagating WCS Information through Data Processing Steps
 17.7 Writing Foreign WCS Information to a FITS Header
18 Storing AST Objects as XML (XmlChan)
 18.1 Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions
19 Reading and writing STC-S descriptions (StcsChans)
20 Creating Your Own Private Mappings (IntraMaps)
 20.1 The Need for Extensibility
 20.2 The IntraMap Model
 20.3 Limitations of IntraMaps
 20.4 Writing a Transformation Function
 20.5 Registering a Transformation Function
 20.6 Creating an IntraMap
 20.7 Restricted Implementations of Transformation Functions
 20.8 Variable Numbers of Coordinates
 20.9 Adapting a Transformation Function to Individual IntraMaps
 20.10 Simplifying IntraMaps
 20.11 Writing and Reading IntraMaps
 20.12 Managing Transformation Functions in Libraries
21 Producing Graphical Output (Plots)
 21.1 The Plot Model
 21.2 Plotting Symbols
 21.3 Plotting Geodesic Curves
 21.4 Plotting Curves Parallel to Axes
 21.5 Plotting Generalized Curves
 21.6 Clipping
 21.7 Using a Plot as a Mapping
 21.8 Using a Plot as a Frame
 21.9 Regions of Valid Physical Coordinates
 21.10 Plotting Borders
 21.11 Plotting Text
 21.12 Plotting a Grid
 21.13 Controlling the Appearance of Sub-strings
 21.14 Producing Logarithmic Axes
 21.15 Choosing a Graphics Package
22 Compiling and Linking Software that Uses AST
 22.1 Accessing the “ast.h” Header File
 22.2 Linking with AST Facilities
 22.3 Building ADAM Applications that Use AST
A The AST Class Hierarchy
B AST Function Descriptions
astSet – Set attribute values for an Object
astActiveObjects – Return pointers for all active Objects
astAddCell – Adds a single HEALPix cell into an existing Moc
astAddColumn – Add a new column definition to a table
astAddFrame – Add a Frame to a FrameSet to define a new coordinate system
astAddMocData – Adds a FITS binary table into an existing Moc
astAddMocString – Adds a JSON or string-encoded MOC into an existing Moc
astAddParameter – Add a new global parameter definition to a table
astAddPixelMask <X > – Add a set of pixels to a Moc
astAddRegion – Add a Region into a Moc
astAddVariant – Store a new variant Mapping for the current Frame in a FrameSet
astAngle – Calculate the angle subtended by two points at a third point
astAnnul – Annul a pointer to an Object
astAxAngle – Returns the angle from an axis, to a line through two points
astAxDistance – Find the distance between two axis values
astAxNorm – Normalise an array of axis values
astAxOffset – Add an increment onto a supplied axis value
astBBuf – Begin a new graphical buffering context
astBegin – Begin a new AST context
astBorder – Draw a border around valid regions of a Plot
astBoundingBox – Return a bounding box for previously drawn graphics
astBox – Create a Box
astChannel – Create a Channel
astChannelData – Return a pointer to user-supplied data stored with a Channel
astChebyDomain – Returns the bounding box of the domain of a ChebyMap
astChebyMap – Create a ChebyMap
astCircle – Create a Circle
astCirclePars – Returns the geometric parameters of an Circle
astClear – Clear attribute values for an Object
astClearStatus – Clear the AST error status
astClip – Set up or remove clipping for a Plot
astClone – Clone (duplicate) an Object pointer
astCmpFrame – Create a CmpFrame
astCmpMap – Create a CmpMap
astCmpRegion – Create a CmpRegion
astColumnName – Get the name of the column at a given index within the Table
astColumnNull – Get or set the null value for an integer column of a FITS table
astColumnShape – Returns the shape of the values in a named column
astColumnSize – Get the number of bytes needed to hold a full column of data
astConvert – Determine how to convert between two coordinate systems
astConvex <X > – Create a new Polygon representing the convex hull of a 2D data grid
astCopy – Copy an Object
astCreatedAt – Return the routine, file and line number at which an Object was created
astCurrentTime – Return the current system time
astCurve – Draw a geodesic curve
astDSBSpecFrame – Create a DSBSpecFrame
astDecompose – Decompose a Mapping into two component Mappings
astDelFits – Delete the current FITS card in a FitsChan
astDelete – Delete an Object
astDistance – Calculate the distance between two points in a Frame
astDownsize – Reduce the number of vertices in a Polygon
astEBuf – End the current graphical buffering context
astEllipse – Create a Ellipse
astEllipsePars – Returns the geometric parameters of an Ellipse
astEmptyFits – Delete all cards in a FitsChan
astEnd – End an AST context
astEscapes – Control whether graphical escape sequences are included in strings
astExempt – Exempt an Object pointer from AST context handling
astExport – Export an Object pointer to an outer context
astFindFits – Find a FITS card in a FitsChan by keyword
astFindFrame – Find a coordinate system with specified characteristics
astFitsChan – Create a FitsChan
astFitsTable – Create a FitsTable
astFluxFrame – Create a FluxFrame
astFormat – Format a coordinate value for a Frame axis
astFrame – Create a Frame
astFrameSet – Create a FrameSet
astFromString – Re-create an Object from an in-memory serialisation
astGenCurve – Draw a generalized curve
astGet <X > – Get an attribute value for an Object
astGetActiveUnit – Determines how the Unit attribute will be used
astGetCell – Identify the next cell in a normalised Moc
astGetColumnData – Retrieve all the data values stored in a column
astGetFits <X > – Get a named keyword value from a FitsChan
astGetFrame – Obtain a pointer to a specified Frame in a FrameSet
astGetGrfContext – Return the KeyMap that describes a Plot’ s graphics context
astGetMapping – Obtain a Mapping that converts between two Frames in a FrameSet
astGetMocData – Get the FITS binary table data describing a Moc
astGetMocHeader – Get the FITS binary table headers describing a Moc
astGetMocString – Get the JSON or string-encoded representation of a Moc
astGetRefPos – Return the reference position in a specified celestial coordinate system
astGetRegionBounds – Returns the bounding box of Region
astGetRegionDisc – Returns the centre and radius of a disc containing a 2D Region
astGetRegionFrame – Obtain a pointer to the encapsulated Frame within a Region
astGetRegionFrameSet – Obtain a pointer to the encapsulated FrameSet within a Region
astGetRegionMesh – Return a mesh of points covering the surface or volume of a Region
astGetRegionPoints – Returns the positions that define the given Region
astGetStcCoord – Return information about an AstroCoords element stored in an Stc
astGetStcNCoord – Return the number of AstroCoords elements stored in an Stc
astGetStcRegion – Obtain a copy of the encapsulated Region within a Stc
astGetTableHeader – Get the FITS headers from a FitsTable
astGetTables – Retrieve any FitsTables currently in a FitsChan
astGetUnc – Obtain uncertainty information from a Region
astGrfPop – Restore previously saved graphics functions used by a Plot
astGrfPush – Save the current graphics functions used by a Plot
astGrfSet – Register a graphics function for use by a Plot
astGrid – Draw a set of labelled coordinate axes
astGridLine – Draw a grid line (or axis) for a Plot
astGrismMap – Create a GrismMap
astHasAttribute – Test if an Object has a named attribute
astHasColumn – Returns a flag indicating if a column is present in a Table
astHasParameter – Returns a flag indicating if a named global parameter is present in a Table
astImport – Import an Object pointer to the current context
astIntersect – Find the point of intersection between two geodesic curves
astInterval – Create a Interval
astIntraMap – Create an IntraMap
astIntraReg – Register a transformation function for use by an IntraMap
astInvert – Invert a Mapping
astIsA <Class > – Test membership of a class by an Object
astKeyMap – Create a KeyMap
astLinearApprox – Obtain a linear approximation to a Mapping, if appropriate
astLock – Lock an Object for exclusive use by the calling thread
astLutMap – Create a LutMap
astMapBox – Find a bounding box for a Mapping
astMapCopy – Copy all entries from one KeyMap into another
astMapCopyEntry – Copy a single entry from one KeyMap into another
astMapDefined – Check if a KeyMap contains a defined value for a key
astMapGet0 <X > – Get a scalar value from a KeyMap
astMapGet1 <X > – Get a vector value from a KeyMap
astMapGetC – Get a scalar or vector value from a KeyMap as a single string
astMapGetElem <X > – Get a single element of a vector value from a KeyMap
astMapHasKey – Check if an entry with a given key exists in a KeyMap
astMapKey – Get the key at a given index within the KeyMap
astMapLenC – Get the number of characters in a character entry in a KeyMap
astMapLength – Get the vector length of an entry in a KeyMap
astMapPut0 <X > – Add a scalar value to a KeyMap
astMapPut1 <X > – Add a vector value to a KeyMap
astMapPutElem <X > – Put a value into an element of a vector value in a KeyMap
astMapPutU – Add an entry to a KeyMap with an undefined value
astMapRegion – Transform a Region into a new Frame using a given Mapping
astMapRemove – Removed a named entry from a KeyMap
astMapRename – Rename an existing KeyMap entry
astMapSize – Get the number of entries in a KeyMap
astMapSplit – Split a Mapping up into parallel component Mappings
astMapType – Get the data type of an entry in a KeyMap
astMark – Draw a set of markers for a Plot
astMask <X > – Mask a region of a data grid
astMatchAxes – Find any corresponding axes in two Frames
astMathMap – Create a MathMap
astMatrixMap – Create a MatrixMap
astMirrorVariants – Make the current Frame mirror the variant Mappings in another Frame
astMoc – Create a Moc
astMocChan – Create a MocChan
astNegate – Negate the area represented by a Region
astNorm – Normalise a set of Frame coordinates representing one point
astNormMap – Create a NormMap
astNormPoints – Normalise a collection of points
astNullRegion – Create a NullRegion
astOK – Test whether AST functions have been successful
astOffset – Calculate an offset along a geodesic curve
astOffset2 – Calculate an offset along a geodesic curve in a 2D Frame
astOutline <X > – Create a new Polygon outling values in a 2D data grid
astOverlap – Test if two regions overlap each other
astParameterName – Get the name of the global parameter at a given index within the Table
astPcdMap – Create a PcdMap
astPermAxes – Permute the axis order in a Frame
astPermMap – Create a PermMap
astPickAxes – Create a new Frame by picking axes from an existing one
astPlot – Create a Plot
astPlot3D – Create a Plot3D
astPointInRegion – Tests if a single point is inside a Region
astPointList – Create a PointList
astPolyCoeffs – Retrieve the coefficient values used by a PolyMap
astPolyCurve – Draw a series of connected geodesic curves
astPolyMap – Create a PolyMap
astPolyTran – Fit a PolyMap inverse or forward transformation
astPolygon – Create a Polygon
astPrism – Create a Prism
astPurgeRows – Remove all empty rows from a table
astPurgeWCS – Delete all cards in the FitsChan describing WCS information
astPutCards – Store a set of FITS header cards in a FitsChan
astPutChannelData – Store arbitrary data to be passed to a source or sink function
astPutColumnData – Store new data values for all rows of a column
astPutFits – Store a FITS header card in a FitsChan
astPutTable – Store a single FitsTable in a FitsChan
astPutTableHeader – Store new FITS headers in a FitsTable
astPutTables – Store one or more FitsTables in a FitsChan
astQuadApprox – Obtain a quadratic approximation to a 2D Mapping
astRate – Calculate the rate of change of a Mapping output
astRateMap – Create a RateMap
astRead – Read an Object from a Channel
astReadFits – Read cards into a FitsChan from the source function
astRebin <X > – Rebin a region of a data grid
astRebinSeq <X > – Rebin a region of a sequence of data grids
astRegionOutline – Draw the outline of an AST Region
astRemapFrame – Modify a Frame’ s relationship to other Frames in a FrameSet
astRemoveColumn – Remove a column from a table
astRemoveFrame – Remove a Frame from a FrameSet
astRemoveParameter – Remove a global parameter from a table
astRemoveRegions – Remove any Regions from a Mapping
astRemoveRow – Remove a row from a table
astRemoveTables – Remove one or more tables from a FitsChan
astResample <X > – Resample a region of a data grid
astResolve – Resolve a vector into two orthogonal components
astRetainFits – Indicate that the current card in a FitsChan should be retained
astSame – Test if two AST pointers refer to the same Object
astSelectorMap – Create a SelectorMap
astSet – Set attribute values for an Object
astSet <X > – Set an attribute value for an Object
astSetActiveUnit – Specify how the Unit attribute should be used
astSetFits <X > – Store a keyword value in a FitsChan
astSetFitsCM – Store a comment card in a FitsChan
astSetFitsU – Store an undefined keyword value in a FitsChan
astSetPutErr – Register an error handling function for use by the AST error model
astSetRefPos – Set the reference position in a specified celestial coordinate system
astSetStatus – Set the AST error status to an explicit value
astSetUnc – Store uncertainty information in a Region
astShiftMap – Create a ShiftMap
astShow – Display a textual representation of an Object on standard output
astShowFits – Display the contents of a FitsChan on standard output
astShowMesh – Display a mesh of points covering the surface of a Region
astSimplify – Simplify a Mapping
astSkyFrame – Create a SkyFrame
astSkyOffsetMap – Returns a Mapping which goes from absolute coordinates to offset coordinates
astSlaAdd – Add a celestial coordinate conversion to an SlaMap
astSlaMap – Create an SlaMap
astSpecAdd – Add a spectral coordinate conversion to a SpecMap
astSpecFluxFrame – Create a SpecFluxFrame
astSpecFrame – Create a SpecFrame
astSpecMap – Create a SpecMap
astSphMap – Create a SphMap
astStatus – Obtain the current AST error status value
astStcCatalogEntryLocation – Create a StcCatalogEntryLocation
astStcObsDataLocation – Create a StcObsDataLocation
astStcResourceProfile – Create a StcResourceProfile
astStcSearchLocation – Create a StcSearchLocation
astStcsChan – Create an StcsChan
astStripEscapes – Remove AST escape sequences from a string
astSwitchMap – Create a SwitchMap
astTable – Create a Table
astTableSource – Register a source function for accessing tables in FITS files
astTest – Test if an Object attribute value is set
astTestCell – Tests if a single HEALPix cell is included in a Moc
astTestFits – See if a named keyword has a defined value in a FitsChan
astText – Draw a text string for a Plot
astThread – Determine the thread that owns an Object
astTimeAdd – Add a time coordinate conversion to a TimeMap
astTimeFrame – Create a TimeFrame
astTimeMap – Create a TimeMap
astToString – Create an in-memory serialisation of an Object
astTran1 – Transform 1-dimensional coordinates
astTran2 – Transform 2-dimensional coordinates
astTranGrid – Transform a grid of positions
astTranMap – Create a TranMap
astTranN – Transform N-dimensional coordinates
astTranP – Transform N-dimensional coordinates held in separate arrays
astTune – Set or get an integer-valued AST global tuning parameter
astTuneC – Set or get a character-valued AST global tuning parameter
astUinterp – Perform sub-pixel interpolation on a grid of data
astUkern1 – 1-dimensional sub-pixel interpolation kernel
astUnformat – Read a formatted coordinate value for a Frame axis
astUnitMap – Create a UnitMap
astUnitNormMap – Create a UnitNormMap
astUnlock – Unlock an Object for use by other threads
astVersion – Return the version of the AST library being used
astWarnings – Returns any warnings issued by the previous read or write operation
astWatch – Identify a new error status variable for the AST library
astWcsMap – Create a WcsMap
astWinMap – Create a WinMap
astWrite – Write an Object to a Channel
astWriteFits – Write out all cards in a FitsChan to the sink function
astXmlChan – Create an XmlChan
astYamlChan – Create a YamlChan
astZoomMap – Create a ZoomMap

C AST Attribute Descriptions
Abbrev(axis) – Abbreviate leading fields within numerical axis labels?
Adaptive – Should the area adapt to changes in the coordinate system?
AlignOffset – Align SkyFrames using the offset coordinate system?
AlignSideBand – Should the SideBand attribute be taken into account when aligning this DSBSpecFrame with another DSBSpecFrame?
AlignSpecOffset – Align SpecFrames using the offset coordinate system?
AlignStdOfRest – Standard of rest to use when aligning SpecFrames
AlignSystem – Coordinate system in which to align the Frame
AlignTimeScale – Time scale to use when aligning TimeFrames
AllVariants – A list of the variant Mappings associated with the current Frame
AllWarnings – A list of all currently available condition names
AltAxes – Controls generation of FITS-WCS alternate axis descriptions
AsTime(axis) – Format celestal coordinates as times?
Base – FrameSet base Frame index
Border – Draw a border around valid regions of a Plot?
Bottom(axis) – Lowest axis value to display
Bounded – Is the Region bounded?
CDMatrix – Use CDi_j keywords to represent pixel scaling, rotation, etc?
CarLin – Ignore spherical rotations on CAR projections?
Card – Index of current FITS card in a FitsChan
CardComm – The comment for the current card in a FitsChan
CardName – The keyword name of the current card in a FitsChan
CardType – The data type of the current card in a FitsChan
Class – Object class name
Clean – Remove cards used whilst reading even if an error occurs?
Clip – Clip lines and/or markers at the Plot boundary?
ClipOp – Combine Plot clipping limits using a boolean OR?
Closed – Should the boundary be considered to be inside the region?
Colour(element) – Colour index for a Plot element
ColumnLenC(column) – The largest string length of any value in a column
ColumnLength(column) – The number of elements in each value in a column
ColumnNdim(column) – The number of axes spanned by each value in a column
ColumnType(column) – The data type of each value in a column
Comment – Include textual comments in output?
Current – FrameSet current Frame index
DSBCentre – The central position of interest in a dual sideband spectrum
DefB1950 – Use FK4 B1950 as defaults?
Digits/Digits(axis) – Number of digits of precision
Direction(axis) – Display axis in conventional direction?
Disco – PcdMap pincushion/barrel distortion coefficient
Domain – Coordinate system domain
DrawAxes(axis) – Draw axes for a Plot?
DrawTitle – Draw a title for a Plot?
Dtai – The TAI-UTC correction
Dut1 – The UT1-UTC correction
Edge(axis) – Which edges to label in a Plot
Encoding – System for encoding Objects as FITS headers
Epoch – Epoch of observation
Equinox – Epoch of the mean equinox
Escape – Allow changes of character attributes within strings?
FillFactor – Fraction of the Region which is of interest
FitsAxisOrder – Frame title
FitsDigits – Digits of precision for floating point FITS values
FitsRounding – Controls rounding of floating-point FITS values
FitsTol – Maximum non-linearity allowed when exporting to FITS-WCS
Font(element) – Character font for a Plot element
ForceTab – Force the use of the -TAB algorithm when writing FITS-WCS headers?
Format(axis) – Format specification for axis values
Full – Set level of output detail
Gap(axis) – Interval between linearly spaced major axis values of a Plot
Grf – Use Grf functions registered through astGrfSet?
Grid – Draw grid lines for a Plot?
GrismAlpha – The angle of incidence of the incoming light on the grating surface
GrismEps – The angle between the normal and the dispersion plane
GrismG – The grating ruling density
GrismM – The interference order
GrismNR – The refractive index at the reference wavelength
GrismNRP – The rate of change of refractive index with wavelength
GrismTheta – Angle between normal to detector plane and reference ray
GrismWaveR – The reference wavelength
ID – Object identification string
IF – The intermediate frequency in a dual sideband spectrum
Ident – Permanent Object identification string
ImagFreq – The image sideband equivalent of the rest frequency
Indent – Specifies the indentation to use in text produced by a Channel
InternalUnit(axis) – Physical units for unformated axis values
IntraFlag – IntraMap identification string
Invert – Mapping inversion flag
Invisible – Draw graphics using invisible ink?
IsLatAxis(axis) – Is the specified celestial axis a latitude axis?
IsLinear – Is the Mapping linear?
IsLonAxis(axis) – Is the specified celestial axis a longitude axis?
IsSimple – Has the Mapping been simplified?
IterInverse – Provide an iterative inverse transformation?
Iwc – Include a Frame representing FITS-WCS intermediate world coordinates?
KeyCase – Are keys case sensitive?
KeyError – Report an error when getting the value of a non-existant KeyMap entry?
LTOffset – The offset from UTC to Local Time, in hours
Label(axis) – Axis label
LabelAt(axis) – Where to place numerical labels for a Plot
LabelUnits(axis) – Use axis unit descriptions in a Plot?
LabelUp(axis) – Draw numerical Plot labels upright?
Labelling – Label and tick placement option for a Plot
LatAxis – Index of the latitude axis
ListSize – Number of points in a PointList
LogGap(axis) – Interval between major axis values of a Plot
LogLabel(axis) – Use exponential format for numerical axis labels?
LogPlot(axis) – Map the plot logarithmically onto the screen?
LogTicks(axis) – Space the major tick marks logarithmically?
LonAxis – Index of the longitude axis
LutEpsilon – The relative error of the values held in the took-up table
LutInterp – Look-up table interpolation method
MajTickLen(axis) – Length of major tick marks for a Plot
MapLocked – Prevent new entries being added to a KeyMap?
MatchEnd – Match trailing axes?
MaxAxes – Maximum number of Frame axes to match
MaxOrder – The highest HEALPix order used in the MOC
MaxRes – The best resolution of the MOC
MeshSize – Number of points used to represent the boundary of a Region
MinAxes – Minimum number of Frame axes to match
MinOrder – The lowest HEALPix order used in the MOC
MinRes – The worst resolution of the MOC
MinTick(axis) – Density of minor tick marks for a Plot
MinTickLen(axis) – Length of minor tick marks for a Plot
MocArea – The area covered by the Moc, in square arc-minutes
MocFormat – Format for encoding Mocs as text
MocLength – The table length used to describe a Moc in FITS
MocLineLen – Controls output buffer length
MocType – The data type used to describe a Moc in FITS
NatLat – Native latitude of the reference point of a FITS-WCS projection
NatLon – Native longitude of the reference point of a FITS-WCS projection
Naxes – Number of Frame axes
Ncard – Number of FITS header cards in a FitsChan
Ncolumn – The number of columns in the table
NegLon – Display negative longitude values?
Negated – Region negation flag
Nframe – Number of Frames in a FrameSet
Nin – Number of input coordinates for a Mapping
NiterInverse – Maximum number of iterations for the iterative inverse transformation
Nkey – Number of unique FITS keywords in a FitsChan
Nobject – Number of Objects in class
Norm(axis) – Specifies the plane upon which a Plot3D draws text and markers
NormUnit(axis) – Normalised physical units for formatted axis values
Nout – Number of output coordinates for a Mapping
Nparameter – The number of global parameters in the table
Nrow – The number of rows in the table
NumLab(axis) – Draw numerical axis labels for a Plot?
NumLabGap(axis) – Spacing of numerical labels for a Plot
ObjSize – The in-memory size of the Object
ObsAlt – The geodetic altitude of the observer
ObsLat – The geodetic latitude of the observer
ObsLon – The geodetic longitude of the observer
PVMax(i) – Maximum number of FITS-WCS projection parameters
PVi_m – FITS-WCS projection parameters
PcdCen(axis) – Centre coordinates of pincushion/barrel distortion
Permute – Permute axis order?
PolarLong – The longitude value to assign to either pole
PolyTan – Use PVi_m keywords to define distorted TAN projection?
PreserveAxes – Preserve axes?
PreserveName – Save the ASDF name attributes as AST Ident values?
ProjP(m) – FITS-WCS projection parameters
Projection – Sky projection description
RefCount – Count of active Object pointers
RefDec – The declination of the reference point
RefRA – The right ascension of the reference point
RegionClass – The AST class name of the Region encapsulated within an Stc
Report – Report transformed coordinates?
ReportLevel – Determines which read/write conditions are reported
RestFreq – The rest frequency
RootCorner – Specifies which edges of the 3D box should be annotated
Seed – Random number seed for a MathMap
SideBand – Indicates which sideband a dual sideband spectrum represents
SimpFI – Forward-inverse MathMap pairs simplify?
SimpIF – Inverse-forward MathMap pairs simplify?
SimpVertices – Simplify a Polygon by transforming its vertices?
SinkFile – Output file to which to data should be written
SipOK – Use Spitzer Space Telescope keywords to define distortion?
SipReplace – Replace SIP inverse transformation?
Size(element) – Character size for a Plot element
SizeGuess – The expected size of the KeyMap
Skip – Skip irrelevant data?
SkyRef(axis) – Position defining the offset coordinate system
SkyRefIs – Selects the nature of the offset coordinate system
SkyRefP(axis) – Position on primary meridian of offset coordinate system
SkyTol – The smallest significant shift in sky coordinates
SortBy – Determines how keys are sorted in a KeyMap
SourceFile – Input file from which to read data
SourceSys – Spectral system in which the source velocity is stored
SourceVRF – Rest frame in which the source velocity is stored
SourceVel – The source velocity
SpecOrigin – The zero point for SpecFrame axis values
SpecVal – The spectral position at which flux values are measured
StcsArea – Return the CoordinateArea component when reading an STC-S document?
StcsCoords – Return the Coordinates component when reading an STC-S document?
StcsLength – Controls output line length
StcsProps – Return all properties when reading an STC-S document?
StdOfRest – Standard of rest
Strict – Report an error if any unexpected data items are found?
Style(element) – Line style for a Plot element
Symbol(axis) – Axis symbol
System – Coordinate system used to describe positions within the domain
TabOK – Should the FITS-WCS -TAB algorithm be recognised?
TextGapType – Controls the interpretation of attributes TextLabGap and TitleGap
TextLab(axis) – Draw descriptive axis labels for a Plot?
TextLabGap(axis) – Spacing of descriptive axis labels for a Plot
TickAll – Draw tick marks on all edges of a Plot?
TimeOrigin – The zero point for TimeFrame axis values
TimeScale – Time scale
Title – Frame title
TitleGap – Vertical spacing for a Plot title
Tol – Plotting tolerance
TolInverse – Target relative error for the iterative inverse transformation
Top(axis) – Highest axis value to display
TranForward – Forward transformation defined?
TranInverse – Inverse transformation defined?
Unit(axis) – Physical units for formatted axis values
UnitRadius – SphMap input vectors lie on a unit sphere?
UseDefs – Use default values for unspecified attributes?
Variant – Indicates which variant of the current Frame is to be used
VerboseRead – Echo YAML text to standard output as it is read?
Warnings – Controls the issuing of warnings about various conditions
WcsAxis(lonlat) – FITS-WCS projection axes
WcsType – FITS-WCS projection type
Width(element) – Line width for a Plot element
XmlFormat – System for formatting Objects as XML
XmlLength – Controls output buffer length
XmlPrefix – The namespace prefix to use when writing
YamlEncoding – System for formatting Objects as YAML
Zoom – ZoomMap scale factor

D AST Class Descriptions
Axis – Store axis information
Box – A box region with sides parallel to the axes of a Frame
Channel – Basic (textual) I/O channel
ChebyMap – Map coordinates using Chebyshev polynomial functions
Circle – A circular or spherical region within a Frame
CmpFrame – Compound Frame
CmpMap – Compound Mapping
CmpRegion – A combination of two regions within a single Frame
DSBSpecFrame – Dual sideband spectral coordinate system description
DssMap – Map points using a Digitised Sky Survey plate solution
Ellipse – An elliptical region within a 2-dimensional Frame
FitsChan – I/O Channel using FITS header cards to represent Objects
FitsTable – A representation of a FITS binary table
FluxFrame – Measured flux description
Frame – Coordinate system description
FrameSet – Set of inter-related coordinate systems
GrismMap – Transform 1-dimensional coordinates using a grism dispersion equation
Interval – A region representing an interval on one or more axes of a Frame
IntraMap – Map points using a private transformation function
KeyMap – Store a set of key/value pairs
LutMap – Transform 1-dimensional coordinates using a lookup table
Mapping – Inter-relate two coordinate systems
MathMap – Transform coordinates using mathematical expressions
MatrixMap – Map coordinates by multiplying by a matrix
Moc – An arbitrary region of the sky expressed as a collection of HEALPix cells
MocChan – I/O Channel for textual representations of Mocs
NormMap – Normalise coordinates using a supplied Frame
NullRegion – A boundless region within a Frame
Object – Base class for all AST Objects
PcdMap – Apply 2-dimensional pincushion/barrel distortion
PermMap – Coordinate permutation Mapping
Plot – Provide facilities for 2D graphical output
Plot3D – Provide facilities for 3D graphical output
PointList – A collection of points in a Frame
PolyMap – Map coordinates using polynomial functions
Polygon – A polygonal region within a 2-dimensional Frame
Prism – An extrusion of a region into higher dimensions
RateMap – Mapping which represents differentiation
Region – Represents a region within a coordinate system
SelectorMap – A Mapping that locates positions within one of a set of alternate Regions
ShiftMap – Add a constant value to each coordinate
SkyAxis – Store celestial axis information
SkyFrame – Celestial coordinate system description
SlaMap – Sequence of celestial coordinate conversions
SpecFluxFrame – Compound spectrum/flux Frame
SpecFrame – Spectral coordinate system description
SpecMap – Sequence of spectral coordinate conversions
SphMap – Map 3-d Cartesian to 2-d spherical coordinates
Stc – Represents an instance of the IVOA STC class
StcCatalogEntryLocation – Correspond to the IVOA STCCatalogEntryLocation class
StcObsDataLocation – Correspond to the IVOA ObsDataLocation class
StcResourceProfile – Correspond to the IVOA STCResourceProfile class
StcSearchLocation – Correspond to the IVOA SearchLocation class
StcsChan – I/O Channel using STC-S to represent Objects
SwitchMap – A Mapping that encapsulates a set of alternate Mappings
Table – A 2-dimensional table of values
TimeFrame – Time coordinate system description
TimeMap – Sequence of time coordinate conversions
TranMap – Mapping with specified forward and inverse transformations
UnitMap – Unit (null) Mapping
UnitNormMap – Convert a vector to a unit vector and its norm, relative to a specified centre
WcsMap – Implement a FITS-WCS sky projection
WinMap – Map one window on to another by scaling and shifting each axis
XmlChan – I/O Channel using XML to represent Objects
YamlChan – I/O Channel that uses YAML to represent Objects
ZoomMap – Zoom coordinates about the origin

E UNIX Command Descriptions
ast_link – Link a program with the AST library
ast_link_adam – Link an ADAM program with the AST library

F AST Memory Management and Utility Functions
astAppendString – Append a string to another string which grows dynamically
astAppendStringf – Append a string to another string, allowing printf format specifiers
astBrackets – Identify a bracketed sub-string
astCalloc – Allocate and initialise memory
astChr2Double – read a double value from a string
astChrCase – Convert a string to upper or lower case
astChrClean – Replace unprintable characters in a string with spaces
astChrLen – Determine the used length of a string
astChrMatch – Case insensitive string comparison
astChrMatchN – Case insensitive string comparison of at most N characters
astChrRemoveBlanks – Remove all spaces from a string
astChrSplit – Extract words from a supplied string
astChrSplitC – Split a string using a specified character delimiter
astChrSplitRE – Extract sub-strings matching a specified regular expression
astChrSub – Performs substitutions on a supplied string
astChrTrunc – Terminate a string to exclude trailing spaces
astFandl – Identify the used section of a string
astFree – Free previously allocated memory
astFreeDouble – Free previously double allocated memory
astGrow – Allocate memory for an adjustable array
astIsDynamic – Returns a flag indicating if memory was allocated dynamically
astMalloc – Allocate memory
astMemCaching – Controls whether allocated but unused memory is cached in this module
astRealloc – Change the size of a dynamically allocated region of memory
astRemoveLeadingBlanks – Remove any leading white space from a string
astSizeOf – Determine the size of a dynamically allocated region of memory
astStore – Store data in dynamically allocated memory
astString – Create a C string from an array of characters
astStringArray – Create an array of C strings from an array of characters
astStringCase – Convert a string to upper or lower case

G FITS-WCS Coverage
 G.1 Paper I - General Linear Coordinates
  G.1.1 Requirements for a Successful Write Operation
  G.1.2 Use and Choice of CTYPEi keywords
  G.1.3 Choice of Reference Point
  G.1.4 Choice of Axis Ordering
  G.1.5 Alternate Axis Descriptions
 G.2 Paper II - Celestial Coordinates

This is the C version of this document.
For the Fortran version, please see SUN/210.