SUN/210.30

Starlink Project
Starlink User Note 210.30

R.F. Warren-Smith & D.S. Berry

29th Jan 2021

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
C AST Attribute Descriptions
D AST Class Descriptions
E UNIX Command Descriptions
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

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