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)