WCSLIB contains C routines which implement the proposed "World Coordinate
System" (WCS) convention in FITS (Flexible Image Transport System).
This proposal is described in "Representations of Celestial Coordinates in
FITS" by Eric W. Greisen and Mark Calabretta.  A draft of this document is
available via anonymous ftp from fits.cv.nrao.edu:/fits/documents/wcs.


Manifest
--------
   Makefile     GNU makefile for installing WCSLIB
   README       This file.
   CHANGES      List of changes made since v1.0.

   wcs.c        High level WCS driver routines.
   wcs.h        Header file for wcs.c; contains the definition of the
                "wcsprm" struct and function prototypes.
   cel.c        Spherical projection driver routines.
   cel.h        Header file for cel.c; contains the definition of the
                "celprm" struct and function prototypes.
   sph.c        WCS spherical coordinate transformation routines.
   proj.c       Implementation of the WCS spherical projections.
   proj.h       Header file for proj.c; contains the definition of the
                "prjprm" struct and function prototypes.
   lin.c        Implementation of the WCS linear transformation.
   lin.h        Header file for lin.c; contains the definition of the
                "linprm" struct and function prototypes.
   wcstrig.c    Trigonometric functions which deal with degrees rather than
                radians.
   wcstrig.h    Header file for wcstrig.c; contains function prototypes.

   tlin.c       Test closure of the linear transformation routines.
   tproj1.c     Test closure of the WCS projection routines.
   tproj2.c     Plot test grids for each projection (requires PGPLOT and X11).
   tsph.c       Test closure of the WCS spherical coordinate transformation
                routines.
   tcel.c       Plot oblique test grids (requires PGPLOT and X11).
   twcs.c       Test WCS routines (requires PGPLOT and X11).
   tpgc.c       C interfaces to PGPLOT used by tproj2 and tcel.
   tpgf.f       FORTRAN interfaces to PGPLOT used by tproj2 and tcel.


Usage caveats
-------------
Usage of the routines is described in the prologue comments in wcs.c, cel.c,
sph.c, proj.c, and lin.c.  The main interface is via the high level wcsfwd(),
wcsrev(), and wcsmix() driver routines, although direct calls may sometimes be
useful to celfwd() and celrev() described in cel.c, and linfwd() and linrev()
described in lin.c.  The twcs.c, tcel.c and tlin test programs may be taken as
programming templates.

The routines use a simple mechanism to store intermediate values and thereby
save recomputing them on every call.  The structs which contain coordinate
transformation and projection parameters ("wcsprm", "linprm", "celprm" and
"prjprm") are also used to store intermediate values derived from the
parameters.  Particular members of these structs are flags which must be set
to zero when any of the parameters are set (or reset), thereby signalling that
the intermediate values need to be computed.  This mechanism also allows an
indefinite number of contexts to be maintained.

Note that while the FITS "LONGPOLE" and "LATPOLE" keywords assumes sensible
default values if omitted from the FITS header, this condition must be
signalled explicitly as described in the prologue to cel.c.


Nomenclature
------------
In WCSLIB the "forward" direction is from (lng,lat) celestial coordinates to
(x,y) coordinates in the plane of projection.  This accords with the notion
that spherical projections are a projection of the sphere onto a plane, the
"reverse" direction is therefore that of deprojection from plane to sphere.

Unfortunately, this is opposite to what is generally understood to be the
forward direction for FITS, namely that of transforming pixel coordinates to
world coordinates.  However, the ordering of function argument lists should
make it clear what is intended.


Installation notes
------------------
A GNU makefile is provided; GNU make (referred to below as gmake) must be
used.  A few variables are defined at the start of the makefile which you may
need to tailor for your purposes; instructions are given in the makefile
itself.  You should then be able to build 'libwcs_c.a' via

   gmake

A suite of test programs is also provided to verify the library.  You can
compile and exercise the test programs in one step via

   gmake test


Verification
------------
The tlin, tproj1 and tsph programs test closure of the linear transformation
routines, projection routines and spherical coordinate transformations.
"Closure" tests apply the forward and reverse transformations in sequence and
compare the result with the original value.  Ideally, the result should agree
exactly, but because of floating point rounding errors there is usually a
small discrepancy so it is only required to agree within a "closure
tolerance".

tproj1 tests for closure separately for longitude and latitude except at the
poles where it only tests for closure in latitude.  Note that closure in
longitude does not deal with angular displacements on the sky.  This is
appropriate for many projections such as the cylindricals where circumpolar
parallels are projected at the same length as the equator.  On the other hand,
tsph does test for closure in angular displacement.

The tolerance for reporting closure discrepancies is set at 1e-10 degree for
most projections; this is slightly less than 3 microarcsec.  The worst case
closure figure is reported for each projection and this is usually better than
the reporting tolerance by several orders of magnitude.  tproj1 and tsph test
closure at all points on the 1 degree grid of native longitude and latitude
and to within 5 degrees of any latitude of divergence for those projections
which cannot represent the full sphere.  Closure is also tested at a sequence
of points close to the reference point (tproj1) or pole (tsph).

Closure has been verified at all test points for SUN workstations.  However,
non-closure may be observed for other machines near native latitude -90 for
the zenithal, cylindrical and conic equal area projections (ZEA, CEA and COE),
and near divergent latitudes of projections such as the azimuthal perspective
and stereographic projections (AZP and STG).   Rounding errors may also carry
points between faces of the quad-cube projections (CSC, QSC, and TSC).
Although such excursions may produce long lists of non-closure points, this
is not necessarily indicative of a fundamental problem.

Note that the inverse of the COBE quad-qube projection (CSC) is a polynomial
approximation and its closure tolerance is intrinsically poor.

Although tests for closure help to verify the internal consistency of the
routines they do not verify them in an absolute sense.  This is partly
addressed by tproj2 and tcel which plot test grids for visual inspection of
scaling, orientation, and other macroscopic characteristics of the
projections.

The twcs test program verifies wcsmix() on the 1 degree grid of celestial
longitude and latitude for a number of selected projections.  It plots a test
grid for each projection and indicates the location of successful and failed
solutions.


Author
------
Mark Calabretta, Australia Telescope National Facility
mcalabre@atnf.csiro.au

$Id: README,v 2.1 1995/11/16 06:53:28 mcalabre Exp $
