Overview of WCSLIB

WCSLIB is documented in the prologues of its header files which provide a detailed description of the purpose of each function and its interface (this material is, of course, used to generate the doxygen manual). Here we explain how the library as a whole is structured. We will normally refer to WCSLIB 'routines', meaning C functions or Fortran 'subroutines', though the latter are actually wrappers implemented in C.

WCSLIB is layered software, each layer depends only on those beneath; understanding WCSLIB first means understanding its stratigraphy. There are essentially three levels, though some intermediate levels exist within these:

• The top layer consists of routines that provide the connection between FITS files and the high-level WCSLIB data structures, the main function being to parse a FITS header, extract WCS information, and copy it into a wcsprm struct. The lexical parsers among these are implemented as Flex descriptions (source files with .l suffix) and the C code generated from these by Flex is included in the source distribution.
  • wcshdr.h,c – Routines for constructing wcsprm data structures from information in a FITS header and conversely for writing a wcsprm struct out as a FITS header.
  • wcspih.l – Flex implementation of wcspih(), a lexical parser for WCS "keyrecords" in an image header. A keyrecord (formerly called "card image") consists of a keyword, its value - the keyvalue - and an optional comment, the keycomment.
  • wcsbth.l – Flex implementation of wcsbth() which parses binary table image array and pixel list headers in addition to image array headers.
  • getwcstab.h,c – Implementation of a -TAB binary table reader in CFITSIO.
  
  A generic FITS header parser is also provided to handle non-WCS keyrecords that are ignored by wcspih():
  • fitshdr.h,l – Generic FITS header parser (not WCS-specific).
  
  The philosophy adopted for dealing with non-standard WCS usage is to translate it at this level so that the middle- and low-level routines need only deal with standard constructs:
  • wcsfix.h,c – Translator for non-standard FITS WCS constructs (uses wcsutrne()).
  • wcsutrn.l – Lexical translator for non-standard units specifications.
  
  As a concrete example, within this layer the CTYPEia keyvalues would be extracted from a FITS header and copied into the ctype[] array within a wcsprm struct. None of the header keyrecords are interpreted.
• The middle layer analyses the WCS information obtained from the FITS header by the top-level routines, identifying the separate steps of the WCS algorithm chain for each of the coordinate axes in the image. It constructs the various data structures on which the low-level routines are based and invokes them in the correct sequence. Thus the wcsprm struct is essentially the glue that binds together the low-level routines into a complete coordinate description.
  • wcs.h,c – Driver routines for the low-level routines.
  • wcsunits.h,c – Unit conversions (uses wcsulexe()).
  • wcsulex.l – Lexical parser for units specifications.
  
  To continue the above example, within this layer the ctype[] keyvalues in a wcsprm struct are analysed to determine the nature of the coordinate axes in the image.
• Applications programmers who use the top- and middle-level routines generally need know nothing about the low-level routines. These are essentially mathematical in nature and largely independent of FITS itself. The mathematical formulae and algorithms cited in the WCS Papers, for example the spherical projection equations of Paper II and the lookup-table methods of Paper III, are implemented by the routines in this layer, some of which serve to aggregate others:
  • cel.h,c – Celestial coordinate transformations, combines prj.h,c and sph.h,c.
  • spc.h,c – Spectral coordinate transformations, combines transformations from spx.h,c.
  
  The remainder of the routines in this level are independent of everything other than the grass-roots mathematical functions:
  • lin.h,c – Linear transformation matrix.
  • log.h,c – Logarithmic coordinates.
  • prj.h,c – Spherical projection equations.
  • sph.h,c – Spherical coordinate transformations.
  • spx.h,c – Basic spectral transformations.
  • tab.h,c – Coordinate lookup tables.
  
  As the routines within this layer are quite generic, some, principally the implementation of the spherical projection equations, have been used in other packages (AST, wcstools) that provide their own implementations of the functionality of the top and middle-level routines.
• At the grass-roots level there are a number of mathematical and utility routines.
  
  When dealing with celestial coordinate systems it is often desirable to use an angular measure that provides an exact representation of the latitude of the north or south pole. The WCSLIB routines use the following trigonometric functions that take or return angles in degrees:
  • cosd(), sind(), sincosd(), tand(), acosd(), asind(), atand(), atan2d()
  
  These "trigd" routines are expected to handle angles that are a multiple of returning an exact result. Some C implementations provide these as part of a system library and in such cases it may (or may not!) be preferable to use them. wcstrig.c provides wrappers on the standard trig functions based on radian measure, adding tests for multiples of .
  
  However, wcstrig.h also provides the choice of using preprocessor macro implementations of the trigd functions that don't test for multiples of (compile with -DWCSTRIG_MACRO). These are typically 20% faster but may lead to problems near the poles.
  • wcsmath.h – Defines mathematical and other constants.
  • wcstrig.h,c – Various implementations of trigd functions.
  • wcsutil.h,c – Simple utility functions for string manipulation, etc. used by WCSLIB.

Complementary to the C library, a set of wrappers are provided that allow all WCSLIB C functions to be called by Fortran programs, see below.

Plotting of coordinate graticules is one of the more important requirements of a world coordinate system. WCSLIB provides a PGPLOT-based subroutine, PGSBOX (Fortran), which handles general curvilinear coordinates via a user-supplied function - PGWCSL provides the interface to WCSLIB. A C wrapper, cpgsbox(), is also provided, see below.

Several utility programs are distributed with WCSLIB:

• wcsgrid extracts the WCS keywords for an image from the specified FITS file and uses cpgsbox() to plot a 2-D coordinate graticule for it. It requires WCSLIB, PGSBOX and CFITSIO.
• wcsware extracts the WCS keywords for an image from the specified FITS file and constructs wcsprm structs for each coordinate representation found. The structs may then be printed or used to transform pixel coordinates to world coordinates. It requires WCSLIB and CFITSIO.
• HPXcvt reorganises HEALPix data into a 2-D FITS image with HPX coordinate system. The input data may be stored in a FITS file as a primary image or image extension, or as a binary table extension. Both NESTED and RING pixel indices are supported. It uses CFITSIO.
• fitshdr lists headers from a FITS file specified on the command line, or else on stdin, printing them as 80-character keyrecords without trailing blanks. It is independent of WCSLIB.