WCSTools: An Image Astrometry Toolkit, Douglas J. Mink (1998), presented at the Eighth Annual Conference on Astronomical Data Analysis Software and Systems (ADASS 98) in Urbana, Illinois in November 1998, published in Astronomical Data Analysis Software and Systems VIII, A.S.P. Conference Series, Vol. 172, 1999, Dave Mehringer, Ray Plante, Doug Roberts, eds., pp. 498-501.

WCSTools: An Image Astrometry Toolkit

Douglas J. Mink
Harvard-Smithsonian Center for Astrophysics

Abstract

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.

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 and 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 \it wcsinit() \rm to fill the WCS data structure, and call \it pix2wcs() \rm or \it pix2wcst() \rm for string output, to compute sky coordinates from image pixel coordinates or \it wcs2pix() \rm to do the reverse.

As the WCSTools subroutines have been adopted as part of the SAOtng (Mandel 1997), its successor (Joye and Mandel 1998), 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 devleoped 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 and 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.

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 totalling 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 labelled shapes at image coordinates computed from the sky positions of catalogued 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.

A portion of an SAOimage display showing three galaxy positions
from two catalogs

Internet Access

WCSTools documentation, with many examples, is available on the World Wide Web at http://tdc-www.harvard.edu/software/wcstools.

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.

Acknowledgements

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.

References

Albrecht, M. A., Brighton, A., Herlin, T., Durand, D., Biereichel, P. 1997, ADASS VI [full text]

Falco, E. E., Kurtz, M. J., Geller, M. J., Huchra, J. P., Peters, J., Berlind, P., Mink, D. J., Tokarz, S. P., & Elwell, B. 1999, PASP in press

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

Joye, W., & Mandel, E. 1999, ADASS VIII, paperref{P9.4}

Mandel, E. 1997, ADASS VI, 253

Mandel, E. & Murray, S. S. 1998, ADASS VII, 142

Mink, D. J. 1996, ADASS V, 96

Mink, D. J. 1997, ADASS VI, 249

Monet, D. 1996, "USNO-A1.0: A catalog of astrometric standards" Washington DC: U.S. Naval Observatory, 10 CDROMs.