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

_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

<

>

– 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

<

>

– 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

<

>

– 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

<

>

– 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

<

>

– 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

<

>

– Get a scalar value from a KeyMap

<

>

– Get a vector value from a KeyMap

astMapGetC – Get a scalar or vector value from a KeyMap as a single string

<

>

– 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

<

>

– Add a scalar value to a KeyMap

<

>

– Add a vector value to a KeyMap

<

>

– 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

<

>

– 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

<

>

– 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

<

>

– Rebin a region of a data grid

<

>

– 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

<

>

– 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

<

>

– Set an attribute value for an Object

astSetActiveUnit – Specify how the Unit attribute should be used

<

>

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