Next: The SAOtng Programming Interface
Previous: Multiple World Coordinate Systems for DEIMOS Mosaic Images
Up: FITS-Flexible Image Transport System
Table of Contents - Index - PS reprint - PDF reprint

Astronomical Data Analysis Software and Systems VI
ASP Conference Series, Vol. 125, 1997
Editors: Gareth Hunt and H. E. Payne

WCSTools: Image World Coordinate System Utilities

Douglas J. Mink
Harvard-Smithsonian Center for Astrophysics, Cambridge, MA 02138, E-mail:



The WCSTools are portable C utility programs and subroutines for setting and using the world coordinate system (WCS) of a FITS or IRAF image. The WCS describes the relationship between sky coordinates, such as right ascension and declination, and image pixels, and can be described using standard keywords in an image header. The subroutine library is currently used by the image display and browsing programs SAOimage, SAOtng, and Skycat to translate between image pixels and sky coordinates. Some subroutines have been improved and new ones have been added to read and write all legal FITS image data types and to deal with IRAF .imh (OIF) files as easily as FITS files. The programs in this package set the WCS of an image, convert between pixel and sky coordinates in an image, and find catalog stars in the region of the sky which the image covers.


1. Introduction

After a means of translating image coordinates to sky coordinates was added to the SAOimage display program (Mink 1995), the same subroutine library was added to the SAOtng (Mandel 1994) and Skycat (Albrecht et al. 1997) image display programs. Users of these programs were then faced with the fact that world coordinate system (WCS) descriptions exist for only a few sets of data which optical astronomers routinely use: images from the Digitized Sky Survey, and spacecraft such as the Hubble Space Telescope and the Infrared Astronomy Satellite. Virtually no ground-based optical observatories add information to their image headers to translate pixel coordinates to sky coordinates.

Individual astronomers have used a variety of methods to match image stars with reference catalogs to set world coordinate systems for small sets of images. All widely-known methods required extensive user interaction until Elwood Downey reported (Downey & Mutel 1996) that the University of Iowa Automated Telescope Facility was automatically adding world coordinate system information to the header of each image it took. Immediately, steps were taken to apply his SETWCS program to data from telescopes used by astronomers at the Center for Astrophysics. As the Iowa software was adapted to deal with more types of images, a whole suite of portable utilities and subroutines was developed to set and use image world coordinate systems.

2. Setting World Coordinate Systems

The sequence of processes used in SETWCS was retained in the revised program, IMWCS:

  1. Read a FITS or IRAF image and its header;
  2. Find all stars in the image and sort them by brightness;
  3. Find all stars in a reference catalog in the region of the sky where the image header says the telescope is pointing and sort them by brightness;
  4. Match the reference stars to the image stars;
  5. Fit a standard WCS function to the matches;
  6. Add the WCS information to the image header;
  7. Write the revised image and header

While its overall structure was maintained, the program was modified extensively to handle all FITS image data types, access IRAF .imh (OIF) files as well as FITS files, use a standard WCS library, and handle a variety of reference catalogs. In addition to the HST Guide Star Catalog, the USNO A1.0 Catalog (Monet 1996), and user-generated reference catalogs in Starbase format (Roll 1996) may be used. Image stars are now sorted by integrated rather than peak flux. Instead of matching stars using a grid of possible offsets, each possible set of offsets between reference and image stars is checked, and the most common offset is used as an initial value for the fit. The WCS fit has been expanded to include plate scale and rotation angle, and many fixed parameters, such as tolerance for reference/image position matches can now be changed on the command line.

In one-third to one-half of the 10´×10´ images we used for testing, there were too few Guide Stars to fit a world coordinate system. Figure 1 shows such an image with only two HST Guide Stars, positioned according to a nominal WCS based on the telescope pointing direction and an assumed plate scale. To deal with this situation, the star-finding code in IMWCS was broken out into a new program, IMSTAR, which catalogs stars with positions from images with a known WCS, such as those created from the Digitized Sky Survey (DSS). The DSS thus serves as a giant catalog, the depth of which can be varied as needed by altering the parameters used by IMSTAR. To make it easier to obtain DSS images covering the same region as a telescope image, a new program, IMSIZE, was written. It translates pointing information from the telescope image to the format needed by the DSS GETIMAGE program to extract an image covering the correct region. Figure 2 shows the same image as Figure 1, after it was processed by IMWCS. The positions of the stars extracted from a DSS image of the same region of the sky are plotted as circles. Where it is available, the USNO A1.0 catalog, with 491,848,883 sources, can be used directly, instead of the extracted DSS catalog, to fit a WCS with similar accuracy.

Figure: An image with only two HST Guide Stars. Original PostScript figure (82kB).

Figure 2 shows the DSS stars found and fit to those in the image by IMWCS.

Figure: The same image with stars from the Digitized Sky Survey. Original PostScript figure (82kB).

3. Using World Coordinate Systems

In the process of testing IMWCS, it became apparent that many of the pieces of that program were useful in their own right. In addition to the IMSTAR star-finding program used above, separate programs to search the GSC, USNO A1.0, or user catalogs were written. IMCAT lists the stars in a specified catalog which can be found in the region specified by an image's WCS. SCAT searches a catalog over a region specified on the command line. XY2SKY and SKY2XY translate coordinate pairs from image pixel coordinates to sky right ascension and declination (or galactic latitude and longitude) and vice versa.

Several image manipulation programs were also developed. EDHEAD edits the header of a FITS or IRAF image using any UNIX text editor. IMHEAD lists the entire header of a FITS or IRAF image. GETHEAD and SETHEAD print and change, respectively, specified FITS or IRAF header parameters. I2F converts an IRAF .imh file to FITS. For all of these programs, the IRAF file may be of either binary byte order (Sun/HP or IBM PC/Dec).

Further information about this software and how to obtain it may be found on the WCSTools Web Page.


I am grateful to Elwood Downey for proving that this project was possible, and for sharing his code. Scott Kenyon patiently tested the WCS fitting program on hundreds of images until it worked all of the time. He also provided the image used as an illustration in this paper. Allan Brighton of ESO tested the WCS translation code on many kinds of images, enabling me to make it as general as possible.


Albrecht, M. A., Brighton, A., Herlin, T., Durand, D., & Biereichel, P. 1997, this volume

Downey, E. C., & Mutel, R. L. 1996, in Astronomical Data Analysis Software and Systems V, ASP Conf. Ser., Vol. 101, eds. G. H. Jacoby and J. Barnes (San Francisco, ASP), 109

Mandel, E., & Tody, D. 1995, in Astronomical Data Analysis Software and Systems IV, ASP Conf. Ser., Vol. 77, eds. R. A. Shaw, H. E. Payne & J. J. E. Hayes (San Francisco, ASP), 125

Monet, D. 1996, BAAS, 28, 905

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

Roll, J. 1996, in Astronomical Data Analysis Software and Systems V, ASP Conf. Ser., Vol. 101, eds. G. H. Jacoby and J. Barnes (San Francisco, ASP), 536

© Copyright 1997 Astronomical Society of the Pacific, 390 Ashton Avenue, San Francisco, California 94112, USA

Next: The SAOtng Programming Interface
Previous: Multiple World Coordinate Systems for DEIMOS Mosaic Images
Up: FITS-Flexible Image Transport System
Table of Contents - Index - PS reprint - PDF reprint