------------------------------------------------------------------------------
                               WCSLIB (C suite)
------------------------------------------------------------------------------
WCSLIB consists of independent C and FORTRAN implementations of the spherical
projections and coordinate transformations defined in the proposed "World
Coordinate System" (WCS) convention in FITS (Flexible Image Transport System).

The proposal is described in "Representations of Celestial Coordinates in
FITS" by Mark R. Calabretta and Eric W. Greisen, a draft of which is available
from

   http://www.atnf.csiro.au/~mcalabre

WCSLIB itself (i.e. this suite) can be obtained from

   ftp://ftp.atnf.csiro.au/pub/software/wcslib

mirrored at

   ftp://fits.cv.nrao.edu/fits/src/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.
   sph.h        Header file for sph.c.
   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).
   twcs1.c      Test closure of wcsfwd() and wcsrev().
   twcs2.c      Test closure of wcsmix() (requires PGPLOT and X11).


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 twcs1.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 "LONPOLE" 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.

twcs1 tests closure of wcsfwd() and wcsrev() for a number of selected
projections.  twcs2 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.


Trigonometric functions
-----------------------
The WCSLIB routines use the following trigonometric functions which take or
return angular arguments in degrees:

   cosd() sind() tand() acosd() asind() atand() atan2d()

These routines explicitly handle angles which are a multiple of 90 degrees
returning an exact result.

These functions are provided in wcstrig.c.  However, some C implementations
also provide them as part of a system library and in such cases it is usually
preferable to use the native versions.


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

$Id: README,v 2.5 2001/11/15 03:22:51 mcalabre Exp $
