Next: Abstract

AST - A Library for Handling World Coordinate Systems in Astronomy

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

V7.1 Programmer's Guide (C Version)

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

(For the Fortran version of this document, please see SUN/210.)

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
- AST Objects within Multi-threaded Applications
  - Locking AST Objects for Exclusive Use
  - AST Pointer Contexts
- Copying Objects
- C Pointer Types
- Error Detection
- Sharing the Error Status
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 astConvert
- 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 Functions 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 Function
- Registering a Transformation Function
- Creating an IntraMap
- Restricted Implementations of Transformation Functions
- Variable Numbers of Coordinates
- Adapting a Transformation Function to Individual IntraMaps
- Simplifying IntraMaps
- Writing and Reading IntraMaps
- Managing Transformation Functions 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 the ``ast.h'' Header File
- Linking with AST Facilities
- Building ADAM Applications that Use AST
The AST Class Hierarchy
AST Function Descriptions
- astSet - Set attribute values for an Object
- astAddColumn - Add a new column definition to a table
- astAddFrame - Add a Frame to a FrameSet to define a new coordinate system
- astAddParameter - Add a new global parameter definition to a table
- astAngle - Calculate the angle subtended by two points at a third point
- astAnnul - Annul a pointer to an Object
- astAxAngle - Returns the angle from an axis, to a line through two points
- astAxDistance - Find the distance between two axis values
- astAxOffset - Add an increment onto a supplied axis value
- astBBuf - Begin a new graphical buffering context
- astBegin - Begin a new AST context
- astBorder - Draw a border around valid regions of a Plot
- astBoundingBox - Return a bounding box for previously drawn graphics
- astBox - Create a Box
- astChannel - Create a Channel
- astChannelData - Return a pointer to user-supplied data stored with a Channel
- astCircle - Create a Circle
- astCirclePars - Returns the geometric parameters of an Circle
- astClear - Clear attribute values for an Object
- astClearStatus - Clear the AST error status
- astClip - Set up or remove clipping for a Plot
- astClone - Clone (duplicate) an Object pointer
- astCmpFrame - Create a CmpFrame
- astCmpMap - Create a CmpMap
- astCmpRegion - Create a CmpRegion
- astColumnName - Get the name of the column at a given index within the Table
- astColumnNull - Get or set the null value for an integer column of a FITS table
- astColumnShape - Returns the shape of the values in a named column
- astColumnSize - Get the number of bytes needed to hold a full column of data
- astConvert - Determine how to convert between two coordinate systems
- astCopy - Copy an Object
- astCurrentTime - Return the current system time
- astCurve - Draw a geodesic curve
- astDSBSpecFrame - Create a DSBSpecFrame
- astDecompose - Decompose a Mapping into two component Mappings
- astDelFits - Delete the current FITS card in a FitsChan
- astDelete - Delete an Object
- astDistance - Calculate the distance between two points in a Frame
- astDownsize - Reduce the number of vertices in a Polygon
- astEBuf - End the current graphical buffering context
- astEllipse - Create a Ellipse
- astEllipsePars - Returns the geometric parameters of an Ellipse
- astEmptyFits - Delete all cards in a FitsChan
- astEnd - End an AST context
- astEscapes - Control whether graphical escape sequences are included in strings
- astExempt - Exempt an Object pointer from AST context handling
- astExport - Export an Object pointer to an outer context
- astFindFits - Find a FITS card in a FitsChan by keyword
- astFindFrame - Find a coordinate system with specified characteristics
- astFitsChan - Create a FitsChan
- astFitsTable - Create a FitsTable
- astFluxFrame - Create a FluxFrame
- astFormat - Format a coordinate value for a Frame axis
- astFrame - Create a Frame
- astFrameSet - Create a FrameSet
- astFromString - Re-create an Object from an in-memory serialisation
- astGenCurve - Draw a generalized curve
- astGetX - Get an attribute value for an Object
- astGetActiveUnit - Determines how the Unit attribute will be used
- astGetColumnData - Retrieve all the data values stored in a column
- astGetFitsX - Get a named keyword value from a FitsChan
- astGetFrame - Obtain a pointer to a specified Frame in a FrameSet
- astGetGrfContext - Return the KeyMap that describes a Plot's graphics context
- astGetMapping - Obtain a Mapping that converts between two Frames in a FrameSet
- astGetRefPos - Return the reference position in a specified celestial coordinate system
- astGetRegionBounds - Returns the bounding box of Region
- astGetRegionFrame - Obtain a pointer to the encapsulated Frame within a Region
- astGetRegionMesh - Return a mesh of points covering the surface or volume of a Region
- astGetRegionPoints - Returns the positions that define the given Region
- astGetStcCoord - Return information about an AstroCoords element stored in an Stc
- astGetStcNCoord - Return the number of AstroCoords elements stored in an Stc
- astGetStcRegion - Obtain a copy of the encapsulated Region within a Stc
- astGetTableHeader - Get the FITS headers from a FitsTable
- astGetTables - Retrieve any FitsTables currently in a FitsChan
- astGetUnc - Obtain uncertainty information from a Region
- astGrfPop - Restore previously saved graphics functions used by a Plot
- astGrfPush - Save the current graphics functions used by a Plot
- astGrfSet - Register a graphics function for use by a Plot
- astGrid - Draw a set of labelled coordinate axes
- astGridLine - Draw a grid line (or axis) for a Plot
- astGrismMap - Create a GrismMap
- astHasAttribute - Test if an Object has a named attribute
- astHasColumn - Returns a flag indicating if a column is present in a Table
- astHasParameter - Returns a flag indicating if a named global parameter is present in a Table
- astImport - Import an Object pointer to the current context
- astIntersect - Find the point of intersection between two geodesic curves
- astInterval - Create a Interval
- astIntraMap - Create an IntraMap
- astIntraReg - Register a transformation function for use by an IntraMap
- astInvert - Invert a Mapping
- astIsAClass - Test membership of a class by an Object
- astKeyMap - Create a KeyMap
- astLinearApprox - Obtain a linear approximation to a Mapping, if appropriate
- astLock - Lock an Object for exclusive use by the calling thread
- astLutMap - Create a LutMap
- astMapBox - Find a bounding box for a Mapping
- astMapCopy - Copy entries from one KeyMap into another
- astMapGet0X - Get a scalar value from a KeyMap
- astMapGet1X - Get a vector value from a KeyMap
- astMapGetElemX - Get a single element of a vector value from a KeyMap
- astMapHasKey - Check if an entry with a given key exists in a KeyMap
- astMapKey - Get the key at a given index within the KeyMap
- astMapLenC - Get the number of characters in a character entry in a KeyMap
- astMapLength - Get the vector length of an entry in a KeyMap
- astMapPut0X - Add a scalar value to a KeyMap
- astMapPut1X - Add a vector value to a KeyMap
- astMapPutElemX - Put a value into an element of a vector value in a KeyMap
- astMapPutU - Add an entry to a KeyMap with an undefined value
- astMapRegion - Transform a Region into a new Frame using a given Mapping
- astMapRemove - Removed a named entry from a KeyMap
- astMapRename - Rename an existing KeyMap entry
- astMapSize - Get the number of entries in a KeyMap
- astMapSplit - Split a Mapping up into parallel component Mappings
- astMapType - Get the data type of an entry in a KeyMap
- astMark - Draw a set of markers for a Plot
- astMaskX - Mask a region of a data grid
- astMatchAxes - Find any corresponding axes in two Frames
- astMathMap - Create a MathMap
- astMatrixMap - Create a MatrixMap
- astNegate - Negate the area represented by a Region
- astNorm - Normalise a set of Frame coordinates
- astNormMap - Create a NormMap
- astNullRegion - Create a NullRegion
- astOK - Test whether AST functions have been successful
- astOffset - Calculate an offset along a geodesic curve
- astOffset2 - Calculate an offset along a geodesic curve in a 2D Frame
- astOutlineX - Create a new Polygon outling values in a 2D data grid
- astOverlap - Test if two regions overlap each other
- astParameterName - Get the name of the global parameter at a given index within the Table
- astPcdMap - Create a PcdMap
- astPermAxes - Permute the axis order in a Frame
- astPermMap - Create a PermMap
- astPickAxes - Create a new Frame by picking axes from an existing one
- astPlot - Create a Plot
- astPlot3D - Create a Plot3D
- astPointList - Create a PointList
- astPolyCurve - Draw a series of connected geodesic curves
- astPolyMap - Create a PolyMap
- astPolyTran - Fit a PolyMap inverse or forward transformation
- astPolygon - Create a Polygon
- astPrism - Create a Prism
- astPurgeRows - Remove all empty rows from a table
- astPurgeWCS - Delete all cards in the FitsChan describing WCS information
- astPutCards - Store a set of FITS header cards in a FitsChan
- astPutChannelData - Store arbitrary data to be passed to a source or sink function
- astPutColumnData - Store new data values for all rows of a column
- astPutFits - Store a FITS header card in a FitsChan
- astPutTable - Store a single FitsTable in a FitsChan
- astPutTableHeader - Store new FITS headers in a FitsTable
- astPutTables - Store one or more FitsTables in a FitsChan
- astQuadApprox - Obtain a quadratic approximation to a 2D Mapping
- astRate - Calculate the rate of change of a Mapping output
- astRateMap - Create a RateMap
- astRead - Read an Object from a Channel
- astReadFits - Read cards into a FitsChan from the source function
- astRebinX - Rebin a region of a data grid
- astRebinSeqX - Rebin a region of a sequence of data grids
- astRemapFrame - Modify a Frame's relationship to other Frames in a FrameSet
- astRemoveColumn - Remove a column from a table
- astRemoveFrame - Remove a Frame from a FrameSet
- astRemoveParameter - Remove a global parameter from a table
- astRemoveRegions - Remove any Regions from a Mapping
- astRemoveRow - Remove a row from a table
- astRemoveTables - Remove one or more tables from a FitsChan
- astResampleX - Resample a region of a data grid
- astResolve - Resolve a vector into two orthogonal components
- astRetainFits - Indicate that the current card in a FitsChan should be retained
- astSame - Test if two AST pointers refer to the same Object
- astSelectorMap - Create a SelectorMap
- astSet - Set attribute values for an Object
- astSetX - Set an attribute value for an Object
- astSetActiveUnit - Specify how the Unit attribute should be used
- astSetFitsX - Store a keyword value in a FitsChan
- astSetFitsCM - Store a comment card in a FitsChan
- astSetFitsU - Store an undefined keyword value in a FitsChan
- astSetRefPos - Set the reference position in a specified celestial coordinate system
- astSetStatus - Set the AST error status to an explicit value
- astSetUnc - Store uncertainty information in a Region
- astShiftMap - Create a ShiftMap
- astShow - Display a textual representation of an Object on standard output
- astShowMesh - Display a mesh of points covering the surface of a Region
- astSimplify - Simplify a Mapping
- astSkyFrame - Create a SkyFrame
- astSkyOffsetMap - Returns a Mapping which goes from absolute coordinates to offset coordinates
- astSlaAdd - Add a celestial coordinate conversion to an SlaMap
- astSlaMap - Create an SlaMap
- astSpecAdd - Add a spectral coordinate conversion to a SpecMap
- astSpecFluxFrame - Create a SpecFluxFrame
- astSpecFrame - Create a SpecFrame
- astSpecMap - Create a SpecMap
- astSphMap - Create a SphMap
- astStatus - Obtain the current AST error status value
- astStcCatalogEntryLocation - Create a StcCatalogEntryLocation
- astStcObsDataLocation - Create a StcObsDataLocation
- astStcResourceProfile - Create a StcResourceProfile
- astStcSearchLocation - Create a StcSearchLocation
- astStcsChan - Create an StcsChan
- astStripEscapes - Remove AST escape sequences from a string
- astSwitchMap - Create a SwitchMap
- astTable - Create a Table
- astTableSource - Register a source function for accessing tables in FITS files
- astTest - Test if an Object attribute value is set
- astTestFits - See if a named keyword has a defined value in a FitsChan
- astText - Draw a text string for a Plot
- astThread - Determine the thread that owns an Object
- astTimeAdd - Add a time coordinate conversion to a TimeMap
- astTimeFrame - Create a TimeFrame
- astTimeMap - Create a TimeMap
- astToString - Create an in-memory serialisation of an Object
- astTran1 - Transform 1-dimensional coordinates
- astTran2 - Transform 2-dimensional coordinates
- astTranGrid - Transform a grid of positions
- astTranMap - Create a TranMap
- astTranN - Transform N-dimensional coordinates
- astTranP - Transform N-dimensional coordinates held in separate arrays
- astTune - Set or get an integer-valued AST global tuning parameter
- astTuneC - Set or get a character-valued AST global tuning parameter
- astUinterp - Perform sub-pixel interpolation on a grid of data
- astUkern1 - 1-dimensional sub-pixel interpolation kernel
- astUnformat - Read a formatted coordinate value for a Frame axis
- astUnitMap - Create a UnitMap
- astUnlock - Unlock an Object for use by other threads
- astVersion - Return the version of the AST library being used
- astWarnings - Returns any warnings issued by the previous read or write operation
- astWatch - Identify a new error status variable for the AST library
- astWcsMap - Create a WcsMap
- astWinMap - Create a WinMap
- astWrite - Write an Object to a Channel
- astWriteFits - Write out all cards in a FitsChan to the sink function
- astXmlChan - Create an XmlChan
- astZoomMap - 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 functions registered through astGrfSet?
- Grid - Draw grid lines for a Plot?
- GrismAlpha - The angle of incidence of the incoming light on the grating surface
- GrismEps - The angle between the normal and the dispersion plane
- GrismG - The grating ruling density
- GrismM - The interference order
- GrismNR - The refractive index at the reference wavelength
- GrismNRP - The rate of change of refractive index with wavelength
- GrismTheta - Angle between normal to detector plane and reference ray
- GrismWaveR - The reference wavelength
- ID - Object identification string
- IF - The intermediate frequency in a dual sideband spectrum
- Ident - Permanent Object identification string
- ImagFreq - The image sideband equivalent of the rest frequency
- Indent - Specifies the indentation to use in text produced by a Channel
- 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 function
- KeyMap - Store a set of key/value pairs
- LutMap - Transform 1-dimensional coordinates using a lookup table
- Mapping - Inter-relate two coordinate systems
- MathMap - Transform coordinates using mathematical expressions
- MatrixMap - Map coordinates by multiplying by a matrix
- 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
AST Memory Management and Utility Functions
- astAppendString - Append a string to another string which grows dynamically
- astCalloc - Allocate and initialise memory
- astChr2Double - read a double value from a string
- astChrCase - Convert a string to upper or lower case
- astChrLen - Determine the used length of a string
- astChrMatch - Case insensitive string comparison
- astChrMatchN - Case insensitive string comparison of at most N characters
- astChrSplit - Extract words from a supplied string
- astChrSplitC - Split a string using a specified character delimiter
- astChrSplitRE - Extract sub-strings matching a specified regular expression
- astChrSub - Performs substitutions on a supplied string
- astFree - Free previously allocated memory
- astFreeDouble - Free previously double allocated memory
- astGrow - Allocate memory for an adjustable array
- astIsDynamic - Returns a flag indicating if memory was allocated dynamically
- astMalloc - Allocate memory
- astMemCaching - Controls whether allocated but unused memory is cached in this module
- astRealloc - Change the size of a dynamically allocated region of memory
- astRemoveLeadingBlanks - Remove any leading white space from a string
- astSizeOf - Determine the size of a dynamically allocated region of memory
- astStore - Store data in dynamically allocated memory
- astString - Create a C string from an array of characters
- astStringArray - Create an array of C strings from an array of characters
- astStringCase - Convert a string to upper or lower case
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 211
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 (C Version)

CCLRC / Rutherford Appleton Laboratory Particle Physics & Astronomy Research Council

Starlink Project

Contents

CCLRC / Rutherford Appleton Laboratory
Particle Physics & Astronomy Research Council