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 <X > – 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
AST_CONVEX <X > – 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
AST_GET <X > – 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
AST_GETFITS <X > – 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
AST_ISA <CLASS > – 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
AST_MAPGET0 <X > – Get a scalar value from a KeyMap
AST_MAPGET1 <X > – Get a vector value from a KeyMap
AST_MAPGETC – Get a scalar or vector value from a KeyMap as a single string
AST_MAPGETELEM <X > – 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
AST_MAPPUT0 <X > – Add a scalar value to a KeyMap
AST_MAPPUT1 <X > – Add a vector value to a KeyMap
AST_MAPPUTELEM <X > – 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
AST_MASK <X > – 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
AST_OUTLINE <X > – 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
AST_REBIN <X > – Rebin a region of a data grid
AST_REBINSEQ <X > – 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
AST_RESAMPLE <X > – 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
AST_SET <X > – Set an attribute value for an Object
AST_SETACTIVEUNIT – Specify how the Unit attribute should be used
AST_SETFITS <X > – 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.