7.2 WCS Routines that require the WCS library

The routines described in this section use the WCS library written by Doug Mink at SAO. This library is available at

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

You do not need the entire WCSTools package to use the routines described here. Instead, you only need to install the World Coordinate System Subroutine library. It is available from the ftp site as a gzipped .tar file (e.g., wcssubs-2.5.tar.gz) or as a zipped file (e.g., wcssub25.zip). Any questions about using this library should be sent to the author at dmink@cfa.harvard.edu.

The advantage of using the WCS library instead of the self-contained WCS routines described in the previous section is that they provide support for all currently defined projection geometries, and they also support most standard as well as many non-standard WCS keyword conventions that have been used by different observatories in the past. This library is also actively maintained so it is likely that it will support any new FITS WCS keyword conventions that are adopted in the future.

The first 3 routines described below are CFITSIO routines that create a character string array containing all the WCS keywords that are needed as input to the WCS library 'wcsinit' routine. These 3 routines provide a convenient interface for calling the WCS library routines from CFITSIO, but do not actually call any routines in the WCS library themselves.

1

Copy all the WCS-related keywords from the header of the primary array or an image extension into a single long character string array. The 80-char header keywords are simply concatenated one after the other in the returned string. The character array is dynamically allocated and must be freed by the calling program when it is no longer needed. In the current implementation, all the header keywords are copied into the array.

  int fits_get_image_wcs_keys / ffgiwcs
      (fitsfile *fptr, char **header, int *status)

2

Copy all the WCS-related keywords for a given pair of columns in a table extension into a single long character string array. The pair of columns must contain a list of the X and Y coordinates of each event in the image (i.e., this is an image in pixel-list or event-list format). The names of the WCS keywords in the table header are translated into the keywords that would correspond to an image HDU (e.g., TCRPXn for the X column becomes the CRPIX1 keyword). The 80-char header keywords are simply concatenated one after the other in the string. The character array is dynamically allocated and must be freed by the calling program when it is no longer needed.

  int fits_get_table_wcs_keys / ffgtwcs
      (fitsfile *fptr, int xcol, int ycol, char **header, int *status)

3

Copy all the WCS-related keywords for an image that is contained in a single vector cell of a binary table extension into a single long character string array. In this type of image format, the table column is a 2-dimensional vector and each row of the table contains an image. The names of the WCS keywords in the table header are translated into the keywords corresponding to an image (e.g., 1CRPn becomes the CRPIX1 keyword). The 80-char header keywords are simply concatenated one after the other in the string. The character array is dynamically allocated and must be freed by the calling program when it is no longer needed.

  int fits_get_imagecell_wcs_keys / ffgicwcs
      (fitsfile *fptr, int column, long row, char **header, int *status)

4

This WCS library routine returns a pointer to a structure that contains all the WCS parameters extracted from the input header keywords. The input header keyword string can be produced by any of the 3 previous routines. The returned WorldCoor structure is used as input to the next 2 WCS library routines that convert between sky coordinates and pixel coordinates. This routine dynamically allocates the WorldCoor structure, so it must be freed by calling the wcsfree routine when it is no longer needed.

  struct WorldCoor *wcsinit (char *header)

5

Calculate the sky coordinate corresponding to the input pixel coordinate using the conversion parameters defined in the wcs structure. This is a WCS library routine.

  void pix2wcs (struct WorldCoor *wcs, double xpix, double ypix,
        > double *xpos, double *ypos)

6

Calculate the pixel coordinate corresponding to the input sky coordinate using the conversion parameters defined in the wcs structure. The returned offscale parameter equals 0 if the coordinate is within bounds of the image. This is a WCS library routine.

  void wcs2pix (struct WorldCoor *wcs, double xpos, double ypos,
       > double *xpix, double *ypix, int *offscale)

7

Free the WCS structure that was created by wcsinit. This is a WCS library routine.

  void wcsfree(struct WorldCoor *wcs)