WCSTools 3.9.7

WCSTools is a set of software utilities, written in C, which create,
display and manipulate the world coordinate system of a FITS or IRAF
image, using specific keywords in the image header which relate pixel
position within the image to position on the sky.  Auxillary programs
search star catalogs and manipulate images.

To make the entire package, type

make all

This is version 3.9.7 of the WCSTools package developed by Jessica Mink
(jmink@cfa.harvard.edu) at the Smithsonian Astrophysical Observatory,
with significant code or algorithms from

Mark Calabretta of CSIRO (projection),
Bill Cotton of NRAO (projection),
Jesse Doggett and Rick White of StScI (DSS projection)
Elwood Downey of the University of Iowa (WCS fitting procedure),
John Roll of SAO (network access),
Jing Li of IPAC (SIP distortion),
Pat Wallace of Rutherford Appleton Laboratory, UK (coordinate conversion),
Frank Valdes of NOAO (support for NOAO's ZPX projection), and
Ed Los of HCO (support for Emmanuel Bertin's SCAMP distortion correction).

Bill Joye and Eric Mandel of SAO, Allan Brighton of ESO, and Jean-Baptiste
Marquette of the Institut d'Astrophysique de Paris, and David Shupe of IPAC
helped debug the subroutine library.
Norman Grogin, Scott Kenyon, Susan Tokarz, Dan Koranyi, Guillermo Torres,
Steve Willner, Gus Muensch, Ed Los and others of the CfA and Andreas Jaunsen
helped debug the astrometry programs.
Sergio Pascual of the Universidad Complutense de Madrid helped me get
all of the variables initialized.

The update history is in the NEWS file, but here is what is new:

Version 3.9.7 (April 26, 2022)
fileroot: Add -3 - -6 to drop more extensions (2021-07-02)
fixhead: New program based on cphead (2021-10-14)
getdate: Add -m option to output English month abbreviation, not number (2021-06-11)
getdate: Allow fractional day subtraction (and addition) with -s (2021-07-08)
getpix: Add -x argument to pull pixel values from the same extension of multiple files (2021-02-10)
getpix: Fix bug when reading filename(s) from command line (2021-03-17) 

catutil.c: If keyword is surrounded by brackets, keep them. (2021-07-06)
catutil.c: Move range and string-parsing subroutines to fileutil.c (2021-08-05)
catutil.c: Move polynomial-fitting to fileutil.c (2022-02-01)
dateutil.c: Add fd2mfd() to replace month number with month name (2021-06-11)
dateutil.c: Add hjd2lst() for rvtools. (2021-06-11)
dateutil.c: Add lt2mfd() for logging time in RVTools (2021-07-27)
fileutil.c: Add range, aget*, and polynomial subroutines from catutil.c (2021-08-31) 
fileutil.c: Add agetw() to get first space-less word from keyword=value string (2022-01-20)
fileutil.c: Separate subroutine list by topic at top of file (2022-01-20)
fileutil.c: Add putfilebuff() and agetl() (2022-02-01)
fileutil.c: Parse value strings using tokens in agets() (2022-02-02)
range.c: If keyword is surrounded by brackets, keep them. (2021-07-06)
webread.c: Include ctype.h, which is needed on some systems (2022-02-04)
webread.c: Add extra parentheses in if statement on line 642 (2022-02-04)

fitsfile.h: Move declarations of range, token, and ASCII file subroutines here
fitsfile.h: Add lt2mfd() to convert local time to ISO format with month name(2022-02-21)
fitsfile.h: Add putfilebuff(), aget*(), polynomial routines from fileutil.c (2022-01-31)
fitsfile.h: Add range, string parsing, and polynomial-fitting subroutine declarations (2022-02-02)
wcscat.h: Move range, string parsing, and polynomial-fitting subroutines to fitsfile.h (2022-02-02)

Documentation, with examples and installation directions, is on the
World Wide Web at



If the WCSTools package has proven useful in your work, please reference
at least one of the following papers. If you want to find out which is
most applicable, the full texts are available on the WCSTools web site at


The paper presented at ADASS in 1996 is the best published description
of the IMWCS world coordinate system fitting program: 
     "WCSTools: Putting Image World Coordinate Systems to Use",
     Douglas J. Mink, 1997, in Astronomical Data Analysis Software and
     Systems VI, A.S.P. Conference Series, Vol. 125. Edited by Gareth Hunt
     and H. E. Payne.
     San Francisco: Astronomical Society of the Pacific, pp. 249-252. 

The 1998 ADASS paper is the best published description of the other tools
in the WCSTools package, including SAOimage when used for WCS work: 
     "WCSTools: An Image Astrometry Toolkit",
     Douglas J. Mink, 1999, in Astronomical Data Analysis Software and
     Systems VIII A.S.P. Conference Series, Vol. 172.  Edited by Dave
     Mehringer, Ray Plante, and Doug Roberts.
     San Francisco: Astronomical Society of the Pacific, pp.  498-501. 

A paper presented at the 2001 ADASS conference describes how the
WCSTools package uses the web, among other new features:
     "WCSTools 3.0: More Tools for Image Astrometry and Catalog Searching",
     Douglas J. Mink, in Astronomical Data Analysis Software and Systems XI,
     A.S.P. Conference Series, Vol. 281, 2002. Edited by David
     Bohlender, Daniel Durand, and T.H. Handley.
     San Francisco: Astronomical Society of the Pacific, pp. 169-172.

This paper presented at the 2002 ADASS conference describes interesting
ways to use the SCAT program:
     "Federating Catalogs and Interfacing Them with Archives: A VO Prototype",
     Douglas J. Mink and Michael J. Kurtz, 2003, in Astronomical Data Analysis
     Software and Systems XII, A.S.P. Conference Proceedings, Vol. 295.
     Edited by Harry Payne, Robert Jedrzejewski, and Richard Hook.
     San Francisco: Astronomical Society of the Pacific, pp. 51-54.

To assist users in selecting the best catalog to use, we tested the accuracy of
the various catalogs one is likely to use with imwcs, showing how well it works
in a pipeline mode on 1728 images. This ADASS paper is an improved version of
our AAS/DDA paper, adding the UCAC2 catalog and emphasizing usefulness more than
     "A Comparison of Large All-Sky Catalogs",
     Douglas J. Mink, Warren R. Brown, and Michael J. Kurtz, 2004, in
     Astronomical Data Analysis Software and Systems XIII, A.S.P. Conference
     Proceedings, Vol. 314. Edited by Francois Oschenbein, Mark Allen,
     and Daniel Egret.
     San Francisco: Astronomical Society of the Pacific, pp. 141-144. 

Program Descriptions

addpix:    Add a constant value(s) to specified pixel(s)
bincat:    Bin a catalog into a FITS image in flux or number
char2sp:   Replace this character with spaces in output (default=_)
conpix:    Operate on all of the pixels of an image
cphead:    Copy keyword values between FITS or IRAF images
crlf:      Change CR's to newlines in text file (for imwcs, imstar logs)
delhead:   Delete specified keywords from FITS or IRAF image file headers
delwcs:    Delete the WCS keywords from an image
edhead:    Edit the header of a FITS or IRAF file
filename:  Drop directory from pathname, returning just the file name
filedir:   Drop filename from path name, returning directory path
fileroot:  Drop file name extension, returning path name without it
fixhead:   Clean up FITS or IRAF by removing excessive blank lines
getcol:    Extract specified fields from an space-separated ASCII table file
getdate:   Convert between two date formats
getfits:   Extract portion of a FITS file into a new FITS file, preserving WCS
gethead:   Return values for keyword(s) specified after filename
getpix:    Return value(s) of specified pixel(s)
gettab:    Extract values from tab table data base files
httpget:   Send contents returned from URL to standard output
i2f:       Read two-dimensional IRAF image file and write FITS image file
imcat:     List catalog sources in the area of the sky covered by an image.
imextract: Extract 1D file from 2D file or 2D file from 3D file
imfill:    Replace bad pixels in image files with 2-D Gaussian, mean, or median
imhead:    Print FITS or IRAF header
immatch:   Match catalog and image stars using the WCS in the image file.
imrot:     Rotate and/or reflect FITS or IRAF image files
imresize:  Block sum or average a file by integral numbers of columns and rows
imsize:    Print center and size of image using WCS keywords in header
imsmooth:  Filter FITS and IRAF image files with 2-D Gaussian, mean, or median
imstack    Stack 1-dimensional images into a 2-dimensional image
imstar:    Find and list stars in an IRAF or FITS image
imwcs:     Match FITS or IRAF image stars to catalog stars and fit a WCS
isdate:    Return 1 if argument is date as yyyy-mm-dd, 2 if yyyy.mmdd, else 0
isfits:    Return 1 if argument is a FITS file, else 0
isnum:     Return 1 if argument is an integer, 2 if it is floating point, else 0
isrange:   Return 1 if argument is a range of the format n1[-n2[xs]],...
keyhead:   Change keyword names in headers of FITS or IRAF images
newfits:   Create blank FITS files (dataless by default with BITPIX=0)
remap      Rebin an image from its current WCS to a new one
scat:      Search a source catalog given a region on the sky
sethead:   Set header keyword values in FITS or IRAF images
setpix:    Set specified pixel(s) to specified value(s)
simpos:    Return RA and Dec for object name(s) from SIMBAD, NED, and/or VizieR
sky2xy:    Print image pixel coordinates for given sky coordinates
skycoor:   Convert between J2000, B1950, galactic, and ecliptic coordinates
sp2char:   Replaces space in string with specified character (default=_)
subpix:    Subtract a constant value(s) from specified pixel(s)
sumpix     Total pixel values in row, column, or specified area
wcshead:   Print basic world coordinate system information for images
xy2sky:    Print sky coordinates for given image pixel coordinates

-Jessica Mink, SAO, 2022-04-26
-Jessica Mink, SAO, 2022-04-26