AST - A Library for Handling World Coordinate Systems in Astronomy
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) a range of different popular FITS descriptions.
- 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 IVOA STC
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.
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
% tar -xzf ast-8.0.2.tar.gz % cd ast-8.0.2 % ./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
Using AST from Perl
Using AST from Java
The Java JNI interface for AST 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.