Next: Abstract

AST - A Library for Handling World Coordinate Systems in Astronomy

$\includegraphics[scale=0.3,angle=-90]{sun210_figures/fronta.eps}$ $\includegraphics[scale=0.3,angle=-90]{sun210_figures/frontb.eps}$ $\includegraphics[scale=0.3,angle=-90]{sun210_figures/frontc.eps}$

V7.1 Programmer's Guide (Fortran Version)

Starlink User Note 210.27
R.F. Warren-Smith & D.S. Berry
7th December 2012

(For the C version of this document, please see SUN/211.)

CCLRC / Rutherford Appleton Laboratory
Particle Physics & Astronomy Research Council

Starlink Project

Retrieve hardcopy

Abstract
Introduction
- What Problems Does AST Tackle?
- Other Design Objectives
- What Does ``AST'' Stand For?
Overview of AST Concepts
- Relationships Between Coordinate Systems
- Mappings Available
- Compound Mappings
- Representing Coordinate Systems
- Networks of Coordinate Systems
- Input/Output Facilities
- Producing Graphical Output
How To...
- ...Obtain and Install AST
- ...Structure an AST Program
- ...Build an AST Program
- ...Read a WCS Calibration from a Dataset
- ...Validate WCS Information
- ...Display AST Data
- ...Convert Between Pixel and World Coordinates
- ...Test if a WCS is a Celestial Coordinate System
- ...Test if a WCS is a Spectral Coordinate System
- ...Format Coordinates for Display
- ...Display Coordinates as they are Transformed
- ...Read Coordinates Entered by a User
- ...Create a New WCS Calibration
- ...Modify a WCS Calibration
- ...Write a Modified WCS Calibration to a Dataset
- ...Display a Graphical Coordinate Grid
- ...Switch to Plot a Different Celestial Coordinate Grid
- ...Give a User Control Over the Appearance of a Plot
An AST Object Primer
- AST Objects
- Object Creation and Pointers
- The Object Hierarchy
- Displaying Objects
- Getting Attribute Values
- Setting Attribute Values
- Testing, Clearing and Defaulting Attributes
- Transforming Coordinates
- Managing Object Pointers
- AST Pointer Contexts--Begin and End
- Exporting, Importing and Exempting AST Pointers
- Copying Objects
- Error Detection
Inter-Relating Coordinate Systems (Mappings)
- The Mapping Class
- The Mapping Model
- Input and Output Coordinate Numbers
- Forward and Inverse Transformations
- Inverting Mappings
- Finding the Rate of Change of a Mapping Output
- Reporting Coordinate Transformations
- Handling Missing (Bad) Coordinate Values
- Example--the UnitMap
- Example--the PermMap
Compound Mappings (CmpMaps)
- Combining Mappings in Series
- Combining Mappings in Parallel
- The Component Mappings
- Creating More Complex Mappings
- Example--Transforming Between Two Calibrated Images
- Over-Complex Compound Mappings
- Simplifying Compound Mappings
Representing Coordinate Systems (Frames)
- The Frame Model
- Creating a Frame
- Using a Frame as a Mapping
- Frame Axis Attributes
- Frame Attributes
- Formatting Axis Values
- Normalising Frame Coordinates
- Reading Formatted Axis Values
- Permuting Frame Axes
- Selecting Frame Axes
- Calculating Distances, Angles and Offsets
- The Domain Attribute
- Conventions for Domain Names
- The Unit Attribute
  - The Syntax for Unit Strings
  - Side-effects of Changing the Unit attribute
Celestial Coordinate Systems (SkyFrames)
- The SkyFrame Model
- Creating a SkyFrame
- Specifying a Particular Celestial Coordinate System
- Attributes which Qualify Celestial Coordinate Systems
- Using Default SkyFrame Attributes
- Formatting Celestial Coordinates
- Reading Formatted Celestial Coordinates
- Representing Offsets from a Specified Sky Position
Spectral Coordinate Systems (SpecFrames)
- The SpecFrame Model
- Creating a SpecFrame
- Specifying a Particular Spectral Coordinate System
- Attributes which Qualify Spectral Coordinate Systems
- Using Default SpecFrame Attributes
- Creating Spectral Cubes
- Handling Dual-Sideband Spectra
Time Systems (TimeFrames)
- The TimeFrame Model
- Creating a TimeFrame
- Specifying a Particular Time System
- Attributes which Qualify Time Coordinate Systems
Compound Frames (CmpFrames)
- Creating a CmpFrame
- The Attributes of a CmpFrame
An Introduction to Coordinate System Conversions
- Converting between Celestial Coordinate Systems
- Converting between Spectral Coordinate Systems
- Converting between Time Coordinate Systems
- Handling SkyFrame Axis Permutations
- Converting Between Frames
- The Choice of Alignment System
Coordinate System Networks (FrameSets)
- The FrameSet Model
- Creating a FrameSet
- Adding New Frames to a FrameSet
- The Base and Current Frames
- Referring to the Base and Current Frames
- Using a FrameSet as a Mapping
- Extracting a Mapping from a FrameSet
- Using a FrameSet as a Frame
- Extracting a Frame from a FrameSet
- Removing a Frame from a FrameSet
Higher Level Operations on FrameSets
- Creating FrameSets with AST_CONVERT
- Converting between FrameSet Coordinate Systems
- Example--Registering Two Images
- Re-Defining a FrameSet Coordinate System
- Example--Binning an Image
- Maintaining the Integrity of FrameSets
- Merging FrameSets
Saving and Restoring Objects (Channels)
- The Channel Model
- Creating a Channel
- Writing Objects to a Channel
- Reading Objects from a Channel
- Saving and Restoring Multiple Objects
- Validating Input
- Storing an ID String with an Object
- The Textual Output Format
- Controlling the Amount of Output
- Controlling Commenting
- Editing Textual Output
- Mixing Objects with other Text
- Reading Objects from Files
- Writing Objects to Files
- Reading and Writing Objects to other Places
Storing AST Objects in FITS Headers (FitsChans)
- The Native FITS Encoding
- The FitsChan Model
- Creating a FitsChan
- Addressing Cards in a FitsChan
- Writing Native Objects to a FitsChan
- Extracting Individual Cards from a FitsChan
- The Native FitsChan Output Format
- Adding Individual Cards to a FitsChan
- Adding Concatenated Cards to a FitsChan
- Reading Native Objects From a FitsChan
- Saving and Restoring Multiple Objects in a FitsChan
- Mixing Native Objects with Other FITS Cards
- Finding and Changing Cards in a FitsChan
- Source and Sink Routines for FitsChans
Using Foreign FITS Encodings
- The Foreign FITS Encodings
- Limitations of Foreign Encodings
- Identifying Foreign Encodings on Input
- Reading Foreign WCS Information from a FITS Header
- Removing WCS Information from FITS Headers--the Destructive Read
- Propagating WCS Information through Data Processing Steps
- Writing Foreign WCS Information to a FITS Header
Storing AST Objects as XML (XmlChan)
- Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions
Reading and writing STC-S descriptions (StcsChans)
Creating Your Own Private Mappings (IntraMaps)
- The Need for Extensibility
- The IntraMap Model
- Limitations of IntraMaps
- Writing a Transformation Routine
- Registering a Transformation Routine
- Creating an IntraMap
- Restricted Implementations of Transformation Routines
- Variable Numbers of Coordinates
- Adapting a Transformation Routine to Individual IntraMaps
- Simplifying IntraMaps
- Writing and Reading IntraMaps
- Managing Transformation Routines in Libraries
Producing Graphical Output (Plots)
- The Plot Model
- Plotting Symbols
- Plotting Geodesic Curves
- Plotting Curves Parallel to Axes
- Plotting Generalized Curves
- Clipping
- Using a Plot as a Mapping
- Using a Plot as a Frame
- Regions of Valid Physical Coordinates
- Plotting Borders
- Plotting Text
- Plotting a Grid
- Controlling the Appearance of Sub-strings
- Producing Logarithmic Axes
- Choosing a Graphics Package
Compiling and Linking Software that Uses AST
- Accessing AST Include Files
- Linking with AST Facilities
- Building ADAM Applications that Use AST
The AST Class Hierarchy
AST Routine Descriptions
- AST_SET - Set attribute values for an Object
- 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_ADDPARAMETER - Add a new global parameter definition to a table
- 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_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_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_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_GETX - Get an attribute value for an Object
- AST_GETACTIVEUNIT - Determines how the Unit attribute will be used
- AST_GETCOLUMNDATA - Retrieve all the data values stored in a column
- AST_GETFITSX - 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_GETREFPOS - Return the reference position in a specified celestial coordinate system
- AST_GETREGIONBOUNDS - Returns the bounding box of Region
- AST_GETREGIONFRAME - Obtain a pointer to the encapsulated Frame 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_ISACLASS - 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 entries from one KeyMap into another
- AST_MAPGET0X - Get a scalar value from a KeyMap
- AST_MAPGET1X - Get a vector value from a KeyMap
- AST_MAPGETELEMX - 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_MAPPUT0X - Add a scalar value to a KeyMap
- AST_MAPPUT1X - Add a vector value to a KeyMap
- AST_MAPPUTELEMX - 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_MASKX - 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_NEGATE - Negate the area represented by a Region
- AST_NORM - Normalise a set of Frame coordinates
- AST_NORMMAP - Create a NormMap
- 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_OUTLINEX - 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_POINTLIST - Create a PointList
- 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_REBINX - Rebin a region of a data grid
- AST_REBINSEQX - 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_RESAMPLEX - 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_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_SETX - Set an attribute value for an Object
- AST_SETACTIVEUNIT - Specify how the Unit attribute should be used
- AST_SETFITSX - 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_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_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_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_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_ZOOMMAP - Create a ZoomMap
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
- AllWarnings - A list of all currently available condition names
- 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
- 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?
- 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
- FitsDigits - Digits of precision for floating point FITS values
- Font(element) - Character font for a Plot element
- 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
- 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
- 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
- MeshSize - Number of points used to represent the boundary of a Region
- MinAxes - Minimum number of Frame axes to match
- MinTick(axis) - Density of minor tick marks for a Plot
- MinTickLen(axis) - Length of minor tick marks for a Plot
- 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 Axis physical units
- 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?
- 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?
- SinkFile - Output file to which to data should be written
- 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
- 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 unexpeted 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?
- 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) - Axis physical units
- UnitRadius - SphMap input vectors lie on a unit sphere?
- UseDefs - Use default values for unspecified attributes?
- 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
- Zoom - ZoomMap scale factor
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
- 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
- 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
- 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
- ZoomMap - Zoom coordinates about the origin
UNIX Command Descriptions
- ast_link - Link a program with the AST library
- ast_link_adam - Link an ADAM program with the AST library
FITS-WCS Coverage
- Paper I - General Linear Coordinates
- Paper II - Celestial Coordinates
- Paper III - Spectral Coordinates
  - Requirements for a Successful Write Operation
  - Common Non-Standard Features
- Paper IV - Coordinate Distortions
  - The ``-SIP'' distortion code
Changes and New Features
- Changes Introduced in V1.1
- Changes Introduced in V1.2
- Changes Introduced in V1.3
- Changes Introduced in V1.4
- Changes Introduced in V1.5
- Changes Introduced in V1.6
- Changes Introduced in V1.7
- Changes Introduced in V1.8-2
- Changes Introduced in V1.8-3
- Changes Introduced in V1.8-4
- Changes Introduced in V1.8-5
- Changes Introduced in V1.8-7
- Changes Introduced in V1.8-8
- Changes Introduced in V1.8-13
- Changes Introduced in V2.0
- Changes Introduced in V3.0
- Changes Introduced in V3.1
- Changes Introduced in V3.2
- Changes Introduced in V3.3
- Changes Introduced in V3.4
- Changes Introduced in V3.5
- Changes Introduced in V3.6
- Changes Introduced in V3.7
- Changes Introduced in V4.0
- Changes Introduced in V4.1
- Changes Introduced in V4.2
- Changes Introduced in V4.3
- Changes Introduced in V4.4
- Changes Introduced in V4.5
- Changes Introduced in V4.6
- Changes Introduced in V5.0
- Changes Introduced in V5.1
- Changes Introduced in V5.2
- Changes Introduced in V5.3
- Changes Introduced in V5.3-1
- Changes Introduced in V5.3-2
- Changes Introduced in V5.4-0
- Changes Introduced in V5.5-0
- Changes Introduced in V5.6-0
- ChangesIntroduced in V5.6-1
- Changes Introduced in V5.7-0
- Changes Introduced in V5.7-1
- Changes Introduced in V5.7-2
- Changes Introduced in V6.0
- Changes Introduced in V6.0-1
- Changes Introduced in V7.0.0
- Changes Introduced in V7.0.1
- Changes Introduced in V7.0.2
- Changes Introduced in V7.0.3
- Changes Introduced in V7.0.4
- Changes Introduced in V7.0.5
- Changes Introduced in V7.0.6
- Changes Introduced in V7.1.0
- Changes Introduced in V7.1.1
About this document ...

Next: Abstract

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
7th December 2012
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council

AST - A Library for Handling World Coordinate Systems in Astronomy

V7.1 Programmer's Guide (Fortran Version)

CCLRC / Rutherford Appleton Laboratory Particle Physics & Astronomy Research Council

Starlink Project

Contents

CCLRC / Rutherford Appleton Laboratory
Particle Physics & Astronomy Research Council