Next:
Introduction
This is the C version of this document.
For the Fortran version, please see SUN/210sun210.
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
Changing Attributes of a Mapping
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
ss_specframesSpectral 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
Aligning Dual-Sideband Spectra
ss_timeframesTime 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
MaxTranSimplifying 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
AST Attribute Descriptions
AST Class Descriptions
UNIX Command Descriptions
AST Memory Management and Utility Functions
FitsWcsCoverageFITS-WCS Coverage
Paper I - General Linear Coordinates
Requirements for a Successful Write Operation
Use and Choice of CTYPE
i
keywords
Choice of Reference Point
Choice of Axis Ordering
Alternate Axis Descriptions
Paper II - Celestial Coordinates
Requirements for a Successful Write Operation
Choice of LONPOLE/LATPOLE
User Defined Fiducial Points
Common Non-Standard Features
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_featuresRelease Notes
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
Changes Introduced in V7.2.0
Changes Introduced in V7.3.0
Changes Introduced in V7.3.1
Changes Introduced in V7.3.2
Changes Introduced in V7.3.3
Changes Introduced in V7.3.4
Changes Introduced in V8.0.0
Changes Introduced in V8.0.1
Changes Introduced in V8.0.2
Changes Introduced in V8.0.3
Changes Introduced in V8.0.4
Changes Introduced in V8.0.5
Changes Introduced in V8.1.0
changeslist_of_most_recent_changesChanges Introduced in V8.2
Changes Introduced in V8.3
Changes Introduced in V8.4
Changes Introduced in V8.5
Changes Introduced in V8.6.2
Changes Introduced in V8.6.3
Changes Introduced in V8.7.0
Changes Introduced in V8.7.1
Changes Introduced in V8.7.2
Changes Introduced in V9.0.0
Changes Introduced in V9.0.2
Changes Introduced in V9.1.0
Changes Introduced in V9.1.2
Changes Introduced in V9.1.3
Changes Introduced in V9.2.0
Changes Introduced in V9.2.4
Changes Introduced in V9.2.5
Changes Introduced in V9.2.6
Changes Introduced in V9.2.7
changeslist_of_most_recent_changesChanges Introduced in V9.2.8
About this document ...