WCSTools 4.0:
Building Astrometry and Catalogs into Pipelines

Douglas Mink
Smithsonian Astrophysical Observatory


The WCSTools package was originally developed to create and access world coordinate systems in FITS image headers. In order to do that, programs and subroutines which access, modify, and extract information from FITS image headers and data, extract information from catalogs of sources, and manipulate sky, image, and time coordinates have been developed. Package functionality has always been available at both the subroutine level for developers of other packages, such as ds9, and at the scripting level for use in data processing pipelines. On the occasion of a major upgrade to the latest level of Mark Calabretta's WCSLIB library, lesser-known features, such as data and time format conversions and command line name to coordinate resolution will be presented.


The WCSTools package was originally created to add world coordinate systems to FITS astronomical images when it turned out that there weren't very many ground-based telescope optical images which could be matched against radio or spacecraft images. The basic functions of the package have been described in a series of papers by Douglas Mink in 1997, 1999, and 2002. The WCS projection capabilities of the package rest on Mark Calabretta's WCSLIB subroutines which implement the FITS-WCS standards laid out in Calabretta and Griesen 2002 and Griesen and Calabretta 2002. Over the past several years, Calabretta has rewritten his subroutines, but WCSTools has continued to use the old ones, which continued to work well almost all of the time.

In order to support features added in the spectral WCS paper (Griesen et al 2005), major upgrades have been made to WCSLIB, and WCSTools is being updated to interface with those modifications. Although these changes should be invisible to users, this seemed like a good time to point out some lesser-known features of WCSTools. The number of catalogs supported has continued to expand and the number of search modes have expanded. Coordinate conversion has always been present, but time conversions have been added. Manipulation of image data as well as image headers is possible, always with the intention of maintaining or improving the match of an images appearance to that of the sky. All of this functionality is available through subroutine calls as well as by command line invocation of the named programs.

Catalog Support

Originally, only the HST Guide Star Catalog was supported. Soon the need for WCS's for deeper, narrow field images led to the implementation of on-demand extraction of positions of sources from the Digitized Sky Survey. Since this process was rather time-consuming, deep all-sky catalogs have been supported since the USNO-A1.0. In WCStools, catalogs are supported in their native format through a single API. scat, which searches catalogs, imcat, which finds the catalog stars in the region defined by an images WCS, imwcs, which fits a WCS to an image, and immatch, which matches sources found in an image with a WCS to a catalog, all use a standard catalog interface.

Deep all-sky catalogs, used with recent epoch narrow field images, include the USNO-B1.0 Catalog (1,0366,366,767 stars, 83 Megabytes), GSC 2.2 Catalog (998,402,801 stars, over 80 Megabytes), 2MASS Point Source Catalog (470,992,970 stars, 32 Megabytes), and the USNO-A2.0 Catalog (526,280,881 stars, 6 Gigabytes). The GSC 2.2 catalog at the Space Telescope Science Institute can be accessed over the web by scat.

Astrometric catalogs with accurate proper motions include the UCAC2 Catalog (48,366,996 stars, 2 Gigabytes) and the Tycho-2 Catalog (2,539,913 stars, 529 Megabytes).

Photometric catalogs with accurate magnitudes across the sky include the 2MASS Point Source Catalog and Tycho-2 Catalog for the entire sky. For deep photometry in some parts of the sky, the Sloane Digital Sky Survey Photometry Catalog (53,000,000 sources) at SDSS can be accessed over web by scat.

Catalogs which are reasonably complete at bright end and work well for wide field images include the HST Guide Star Catalog (25,541,952 sources, 1.2 Gigabytes) the PPM Catalog (378,910 stars with proper motions, 22 Megabytes), and the SAO Catalog (258,996 stars with proper motions, 16 Megabytes).

Web access to the NASA Extragalactic Database (NED) and SIMBAD, now included with WCSTools, gives command line access to their vast catalogs of named objects, for example:

> nedpos m44
08:40:22.198 +19:40:19.43}

> simpos m44
08:40:24.000 +19:41:00.00 J2000}
You can convert coordinates, just as in scat access to any other catalog:
> nedpos -g m44
205.910635 +32.479519  Galactic}

> simpos -e m44
127.346995 +1.291450  Ecliptic}

Catalog Search Options

There are three ways scat can specify a search region on the sky, as shown in Figure 1:

cone search a circle on the sky, with center and radius specified
> scat -c ub1 -tn 10000 -r 900 10:00 85:00 J2000}
a square (or rectangle) on the sky, with center and half-side(s) specified
> scat -c ub1 -tn 10000 -r -900 10:00 85:00 J2000}
or as a rectangle in coordinates, with center and half-sides specified
> scat -c ub1 -tn 10000 -rr 900,900 10:00 85:00 J2000}

Time Conversion

As modern synoptic surveys of the sky begin and older surveys, such as the Harvard Plate Collection, are brought into the digital age, manipulation of times, their units and their formats has become more important. The getdate task converts time formats and systems. For example, the current time in FITS ISO format:
> getdate now2fd
can be converted to Julian Date
> getdate fd2jd 2005-09-30T17:49:53.000
or Modified Julian Date
> getdate fd2mjd 2005-09-30T17:49:53
Conversions between UTC, TT, and TAI are also possible.

Image Manipulation

WCSTools' imrot task performs simple 90, 180, and 270 degree rotations and both horizontal and vertical reflections without modifying pixel values. A common use of this task is to align multiple outputs of imaging detectors which are read out in different directions. The operation is also built into the imwcs task so that a WCS can be added to an input image no matter what its orientation returning an output image with north-up, east-left. Input image source catalogs, such as can be created using SExtractor (Bertin & Arnouts 1996), created from the input image, are also rotated and/or reflected just like the image. The getfits task extracts an arbitrary segment of an image while preserving the world coordinate system. Because the task is WCS-cognizant, the center of the region to be extracted can be specified by either the sky coordinates or image pixel coordinates. The original coordinates of the pixels of the image are preserved through an additional FITS WCS with a "P" suffix on the keywords.

Image Distortion

The proposed standard for dealing with distortion in FITS world coordinate systems is still in flux (Calabretta et al 2004), but the Spitzer Space Telescope needed a way to represent distortions in IRAC images, so they created a model based on the proposed standard in 2003 and it was implemented and tested in WCSTools before launch. Since images can be remapped by WCSTools' remap task from any supported projection into a more standard projection, such as plane tangent, the Spitzer pipeline uses that task to remap distorted images into a simpler WCS.

WCSTools Updates

Extensive online documentation, with examples for every task in the package is available at http://tdc-www.harvard.edu/software/wcstools/

To keep users informed about the status of the package, two email lists have been created:

To subscribe, email {\it majordomo@cfa.harvard.edu} with one of the following in the body of the message:
subscribe wcstools

subscribe wcstools-announce


Bertin, E. & Arnouts, S. 1996, Astronomy and Astrophysics Supplement,
117, 393 Calabretta. M.R. & Greisen, E.W. 2002, Astronomy and Astropyhsycs, 375, 1077
Calabretta. M.R., Valdes, F., Greisen, E.W., Allen, S.L., 2004, ADASS XIII, 551
Greisen, E.W. & Calabretta, M.R. 2002, Astronomy and Astrohysics, 375, 1061
Greisen, E.W, Calabretta, M.R., Valdes F., & Allen, S.L., 2005, accepted for publication in Astronomy and Astrophysics
Mink, D. 1997, ADASS VI, 249
Mink, D. 1999, ADASS VIII, 498
Mink, D. 2002, ADASS XI, 169