Previous Up Next

Chapter 7   Celestial Coordinate System Routines

Two complimentary sets of routines are provided for calculating the transformation between pixel location in an image and the the corresponding celestial coordinates on the sky. These routines rely on a set of standard World Coordinate System (WCS) keywords in the header of the HDU which define the parameters to be used when calculating the coordinate transformation.

Both sets of routines require that a 2 step procedure be followed: first an initialization routine must be called to read the relevant WCS keywords in the header. These parameters are then passed to a pair of routines that convert from pixel to sky coordinates, or from sky to pixel coordinates. See Appendix B for the definition of the parameters used in these routines.

The first set of routines described below have the advantage that they are completely self-contained within the CFITSIO library and thus are guaranteed to be available on the system. These routines only support the most common types of map projections and WCS keyword conventions however.

The second set of routines are available in a WCS library written by Doug Mink at SAO. These routines are more powerful than the ones contained in CFITSIO itself because they support all the defined WCS map projections and they support a number of non-standard keyword conventions that have been adopted over the years by various different observatories. To use these routines, however, requires that a separate WCS library be built and installed on the system in addition to CFITSIO.

7.1   Self-contained WCS Routines

The following routines are included in the CFITSIO library to help calculate the transformation between pixel location in an image and the corresponding celestial coordinates on the sky. These support the following standard map projections: -SIN, -TAN, -ARC, -NCP, -GLS, -MER, and -AIT (these are the legal values for the coordtype parameter). These routines are based on similar functions in Classic AIPS. All the angular quantities are given in units of degrees.
1
Get the values of all the standard FITS celestial coordinate system keywords from the header of a FITS image (i.e., the primary array or an image extension). These values may then be passed to the routines that perform the coordinate transformations. If any or all of the WCS keywords are not present, then default values will be returned. If the first coordinate axis is the declination-like coordinate, then this routine will swap them so that the longitudinal-like coordinate is returned as the first axis.

If the file uses the newer 'CDj_i' WCS transformation matrix keywords instead of old style 'CDELTn' and 'CROTA2' keywords, then this routine will calculate and return the values of the equivalent old-style keywords. Note that the conversion from the new-style keywords to the old-style values is sometimes only an approximation, so if the approximation is larger than an internally defined threshold level, then CFITSIO will still return the approximate WCS keyword values, but will also return with status = APPROX_WCS_KEY, to warn the calling program that approximations have been made. It is then up to the calling program to decide whether the approximations are sufficiently accurate for the particular application, or whether more precise WCS transformations must be performed using new-style WCS keywords directly.
  int fits_read_img_coord / ffgics
      (fitsfile *fptr, > double *xrefval, double *yrefval,
       double *xrefpix, double *yrefpix, double *xinc, double *yinc,
       double *rot, char *coordtype, int *status)
2
Get the values of all the standard FITS celestial coordinate system keywords from the header of a FITS table where the X and Y (or RA and DEC) coordinates are stored in 2 separate columns of the table. These values may then be passed to the routines that perform the coordinate transformations.
  int fits_read_tbl_coord / ffgtcs
      (fitsfile *fptr, int xcol, int ycol, > double *xrefval,
       double *yrefval, double *xrefpix, double *yrefpix, double *xinc,
       double *yinc, double *rot, char *coordtype, int *status)
3
Calculate the celestial coordinate corresponding to the input X and Y pixel location in the image.
  int fits_pix_to_world / ffwldp
      (double xpix, double ypix, double xrefval, double yrefval,
       double xrefpix, double yrefpix, double xinc, double yinc,
       double rot, char *coordtype, > double *xpos, double *ypos,
       int *status)
4
Calculate the X and Y pixel location corresponding to the input celestial coordinate in the image.
  int fits_world_to_pix / ffxypx
      (double xpos, double ypos, double xrefval, double yrefval,
       double xrefpix, double yrefpix, double xinc, double yinc,
       double rot, char *coordtype, > double *xpix, double *ypix,
       int *status)

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)

Previous Up Next