----------------------------------------------------------------------------
----------------------------------------------------------------------------
-----------------



WCSTools: Putting Image World Coordinate Systems to Use



Douglas J. Mink



Abstract



WCSTools is a set of programs and a library of utility subroutines, written
in portable C, for setting and using the

world coordinate system (WCS) of a FITS or IRAF image. The WCS is 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. A single 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 central program, IMWCS, is based on earlier work presented by Elwood
Downey and Robert Mutel of the

University of Iowa at the 1995 ADASS Conference. It has been written to
automatically find stars in an image,

match them to a reference catalog, and fit a WCS to the image. Many of these
individual functions are available

separately: IMSTAR lists the stars in an image, with sky coordinates if a
WCS exists in the image header; IMGSC

lists stars from the HST Guide Star Catalog CDROMs which are found in the
area defined by an image WCS; and

IMUJC lists stars from the USNO J Catalog found in such an image-defined
area. XY2SKY and its inverse,

SKY2XY, convert pixel coordinates to sky coordinates and sky coordinates to
pixel coordinates for an image with

a WCS defined in its header. 



These programs can be used in combination. If a CCD image has too few Guide
Stars in it for a good WCS fit,

IMSIZE can output the area covered by the image in a format which can be
read by the GETIMAGE program to

extract a Digitized Sky Survey image. IMSTAR can be used to generate a
catalog of stars in that image and their

positions which can then be used by IMWCS as a reference catalog to set the
world coordinate system of the

image. 



Source code and online documentation for this library are available at URL

http://tdc-www.harvard.edu/software/wcstools.html. 



Presented at the Sixth Annual Conference on Astronomical Data Analysis
Software and Systems (ADASS

96) in Charlottesvile, Virginia in September 1996. 



----------------------------------------------------------------------------
----------------------------



Documentation
http://tdc-www.harvard.edu/software/wcstools.html

WCSTools Programs

delwcs.c
  Delete the WCS keywords from an image. If both EPOCH and EQUINOX are
  present, EQUINOX is also deleted. 
edhead.c
  Edit the header of a FITS file or the user parameters of an IRAF image file
  using a the text editor specified by the EDITOR environment variable.
gethead.c
  Return value(s) for specified keyword(s) from a file.
i2f.c
  Read two-dimensional IRAF image file and write FITS image file
imcat.c
  List sources from the HST Guide Star Catalog, the USNO UJ Catalog, or a
  tab-table catalog which should be found in the area of the sky covered
  by a specific image using its WCS.
imgsc.c
  List Guide Star Catalog sources which should be found in the area of
  the sky covered by a specific image using its WCS.
imhead.c
  Print FITS or IRAF header
imrot.c
  Rotate and/or reflect FITS or IRAF image files
imsize.c
  Print center and size of image using WCS keywords in header
imstar.c
  Find and list the n brightest stars in an IRAF or FITS image, with their
  sky coordinates if there is WCS information in the image header. 
imtab.c
  List sources from a tab-table catalog which should be found in the area of
  the sky covered by a specific image using its WCS.
imujc.c
  List USNH UJ Catalog sources which should be found in the area of
  the sky covered by a specific image using its WCS.
imwcs.c
  Automaticaly find stars in a FITS or IRAF image, match them to HST Guide
  or UJC Stars, compute the relation between sky coordinates and image
  coordinates, and write in in the image header. [after U of Iowa SETWCS]
scat.c
  Search the HST GSC, USNO UJC, or a local catalog given a region on the sky.
sethead.c
  Set header parameters in FITS or IRAF images.
sgsc.c
  Search the HST Guide Star Catalog given a region on the sky.
sky2xy.c
  Print image pixel coordinates for given sky coordinates on the command line
  or in a list file. 
skycoor.c
  Convert between J2000, B1950, and Galactic coordinates from the command line
or a file.
sujc.c
  Search the USNO UJ Catalog given a region on the sky.
xy2sky.c
  Print sky coordinates for given image pixel coordinates on the command line
  or in a list file.

WCS Subroutines in wcssubs and WCSTools libwcs

hget.c
  Subroutines to extract values from FITS headers by keyword.
  Subroutines for parsing RA and Dec strings are included.
hput.c
  Subroutines to implant values into FITS headers by keyword (and to
  delete headers).
platepos.c
  platepos() uses the WCS structure to compute sky coordinates given
  image pixel X and Y for images with Digitized Sky Survey plate solutions
  in their headers.  platepix() uses the WCS structure to compute image
  pixel X and Y given sky coordinates for DSS images.  Algorithms from
  StSCI CASB.
wcs.c
  Subroutines for using FITS or IRAF header spatial world coordinate
  system information.
wcscon.c
  Subroutines for converting between B1950, J2000, and galactic
  coordinates, based on Starlink SLA_LIB subroutines.
worldpos.c
  worldpos() uses the WCS structure to compute sky coordinates given
  image pixel X and Y for images with header information for any of 8
  standard world coordinate systems.  worldpix() uses the WCS structure
  to compute image pixel X and Y given sky coordinates for the same images.
  Mostly from NRAO.
*iraf2fits.c
  Convert IRAF oif (.imh) header to FITS header so identical keyword value
  extraction routines can be used.  This is only in wcssubs.tar, but an
  identical version is included in wcstools/imhio.c along with IRAF I/O
  subroutines and a FITS header to oif header conversion subroutine.
fitshead.h
  Declarations of FITS header and image access subroutines and FITS
  table data structure.
wcs.h
  Declaration of WCS data structure and useful conversions.


Other WCSTools libwcs Subroutines

findstar.c
  findStars() gets the location and brightest pixel of stars in the given
  image.  Included are subroutines to find and reject bright pixels and
  compute a star centroid.
fitsio.c
  FITS header and image reading and writing subroutines, including FITS
  table support.
fitswcs.c
  GetWCS() returns a WCS structure used by wcs.c subroutines from a FITS
  or IRAF .imh image, reading only the header.
  DelWCS() delete the WCS keywords in a FITS header.
gscread.c
  Return HST Guide Stars from standard CDROM format FITS table files for
  a given RA, Dec, and magnitude range.
imio.c
  Subroutines to get, put, and move pixels of various data types between images
  im memory and a program.
imrotate.c
  rotFITS() rotates an image by 90, 180, or 270 degrees, with an optional
  left-right reflection before the rotation.
imsetwcs.c
  setWCSFITS() uses findStars to find the stars in an image, gscread to
  find the Guide Stars in the nominal image region, and findRegisration or
  findCoords to fit plate-tangent WCS to the image.
irafio.c
  IRAF header and image reading and writing subroutines.  IRAF headers
  are converted to FITS headers for use by other programs and can be
  derived from FITS headers for writing.
matchstar.c
  StarMatch() takes a list of reference star positions and a list
  of object coordinates from an image and finds the image pixels
  which correspond to each of the reference stars.  It then uses these
  matches to get an image center, plate scale, and rotation.  The actual
  fit is based on the amoeba subroutine in Numerical Recipes, and all
  necessary subroutines are included.
platepos.c
  platepos() uses the WCS structure to compute sky coordinates given
  image pixel X and Y for images with Digitized Sky Survey plate solutions
  in their headers.  platepix() uses the WCS structure to compute image
  pixel X and Y given sky coordinates for DSS images.  Algorithms from
  StSCI CASB.
sortstars.c
  Subroutines to sort lists of stars by right ascension, magnitude, or flux
tabread.c
  Return stars from a tab table format catalog file for a given RA, Dec,
  and magnitude range.  Based on John Roll's Starbase format.
ujcread.c
  Return USNO UJ Catalog stars from its standard CDROM format files for
  a given RA, Dec, and magnitude range.

lwcs.h
  Parameters used by various libwcs subroutines