Differences between revisions 101 and 102
Deletions are marked like this. Additions are marked like this.
Line 110: Line 110:
The source code tar file for AST V9.2.3 is available [[https://github.com/Starlink/ast/releases/download/v9.2.3/ast-9.2.3.tar.gz|here]] (18 MB) ([[https://github.com/Starlink/ast/releases/tag/v9.2.3|release notes]]). To build it, do: The source code tar file for AST V9.2.4 is available [[https://github.com/Starlink/ast/releases/download/v9.2.4/ast-9.2.4.tar.gz|here]] (18 MB) ([[https://github.com/Starlink/ast/releases/tag/v9.2.4|release notes]]). To build it, do:
Line 113: Line 113:
 % tar -xzf ast-9.2.3.tar.gz
 % cd ast-9.2.3
 % tar -xzf ast-9.2.4.tar.gz
 % cd ast-9.2.4

AST - A Library for Handling World Coordinate Systems in Astronomy




  1. AST - What is it?

  2. AST Support for IVOA STC-S

  3. AST Support for STSci ASDF Format

  4. FITS-WCS Plotting Demo

  5. Documentation

  6. Obtaining AST

  7. Using AST from Python

  8. Using AST from Perl

  9. Using AST from Java

  10. Using AST from the UNIX shell

  11. Support for AST

AST - What is it?

The AST library provides a comprehensive range of facilities for attaching world coordinate systems to astronomical data, for retrieving and interpreting that information and for generating graphical output based on it. It's main selling points are:

  • Ease of use.
  • Facilities for generating plots of generalised non-linear, potentially discontinuous 2-D or 3-D coordinate systems, with detailed control of the appearance of the plot.
  • Facilities for converting transparently between different coordinate systems, including a wide range of celestial, spectral and time coordinate systems.
  • Facilities for searching a general collection of connected coordinate systems for a coordinate system with any given set of characteristics.
  • Allows code for handling WCS information to be written in a general way without regard to the specific nature of the coordinate systems being handled (i.e. whether they represent sky positions, spectral positions, focal plane positions, pixel positions, etc).
  • Flexible system for saving and retrieving WCS information, including (but not limited to) the STSci ASDF format, the IVOA STC-S format and a range of different popular FITS descriptions.

  • Flexible system for describing regions within any coordinate frame, including support for trhe IVOA MOC standard.

  • Written in C but has interfaces for C, Fortran, Python, Java (via JNI), Perl, and UNIX shell.
  • Extensive documentation.
  • LGPL licence.

AST is different to other popular FITS-based WCS packages in that it takes a very high level, generalised "object oriented" view of the problems of describing, using and storing WCS information. For this reason, it is very easy to use - it wraps up all the complications of dealing with the specifics of different classes of coordinate systems (celestial, spectral, pixel, etc). Another reason it is easy to use is that it hides completely the sometimes elaborate details of FITS WCS handling, and uses a completely FITS-independent and much cleaner interface more closely associated with the general nature of world coordinate information. However, it is possible to go both ways between AST and FITS (albeit the AST representations are much richer than the FITS and so some information may be lost in going from AST to FITS).

All coordinate systems are described by "Frame" objects which encapsulate information about the nature of the coordinate system - axis labels, units, how to convert axis values to and from text strings, how to "measure distance" within the Frame (the Frame metric), etc, etc. There are then subclasses of Frame which "know" about more specific coordinate systems - at the moment the three main subclasses are SkyFrame (which describes celestial positions on the sky), SpecFrame (which describes positions within a spectrum) and TimeFrame (which describes moments in time). All these classes can describe positions within their respective domains using all the common coordinate systems (various equatorial, ecliptic, galactic, etc for sky positions, wavelength frequency, various velocities, etc, for spectral, different timescales, etc, for time). They also know how to transform axis values between these systems. There is also a "compound Frame" class which allows any two Frames (of any class) to be joined together (for instance, you could compound a SkyFrame and a SpecFrame to describe a spectral cube). These various forms of Frame can be connected together using "Mappings". A Mapping is a mathematical recipe for transforming a position within one coordinate system into another. There are subclasses of Mapping which implement a wide range of different transformation. These include:

  • all the celestial projections and spectral algorithms described in FITS-WCS papers II & III,

  • classes which allows the caller to define their own transformations, either by providing a routine written in C or Fortran, or by providing a general algebraic fortran-like expression supplied in a text string.
  • classes for scaling, shifting, pin cushion distortion, spherical to Cartesian transformation, axis permutations, look-up table transformations, etc, etc.
  • a class which allows any two other Mappings to be combined together either in series or in parallel, to form a "compound Mapping". This allows Mappings of arbitrary complexity to be constructed using the other Mappings as components.

A "FrameSet" is a collection of Frames connected together by Mappings. A FrameSet can be created from a FITS header (for instance) using a single call. The FrameSet can then be used to transform positions between nominated coordinate systems, to convert axis values to and from text strings using formats automatically chosen to be appropriate to the class of Frame, to plot coordinate grids (using any graphics system you like), etc. FrameSets can be searched for Frames with particular characteristics.

FITS-WCS Plotting Demo

A WWW-based demo is available which allows you to enter a set of FITS-WCS headers and then produces an annotated coordinate grid using the facilities of the AST Plot class. Useful for exploring FITS-WCS as well as AST plotting options.

AST Support for STSci ASDF Format

AST contains a class called YamlChan that will convert between WCS stored in STSci's ASDF YAML-based format and AST. Note, currently the YamlChan class only supports celestial coordinate systems (i.e no spectral or time systems are supported).

Here are some examples programs that make use of the YamlChan class:

  • readasdf.c - This program reads WCS stored in ASDF format in a YAML file, creating an AST FrameSet from it. It then displays some basic information about the FrameSet. Here is an example.asdf ASDF file.

  • writeasdf.c - This program creates an AST FrameSet from a simple FITS-WCS header and then writes the FrameSet to an external YAML file using ASDF format.

AST Support for IVOA STC-S

AST contains a class called StcsChan that will convert between IVOA STC-S descriptions and AST Regions. A poster paper was presented on this at ADASS 2009.

A WWW-based demo is available which allows you to test STC-S regions for overlap, test points for inclusion in an STC-S region, and draw the boundary around an STC-S region.

Here are some examples programs that make use of the StcsChan class:

  • stcschan-demo1.c - This program reads an STC-S description from a disk file, and tests a given position to see if it is inside or outside the AstroCoordsArea specified by the STC-S description.

  • stcschan-demo2.c - This program reads a set of FITS-WCS headers from a text file, and writes an STC-S description of the region covered by the FITS file to standard output.

  • stcschan-demo3.c - This program reads an STC-S description from a text file, and also reads a set of 2-D spatial FITS-WCS headers from another (text) file. It then opens a specified PGPLOT graphics device, and displays an annotated coordinate grid covering the region described by the FITS headers. Finally, it draws the outline of the spatial extent of the STC-S description over the top of the annotated coordinate grid.

  • stcschan-demo4.c - This program reads two STC-S descriptions from two disk files, and tests them for overlap. The two descriptions need not refer to the same coordinate system. Built-in conversions within AST will be used to align them if the coordinate systems differ.

  • stcschan-demo5.c - This program reads two STC-S descriptions from two disk files, and writes a new STC-S description to standard output. The new STC-S covers the same region as the first STC-S, but expressed in the coordinate system of the second STC-S.


  • SUN/210 : The Fortran 77 interface (PDF)

  • SUN/211 : The C interface (PDF)

  • Python interface : Outline docs only - see SUN/211 for tutorial information and function details.

  • JNIAST : Javadocs only - see SUN/211 for tutorial information.

The AST library has been presented at various conferences over the past few years. For instance, see

Obtaining AST

AST is available pre-built as part of the Starlink Software Collection, which is now maintained by the East Asian Observatory, Hawaii.

The source for the current development version of AST can be viewed on github.

The source code tar file for AST V9.2.4 is available here (18 MB) (release notes). To build it, do:

 % tar -xzf ast-9.2.4.tar.gz
 % cd ast-9.2.4
 % ./configure --prefix=???
 % make 
 % make install

Replace the "???" string with the path to the directory in which you want AST to be installed

Using AST from Python

The Python interface was written by David Berry and Tim Jenness, and can be installed by doing "pip install starlink-pyast". You can also clone the github repository of you prefer.

Using AST from Perl

The Perl interface for AST was written by Tim Jenness and Brad Cavanagh of the Joint Astronomy Centre, Hilo, Hawaii, and Alasdair Allan of Starlink.

Using AST from Java

The Java JNI interface for AST was written by Mark Taylor and is contained in a package called JNIAST. The javadocs documentation for JNIAST is available here. JNIAST is available here, or can be obtained from the jniast directory within the StarJava Git repository.

Using AST from the UNIX shell

The Starlink Software Collection includes a package called ATOOLS that uses a command line interface similar to KAPPA, CCDPACK, etc. It contains one-to-one equivalents to the majority of the functions available in the AST library, allowing quick experiments to be performed from the shell, and providing access to the full power of AST from within shell scripts. Descriptions of AST objects may be stored in text files or in NDFs. There is currently no Starlink User Note describing ATOOLS, but the online help system (accessed using the ATOOLS command "atlhelp") describes how to use the commands.

Support for AST

The Starlink project became unfunded at the end of June 2005. However, the AST library continues to be supported by East Asian Observatory. Please contact David Berry (d.berry@eaobservatory.org).

Starlink: AST (last edited 2021-04-14 08:29:40 by DavidBerry)