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

SUN/210.30

Starlink Project
Starlink User Note 210.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
(Fortran 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 Copying Objects
4.13 Error Detection
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 AST_CONVERT
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 Routines 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 Routine
20.5 Registering a Transformation Routine
20.6 Creating an IntraMap
20.7 Restricted Implementations of Transformation Routines
20.8 Variable Numbers of Coordinates
20.9 Adapting a Transformation Routine to Individual IntraMaps
20.10 Simplifying IntraMaps
20.11 Writing and Reading IntraMaps
20.12 Managing Transformation Routines 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 AST Include Files
22.2 Linking with AST Facilities
22.3 Building ADAM Applications that Use AST
A The AST Class Hierarchy
B AST Routine Descriptions

AST_SET – Set attribute values for an Object

AST_ADDCELL – Adds a single HEALPix cell into an existing Moc

AST_ADDCOLUMN – Add a new column definition to a table

AST_ADDFRAME – Add a Frame to a FrameSet to define a new coordinate system

AST_ADDMOCDATA – Adds a FITS binary table into an existing Moc

AST_ADDMOCSTRING – Adds a JSON or string-encoded MOC into an existing Moc

AST_ADDPARAMETER – Add a new global parameter definition to a table

AST_ADDPIXELMASK

<

>

– Add a set of pixels to a Moc

AST_ADDREGION – Add a Region into a Moc

AST_ADDVARIANT – Store a new variant Mapping for the current Frame in a FrameSet

AST_ANGLE – Calculate the angle subtended by two points at a third point

AST_ANNUL – Annul a pointer to an Object

AST_AXANGLE – Returns the angle from an axis, to a line through two points

AST_AXDISTANCE – Find the distance between two axis values

AST_AXNORM – Normalise an array of axis values

AST_AXOFFSET – Add an increment onto a supplied axis value

AST_BBUF – Begin a new graphical buffering context

AST_BEGIN – Begin a new AST context

AST_BORDER – Draw a border around valid regions of a Plot

AST_BOUNDINGBOX – Return a bounding box for previously drawn graphics

AST_BOX – Create a Box

AST_CHANNEL – Create a Channel

AST_CHEBYDOMAIN – Returns the bounding box of the domain of a ChebyMap

AST_CHEBYMAP – Create a ChebyMap

AST_CIRCLE – Create a Circle

AST_CIRCLEPARS – Returns the geometric parameters of an Circle

AST_CLEAR – Clear attribute values for an Object

AST_CLIP – Set up or remove clipping for a Plot

AST_CLONE – Clone (duplicate) an Object pointer

AST_CMPFRAME – Create a CmpFrame

AST_CMPMAP – Create a CmpMap

AST_CMPREGION – Create a CmpRegion

AST_COLUMNNAME – Get the name of the column at a given index within the Table

AST_COLUMNNULL – Get or set the null value for an integer column of a FITS table

AST_COLUMNSHAPE – Returns the shape of the values in a named column

AST_COLUMNSIZE – Get the number of bytes needed to hold a full column of data

AST_CONVERT – Determine how to convert between two coordinate systems

<

>

– Create a new Polygon representing the convex hull of a 2D data grid

AST_COPY – Copy an Object

AST_CURRENTTIME – Return the current system time

AST_CURVE – Draw a geodesic curve

AST_DECOMPOSE – Decompose a Mapping into two component Mappings

AST_DELETE – Delete an Object

AST_DELFITS – Delete the current FITS card in a FitsChan

AST_DISTANCE – Calculate the distance between two points in a Frame

AST_DOWNSIZE – Reduce the number of vertices in a Polygon

AST_DSBSPECFRAME – Create a DSBSpecFrame

AST_EBUF – End the current graphical buffering context

AST_ELLIPSE – Create a Ellipse

AST_ELLIPSEPARS – Returns the geometric parameters of an Ellipse

AST_EMPTYFITS – Delete all cards in a FitsChan

AST_END – End an AST context

AST_ESCAPES – Control whether graphical escape sequences are included in strings

AST_EXEMPT – Exempt an Object pointer from AST context handling

AST_EXPORT – Export an Object pointer to an outer context

AST_FINDFITS – Find a FITS card in a FitsChan by keyword

AST_FINDFRAME – Find a coordinate system with specified characteristics

AST_FITSCHAN – Create a FitsChan

AST_FITSTABLE – Create a FitsTable

AST_FLUXFRAME – Create a FluxFrame

AST_FORMAT – Format a coordinate value for a Frame axis

AST_FRAME – Create a Frame

AST_FRAMESET – Create a FrameSet

AST_GENCURVE – Draw a generalized curve

<

>

– Get an attribute value for an Object

AST_GETACTIVEUNIT – Determines how the Unit attribute will be used

AST_GETCELL – Identify the next cell in a normalised Moc

AST_GETCOLUMNDATA – Retrieve all the data values stored in a column

<

>

– Get a named keyword value from a FitsChan

AST_GETFRAME – Obtain a pointer to a specified Frame in a FrameSet

AST_GETGRFCONTEXT – Return the KeyMap that describes a Plot’ s graphics context

AST_GETLINE – Obtain text to be written by a Channel sink routine

AST_GETMAPPING – Obtain a Mapping that converts between two Frames in a FrameSet

AST_GETMOCDATA – Get the FITS binary table data describing a Moc

AST_GETMOCHEADER – Get the FITS binary table headers describing a Moc

AST_GETMOCSTRING – Get the JSON or string-encoded representation of a Moc

AST_GETREFPOS – Return the reference position in a specified celestial coordinate system

AST_GETREGIONBOUNDS – Returns the bounding box of Region

AST_GETREGIONDisc – Returns the centre and radius of a disc containing a 2D Region

AST_GETREGIONFRAME – Obtain a pointer to the encapsulated Frame within a Region

AST_GETREGIONFRAMESET – Obtain a pointer to the encapsulated FrameSet within a Region

AST_GETREGIONMESH – Return a mesh of points covering the surface or volume of a Region

AST_GETREGIONPOINTS – Returns the positions that define the given Region

AST_GETSTCCOORD – Return information about an AstroCoords element stored in an Stc

AST_GETSTCNCOORD – Return the number of AstroCoords elements stored in an Stc

AST_GETSTCREGION – Obtain a copy of the encapsulated Region within a Stc

AST_GETTABLES – Retrieve any FitsTables currently in a FitsChan

AST_GETUNC – Obtain uncertainty information from a Region

AST_GRFPOP – Restore previously saved graphics functions used by a Plot

AST_GRFPUSH – Save the current graphics functions used by a Plot

AST_GRFSET – Register a graphics routine for use by a Plot

AST_GRID – Draw a set of labelled coordinate axes

AST_GRIDLINE – Draw a grid line (or axis) for a Plot

AST_GRISMMAP – Create a GrismMap

AST_GetTableHeader – Get the FITS headers from a FitsTable

AST_HASATTRIBUTE – Test if an Object has a named attribute

AST_HASCOLUMN – Returns a flag indicating if a column is present in a Table

AST_HASPARAMETER – Returns a flag indicating if a named global parameter is present in a Table

AST_IMPORT – Import an Object pointer to the current context

AST_INTERSECT – Find the point of intersection between two geodesic curves

AST_INTERVAL – Create a Interval

AST_INTRAMAP – Create an IntraMap

AST_INTRAREG – Register a transformation routine for use by an IntraMap

AST_INVERT – Invert a Mapping

<

>

– Test membership of a class by an Object

AST_KEYMAP – Create a KeyMap

AST_LINEARAPPROX – Obtain a linear approximation to a Mapping, if appropriate

AST_LUTMAP – Create a LutMap

AST_MAPBOX – Find a bounding box for a Mapping

AST_MAPCOPY – Copy all entries from one KeyMap into another

AST_MAPCOPYENTRY – Copy a single entry from one KeyMap into another

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

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

<

>

– Get a single element of a vector value from a KeyMap

AST_MAPHASKEY – Check if an entry with a given key exists in a KeyMap

AST_MAPKEY – Get the key at a given index within the KeyMap

AST_MAPLENC – Get the number of characters in a character entry in a KeyMap

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

AST_MAPPUTU – Add an entry to a KeyMap with an undefined value

AST_MAPREGION – Transform a Region into a new Frame using a given Mapping

AST_MAPREMOVE – Removed a named entry from a KeyMap

AST_MAPRENAME – Rename an existing KeyMap entry

AST_MAPSIZE – Get the number of entries in a KeyMap

AST_MAPSPLIT – Split a Mapping up into parallel component Mappings

AST_MAPTYPE – Get the data type of an entry in a KeyMap

AST_MARK – Draw a set of markers for a Plot

<

>

– Mask a region of a data grid

AST_MATCHAXES – Find any corresponding axes in two Frames

AST_MATHMAP – Create a MathMap

AST_MATRIXMAP – Create a MatrixMap

AST_MIRRORVARIANTS – Make the current Frame mirror the variant Mappings in another Frame

AST_MOC – Create a Moc

AST_MOCCHAN – Create a MocChan

AST_NEGATE – Negate the area represented by a Region

AST_NORM – Normalise a set of Frame coordinates representing one point

AST_NORMMAP – Create a NormMap

AST_NORMPOINTS – Normalise a collection of points

AST_NULLREGION – Create a NullRegion

AST_OFFSET – Calculate an offset along a geodesic curve

AST_OFFSET2 – Calculate an offset along a geodesic curve in a 2D Frame

<

>

– Create a new Polygon outling values in a 2D data grid

AST_OVERLAP – Test if two regions overlap each other

AST_PARAMETERNAME – Get the name of the global parameter at a given index within the Table

AST_PCDMAP – Create a PcdMap

AST_PERMAXES – Permute the axis order in a Frame

AST_PERMMAP – Create a PermMap

AST_PICKAXES – Create a new Frame by picking axes from an existing one

AST_PLOT – Create a Plot

AST_PLOT3D – Create a Plot3D

AST_POINTINREGION – Tests if a single point is inside a Region

AST_POINTLIST – Create a PointList

AST_POLYCOEFFS – Retrieve the coefficient values used by a PolyMap

AST_POLYCURVE – Draw a series of connected geodesic curves

AST_POLYGON – Create a Polygon

AST_POLYMAP – Create a PolyMap

AST_POLYTRAN – Fit a PolyMap inverse or forward transformation

AST_PRISM – Create a Prism

AST_PURGEROWS – Remove all empty rows from a table

AST_PURGEWCS – Delete all cards in the FitsChan describing WCS information

AST_PUTCARDS – Store a set of FITS header cards in a FitsChan

AST_PUTCOLUMNDATA – Store new data values for all rows of a column

AST_PUTFITS – Store a FITS header card in a FitsChan

AST_PUTLINE – Store a text line read by a Channel source routine

AST_PUTTABLE – Store a single FitsTable in a FitsChan

AST_PUTTABLEHEADER – Store new FITS headers in a FitsTable

AST_PUTTABLES – Store one or more FitsTables in a FitsChan

AST_QUADAPPROX – Obtain a quadratic approximation to a 2D Mapping

AST_RATE – Calculate the rate of change of a Mapping output

AST_RATEMAP – Create a RateMap

AST_READ – Read an Object from a Channel

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

AST_REMAPFRAME – Modify a Frame’ s relationship to other Frames in a FrameSet

AST_REMOVECOLUMN – Remove a column from a table

AST_REMOVEFRAME – Remove a Frame from a FrameSet

AST_REMOVEPARAMETER – Remove a global parameter from a table

AST_REMOVEREGIONS – Remove any Regions from a Mapping

AST_REMOVEROW – Remove a row from a table

AST_REMOVETABLES – Remove one or more tables from a FitsChan

<

>

– Resample a region of a data grid

AST_RESOLVE – Resolve a vector into two orthogonal components

AST_RETAINFITS – Indicate that the current card in a FitsChan should be retained

AST_RegionOutline – Draw the outline of an AST Region

AST_SAME – Test if two AST pointers refer to the same Object

AST_SELECTORMAP – Create a SelectorMap

AST_SET – Set attribute values for an Object

<

>

– Set an attribute value for an Object

AST_SETACTIVEUNIT – Specify how the Unit attribute should be used

<

>

– Store a keyword value in a FitsChan

AST_SETFITSCM – Store a comment card in a FitsChan

AST_SETFITSU – Store an undefined keyword value in a FitsChan

AST_SETPUTERR – Register an error handling routine for use by the AST error model

AST_SETREFPOS – Set the reference position in a specified celestial coordinate system

AST_SETUNC – Store uncertainty information in a Region

AST_SHIFTMAP – Create a ShiftMap

AST_SHOW – Display a textual representation of an Object on standard output

AST_SHOWFITS – Display the contents of a FitsChan on standard output

AST_SHOWMESH – Display a mesh of points covering the surface of a Region

AST_SIMPLIFY – Simplify a Mapping

AST_SKYFRAME – Create a SkyFrame

AST_SKYOFFSETMAP – Returns a Mapping which goes from absolute coordinates to offset coordinates

AST_SLAADD – Add a celestial coordinate conversion to an SlaMap

AST_SLAMAP – Create an SlaMap

AST_SPECADD – Add a spectral coordinate conversion to a SpecMap

AST_SPECFLUXFRAME – Create a SpecFluxFrame

AST_SPECFRAME – Create a SpecFrame

AST_SPECMAP – Create a SpecMap

AST_SPHMAP – Create a SphMap

AST_STCCATALOGENTRYLOCATION – Create a StcCatalogEntryLocation

AST_STCOBSDATALOCATION – Create a StcObsDataLocation

AST_STCRESOURCEPROFILE – Create a StcResourceProfile

AST_STCSCHAN – Create an StcsChan

AST_STCSEARCHLOCATION – Create a StcSearchLocation

AST_STRIPESCAPES – Remove AST escape sequences from a string

AST_SWITCHMAP – Create a SwitchMap

AST_TABLE – Create a Table

AST_TABLESOURCE – Register a source routine for accessing tables in FITS files

AST_TEST – Test if an Object attribute value is set

AST_TESTCELL – Tests if a single HEALPix cell is included in a Moc

AST_TESTFITS – See if a named keyword has a defined value in a FitsChan

AST_TEXT – Draw a text string for a Plot

AST_TIMEADD – Add a time coordinate conversion to a TimeMap

AST_TIMEFRAME – Create a TimeFrame

AST_TIMEMAP – Create a TimeMap

AST_TRAN1 – Transform 1-dimensional coordinates

AST_TRAN2 – Transform 2-dimensional coordinates

AST_TRANGRID – Transform a grid of positions

AST_TRANMAP – Create a TranMap

AST_TRANN – Transform N-dimensional coordinates

AST_TUNE – Set or get an integer-valued AST global tuning parameter

AST_TUNEC – Set or get a character-valued AST global tuning parameter

AST_UINTERP – Perform sub-pixel interpolation on a grid of data

AST_UKERN1 – 1-dimensional sub-pixel interpolation kernel

AST_UNFORMAT – Read a formatted coordinate value for a Frame axis

AST_UNITMAP – Create a UnitMap

AST_UNITNORMMAP – Create a UnitNormMap

AST_VERSION – Return the version of the AST library being used

AST_WARNINGS – Returns any warnings issued by the previous read or write operation

AST_WCSMAP – Create a WcsMap

AST_WINMAP – Create a WinMap

AST_WRITE – Write an Object to a Channel

AST_WRITEFITS – Write out all cards in a FitsChan to the sink function

AST_XMLCHAN – Create an XmlChan

AST_YAMLCHAN – Create a YamlChan

AST_ZOOMMAP – 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 routines registered through AST_GRFSET?

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 routine

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 FITS-WCS Coverage
F.1 Paper I - General Linear Coordinates
  F.1.1 Requirements for a Successful Write Operation
  F.1.2 Use and Choice of CTYPEi keywords
  F.1.3 Choice of Reference Point
  F.1.4 Choice of Axis Ordering
  F.1.5 Alternate Axis Descriptions
F.2 Paper II - Celestial Coordinates
  F.2.1 Requirements for a Successful Write Operation
  F.2.2 Choice of LONPOLE/LATPOLE
  F.2.3 User Defined Fiducial Points
  F.2.4 Common Non-Standard Features
F.3 Paper III - Spectral Coordinates
  F.3.1 Requirements for a Successful Write Operation
  F.3.2 Common Non-Standard Features
F.4 Paper IV - Coordinate Distortions
  F.4.1 The “-SIP” distortion code
G Release Notes
G.1 Changes Introduced in V1.1
G.2 Changes Introduced in V1.2
G.3 Changes Introduced in V1.3
G.4 Changes Introduced in V1.4
G.5 Changes Introduced in V1.5
G.6 Changes Introduced in V1.6
G.7 Changes Introduced in V1.7
G.8 Changes Introduced in V1.8-2
G.9 Changes Introduced in V1.8-3
G.10 Changes Introduced in V1.8-4
G.11 Changes Introduced in V1.8-5
G.12 Changes Introduced in V1.8-7
G.13 Changes Introduced in V1.8-8
G.14 Changes Introduced in V1.8-13
G.15 Changes Introduced in V2.0
G.16 Changes Introduced in V3.0
G.17 Changes Introduced in V3.1
G.18 Changes Introduced in V3.2
G.19 Changes Introduced in V3.3
G.20 Changes Introduced in V3.4
G.21 Changes Introduced in V3.5
G.22 Changes Introduced in V3.6
G.23 Changes Introduced in V3.7
G.24 Changes Introduced in V4.0
G.25 Changes Introduced in V4.1
G.26 Changes Introduced in V4.2
G.27 Changes Introduced in V4.3
G.28 Changes Introduced in V4.4
G.29 Changes Introduced in V4.5
G.30 Changes Introduced in V4.6
G.31 Changes Introduced in V5.0
G.32 Changes Introduced in V5.1
G.33 Changes Introduced in V5.2
G.34 Changes Introduced in V5.3
G.35 Changes Introduced in V5.3-1
G.36 Changes Introduced in V5.3-2
G.37 Changes Introduced in V5.4-0
G.38 Changes Introduced in V5.5-0
G.39 Changes Introduced in V5.6-0
G.40 ChangesIntroduced in V5.6-1
G.41 Changes Introduced in V5.7-0
G.42 Changes Introduced in V5.7-1
G.43 Changes Introduced in V5.7-2
G.44 Changes Introduced in V6.0
G.45 Changes Introduced in V6.0-1
G.46 Changes Introduced in V7.0.0
G.47 Changes Introduced in V7.0.1
G.48 Changes Introduced in V7.0.2
G.49 Changes Introduced in V7.0.3
G.50 Changes Introduced in V7.0.4
G.51 Changes Introduced in V7.0.5
G.52 Changes Introduced in V7.0.6
G.53 Changes Introduced in V7.1.0
G.54 Changes Introduced in V7.1.1
G.55 Changes Introduced in V7.2.0
G.56 Changes Introduced in V7.3.0
G.57 Changes Introduced in V7.3.1
G.58 Changes Introduced in V7.3.2
G.59 Changes Introduced in V7.3.3
G.60 Changes Introduced in V7.3.4
G.61 Changes Introduced in V8.0.0
G.62 Changes Introduced in V8.0.1
G.63 Changes Introduced in V8.0.2
G.64 Changes Introduced in V8.0.3
G.65 Changes Introduced in V8.0.4
G.66 Changes Introduced in V8.0.5
G.67 Changes Introduced in V8.1.0
G.68 Changes Introduced in V8.2
G.69 Changes Introduced in V8.3
G.70 Changes Introduced in V8.4
G.71 Changes Introduced in V8.5
G.72 Changes Introduced in V8.6.2
G.73 Changes Introduced in V8.6.3
G.74 Changes Introduced in V8.7.0
G.75 Changes Introduced in V8.7.1
G.76 Changes Introduced in V8.7.2
G.77 Changes Introduced in V9.0.0
G.78 Changes Introduced in V9.0.2
G.79 Changes Introduced in V9.1.0
G.80 Changes Introduced in V9.1.2
G.81 Changes Introduced in V9.1.3
G.82 Changes Introduced in V9.2.0
G.83 Changes Introduced in V9.2.4
G.84 Changes Introduced in V9.2.5
G.85 Changes Introduced in V9.2.6
G.86 Changes Introduced in V9.2.7
G.87 Changes Introduced in V9.2.8

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