Next: CIRSI Data Reduction System - CIRDR
Up: Software Systems and Tools
Previous: Perl at the Joint Astronomy Centre
Table of Contents - Subject Index - Author Index - Search - PS reprint - PDF reprint

Mink, D. J. 1999, in ASP Conf. Ser., Vol. 172, Astronomical Data Analysis Software and Systems VIII, eds. D. M. Mehringer, R. L. Plante, & D. A. Roberts (San Francisco: ASP), 498

WCSTools: An Image Astrometry Toolkit

Douglas J. Mink
Harvard-Smithsonian Center for Astrophysics


Very few people want to deal with the details of positional astronomy, but many astronomers want to know precise positions of objects in the sky. New instruments, such as fiber-fed spectrographs, require more precise positions than are available for many objects. WCSTools provides programs and subroutines which allow both scientists and programmers to access astrometric information using the world coordinate system (WCS) of an image. WCSTools programs translate between image and sky coordinates, list catalog stars in the area covered by an image, find stars in an image and list them with their sky positions, and fit a WCS by matching image objects to catalogs. SAOimage, SkyCat, and SAOtng use WCSTools subroutines to display sky coordinates while browsing an image. The software reads and writes FITS and IRAF .imh images and deals easily with Space Telescope and Digitized Sky Survey FITS images. The proposed FITS WCS standard is being tracked, and interim formats are being supported.

1. Introduction

An astronomical image world coordinate system (WCS) links each pixel in an astronomical image to a specific direction in the sky. Thus one can either find objects with known sky positions in an image or find the sky positions of objects discovered in an image. Spacecraft images, such as those from the Infrared Astronomy Satellite (IRAS) or the Hubble Space Telescope come with WCS information in their header. The images of the Digitized Sky Survey also come with WCS information. Using very large reference catalogs such as the HST Guide Star Catalog or the USNO-A Catalogs (Monet 1996), one can get enough stars to fit a fairly accurate WCS to almost any ground-based image using the imwcs program (Mink 1997).

What can you do with an image with a world coordinate system attached to it? You can work on specific applications, such as tracking each pixel's sky position as a cursor moves across an image browser (Mink 1996). Or you can make WCS information easy to use and find out what happens. WCSTools provides both modular subroutines and simple programs which provide straightforward access to world coordinate information to programmers and astronomers as transparently as possible. Subroutines need only a FITS or IRAF image header and coordinates to transform. Programs need only a FITS or IRAF image and coordinates.

2. Community-Driven Software

Given that a software package does something useful, there are two principles which need to be followed for it to be used by the astronomical community. It must be easy to use or adapt, that is it must have what Mandel & Murray (1998) called a ``minimal buy-in'', and it must work with real data, requiring adaptations by the package developer which could be called in a reciprocal term, ``sell-out''.

To make WCSTools subroutines easy to use, there are simple interfaces which require minimal information input-image headers and coordinates-and provide straightforward output: both formatted strings and binary numbers. Derived information is contained in a single data structure which can easily be passed between subroutines. In the most simple case, a subroutine user must read a FITS header, using their own subroutine or one included in this package, call wcsinit() to fill the WCS data structure, and call pix2wcs() or pix2wcst() for string output, to compute sky coordinates from image pixel coordinates or wcs2pix() to do the reverse.

As the WCSTools subroutines have been adopted as part of the SAOtng (Mandel 1997), its successor (as discussed by Joye & Mandel at this conference), and SkyCat (Albrecht et al. 1997) image browsers, many new features have been added at the request of the developers of those programs, and many bugs have been found by their users. Resolving these requests has taken a significant amount of the WCSTools developer's time, the aforementioned ``sell-out''. Spending that time, paid for by the developer's institution must be justified. Local use of the programs being developed elsewhere is one good reason to share code. More users find more bugs, the repair of which makes the programs more robust and thus more useful to everyone, including users at the developers institution.

The most difficult part of software development is to make it work with real data. WCSTools can read and write not only FITS image files, but IRAF .imh files, accessing most images made by astronomers. The image-reading subroutines can read the version 2 IRAF .imh files introduced in 1997 as well as version 1, and, unlike IRAF, can read images of either byte order on computers with either native byte order. The i2f program uses this capability to convert IRAF image files, no matter what their system of origin, to FITS files which can be more widely used.

To get WCS information out of as many kinds of images as possible, the WCSTools package supports 30 map projections, including the 8 AIPS projections (-SIN, -TAN, -ARC, -NCP, -GLS, -MER, -AIT, and -STG), 19 additional projections proposed as FITS WCS standards by Griesen & Calabretta (1996), the plate projection used by the Digitized Sky Survey, and IRAF and SAO polynomial projections. If no other WCS is present in the header, an approximate tangent plane projection WCS is created with the tangent point at the center of the image using the RA and DEC specified in the header, and a plate scale in arcseconds per pixel given in the image header or on the command line. As soon as a FITS standard WCS polynomial is proposed, it will be included as an option.

3. Use as Script Components

WCSTools programs, including SAOimage, are meant to be run with all of their arguments on the command line, making it easy to use them with any scripting language. Like the subroutines, they require minimal input-image file names and coordinates-and provide output in ways which are easily transmitted to other programs.

The use of WCSTools programs in scripts is illustrated by two recent projects undertaken at the Center for Astrophysics to improve galaxy positions. The first was an attempt to make sure that our database of spectra had positions good to an arcsecond or so. A Unix shell script was written which read lists totaling several thousand file names, extracted right ascensions and declinations from their headers using WCSTools gethead, extracted a Digitized Sky Survey field centered on that position into a local FITS file, and displayed that image using SAOimage, where the new -f1, -f2, and -f3 commands were used to set actions to be performed when the F1, F2, and F3 keys were used. These actions either sent the cursor position to the WCSTools sethead program which reset the position in the archive spectrum file or added the file name to a list of problem files or files which had really bad positions.

A second project was to get accurate positions of galaxies for the Updated Zwicky Catalog (Falco et al. 1999). Many of these positions could be obtained by matching the original Zwicky Catalog against catalogs with positions which were known to be good enough, but a list of ambiguous Zwicky Catalog entries remained. Region files containing labeled shapes at image coordinates computed from the sky positions of cataloged objects in Digitized Sky Survey images centered on the supposed position of a galaxy were written by the WCSTools imcat program and displayed by SAOimage. Using the function key commands described in the previous example, the coordinates of the correct position were added to a list. Figure 1 shows part of an SAOimage display of one of these images.

Figure 1: A portion of an SAOimage display showing three galaxy positions from two catalogs.

4. Internet Access

WCSTools documentation, with many examples, is available on the World Wide Web at

A future release of WCSTools will also include Internet access to catalogs and images. Code to read the tab tables format used by SkyCat catalog servers is already incorporated into WCSTools.


Bill Joye, Allan Brighton, and Eric Mandel, who use my subroutines in their image browsers, have passed on their problem data to make my interpretations of real image headers more robust. Andreas Jaunsen has been patient while I fixed the bugs he found. Susan Tokarz, Emilio Falco, Norman Grogin, and Jan Kleyna have tested the catalog search and display programs and used them as tools to do science.


Albrecht, M. A., Brighton, A., Herlin, T., Biereichel, P., & Durand, D. 1997, in ASP Conf. Ser., Vol. 125, Astronomical Data Analysis Software and Systems VI, ed. G. Hunt & H. E. Payne (San Francisco: ASP), 333

Falco, E. E., et al. 1999, PASP, in press

Griesen, E. & Calabretta, M. 1996, A&A, submitted

Mandel, E. 1997, in ASP Conf. Ser., Vol. 125, Astronomical Data Analysis Software and Systems VI, ed. G. Hunt & H. E. Payne (San Francisco: ASP), 253

Mandel, E. & Murray, S. S. 1998, in ASP Conf. Ser., Vol. 145, Astronomical Data Analysis Software and Systems VII, ed. R. Albrecht, R. N. Hook, & H. A. Bushouse (San Francisco: ASP), 142

Mink, D. J. 1996, in ASP Conf. Ser., Vol. 101, Astronomical Data Analysis Software and Systems V, ed. G. H. Jacoby & J. Barnes (San Francisco: ASP), 249

\ibid, 1997, in ASP Conf. Ser., Vol. 125, Astronomical Data Analysis Software and Systems VI, ed. G. Hunt & H. E. Payne (San Francisco: ASP), 249

Monet, D. 1996, USNO-A1.0: A Catalog of Astrometric Standards, (Washington: USNO)

© Copyright 1999 Astronomical Society of the Pacific, 390 Ashton Avenue, San Francisco, California 94112, USA
Next: CIRSI Data Reduction System - CIRDR
Up: Software Systems and Tools
Previous: Perl at the Joint Astronomy Centre
Table of Contents - Subject Index - Author Index - Search - PS reprint - PDF reprint