Chapter 7 Celestial Coordinate System Routines
The FITS community has adopted a set of keyword conventions that are
used to specify the transformation that is needed to convert between
pixel locations in an image and the corresponding celestial coordinates
on the sky. or more generally, to specify world coordinates that
are to be associated with any pixel location in an n-dimensional FITS
array. CFITSIO is distributed with a simple set of World Coordinate
System routines that support a limited set of celestial projections.
These routines were derived from functions in the Classic AIPS software
package developed in the 1980s. These routines DO NOT support all the
new conventions in the WCS papers that have recently been approved as
part of the official FITS standard.
Rather than using the WCS routines distributed with CFITSIO, it is
STRONGLY RECOMMENDED that software developers use a more sophisticated
external WCS library. Several recommended libraries are:
WCSLIB - supported by Mark Calabretta
WCSTools - supported by Doug Mink
AST library - developed by the U.K. Starlink project
More information about the WCS keyword conventions and links
to all of these libraries can be found on the FITS Support Office
web site at http://fits.gsfc.nasa.gov under the WCS link.
Each of these libraries has a routine that will ingest a list of header
keywords from which the transformations between pixel coordinates and
world coordinates can be derived. The following CFITSIO routine may
be used to copy the keywords in any FITS header into a long character
string that can then be passed to the WCS library routine:
-
1
- Concatenate the header keywords in the CHDU into a single long
string of characters. Each 80-character fixed-length keyword
record is appended to the output character string, in order, with
no intervening separator or terminating characters. The last header
record is terminated with a NULL character. This routine allocates
memory for the returned character array, so the calling program must
free the memory when finished.
Selected keywords may be excluded from the returned character string.
If the second parameter (nocomments) is TRUE (nonzero) then any
COMMENT, HISTORY, or blank keywords in the header will not be copied
to the output string.
The 'exclist' parameter may be used to supply a list of keywords
that are to be excluded from the output character string. Wild card
characters (*, ?, and #) may be used in the excluded keyword names.
If no additional keywords are to be excluded, then set nexc = 0 and
specify NULL for the the **header parameter.
int fits_hdr2str
(fitsfile *fptr, int nocomments, char **exclist, int nexc,
> char **header, int *nkeys, int *status)
7.1 Self-contained WCS Routines
The following routines DO NOT support the more recent WCS conventions
that have been approved as part of the FITS standard. Consequently,
the following routines ARE NOW DEPRECATED. It is STRONGLY RECOMMENDED
that software developers not use these routines, and instead use an
external WCS library, as described in the previous section.
These routines are included only for backward compatibility with
existing software. They 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 the basic set of 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 fits_pix_to_world and fits_world_to_pix 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 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
(as in the Event List table format that is often used by high energy
astrophysics missions). These values may then be passed to the
fits_pix_to_world and fits_world_to_pix 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)