7. World Coordinate System Routines

The FITS community has adopted a set of keyword conventions that define the transformations needed to convert between pixel locations in an image and the corresponding celestial coordinates on the sky, or more generally, that define world coordinates that are to be associated with any pixel location in an n-dimensional FITS array. CFITSIO is distributed with a a few self-contained World Coordinate System (WCS) routines, however, these routines DO NOT support all the latest WCS conventions, so it is STRONGLY RECOMMENDED that software developers use a more robust 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 WCS libraries can be found on the FITS Support Office web site at http://fits.gsfc.nasa.gov under the WCS link.

The functions provided in these external WCS libraries will need access to the WCS keywords contained in the FITS file headers. One convenient way to pass this information to the external library is to use the fits_hdr2str routine in CFITSIO (defined below) to copy the header keywords into one long string, and then pass this string to an interface routine in the external library that will extract the necessary WCS information (e.g., the 'wcspih' routine in the WCSLIB library and the 'astFitsChan' and 'astPutCards' functions in the AST library).

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.

There are 2 related routines: fits_hdr2str simply concatenates all the existing keywords in the header; fits_convert_hdr2str is similar, except that if the CHDU is a tile compressed image (stored in a binary table) then it will first convert that header back to that of a normal FITS image before concatenating the keywords.

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 **exclist parameter.

  int fits_hdr2str
      (fitsfile *fptr, int nocomments, char **exclist, int nexc,
      > char **header, int *nkeys, int *status)

  int fits_convert_hdr2str / ffcnvthdr2str
      (fitsfile *fptr, int nocomments, char **exclist, int nexc,
      > char **header, int *nkeys, int *status)

2

The following CFITSIO routine is specifically designed for use in conjunction with the WCSLIB library. It is not expected that applications programmers will call this routine directly, but it is documented here for completeness. This routine extracts arrays from a binary table that contain WCS information using the -TAB table lookup convention. See the documentation provided with the WCSLIB library for more information.

  int fits_read_wcstab
       (fitsfile *fptr, int nwtb, wtbarr *wtb, int *status);