------------------------------------------------------------------------------
                                  WCSLIB 3.3
------------------------------------------------------------------------------
WCSLIB is a C library which implements the "World Coordinate System" (WCS)
convention in FITS (Flexible Image Transport System).

The convention, which has been adopted as a formal FITS standard, is described
in

   "Representations of world coordinates in FITS" (Paper I),
   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061-1075

and

   "Representations of celestial coordinates in FITS" (Paper II),
   Calabretta, M.R., & Greisen, E.W. 2002, A&A, 395, 1077-1122

WCSLIB also implements the proposed spectral coordinate convention

   "Representations of spectral coordinates in FITS" (Paper III),
   Greisen, E.W., Valdes, F.G., Calabretta, M.R., & Allen, S.L.
   A&A, (in preparation)

Reprints of Papers I, and II, and the draft of Paper III are available from

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

and

   http://www.aoc.nrao.edu/~egreisen/

Paper IV, "Representations of distortions in FITS world coordinate systems"
is also in preparation.

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

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



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

   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.

   prj.c        Implementation of the WCS spherical projections.
   prj.h        Header file for prj.c; contains the definition of the
                "prjprm" struct and function prototypes.

   sph.c        WCS spherical coordinate transformation routines.
   sph.h        Header file for sph.c.

   cel.c        Spherical projection driver routines.
   cel.h        Header file for cel.c; contains the definition of the
                "celprm" struct and function prototypes.

   spx.c        Low-level spectral conversion routines.
   spx.h        Header file for spx.c; contains the definition of the
                "spxprm" struct and function prototypes.

   spc.c        Implementation of the WCS spectral coordinates.
   spc.h        Header file for spc.c; contains the definition of the
                "spcprm" struct and function prototypes.

   wcs.c        High level WCS driver routines.
   wcs.h        Header file for wcs.c; contains the definition of the
                "wcsprm" struct and function prototypes.

   cylfix.c     Implementation of a function, cylfix(), which fixes WCS FITS
                header cards for malformed cylindrical projections.
   cylfix.h     Header file for cylfix.c.

   wcstrig.c    Implementation of trigonometric functions which deal with
                degrees rather than radians.
   wcstrig.h    Header file for wcstrig.c; contains function prototypes.
   wcsmath.h    Definition of mathematical constants used by WCSLIB.

C/test/
   tlin.c       Test closure of the linear transformation routines.
   tprj1.c      Test closure of the WCS projection routines.
   tprj2.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).
   tspx.c       Test closure of the spectral transformation routines.
   tspc.c       Test closure of the spectral transformation driver routines
                (requires PGPLOT and X11).
   twcs1.c      Test closure of wcss2p() and wcsp2s().
   twcs2.c      Test closure of wcsmix() (requires PGPLOT and X11).
   twcsprt.c    Tests printing of the wcsprm struct by wcsprt().

C/test_s/
   README       Describes usage of the scalar preprocessor macros for the
                lin.c, prj.c, and sph.c routines.
   tlin_s.c     Scalar version of tlin.c.
   tprj1_s.c    Scalar version of tprj1.c.
   tprj2_s.c    Scalar version of tprj2.c.
   tsph_s.c     Scalar version of tsph.c.



Usage
-----
Usage of the routines is described in detail in the prologue comments in
wcs.h, cel.h, sph.h, prj.h, spc.h, spx.h, and lin.h.

The main interface is via the high level wcsp2s(), wcss2p(), and wcsmix()
driver routines, although direct calls may sometimes be useful to celx2s() and
cels2x() described in cel.c, and linp2x() and linx2p() described in lin.h.

The various test programs are also intended to serve as programming templates
as well as demonstrations.


Caveats
-------
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", "celprm", "prjprm",
"spcprm", and "linprm") are also used to store intermediate values derived
from these parameters.  Particular members of the 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.

Service routines are provided to manage the various structs, including memory
allocation and initialization to default values, and it is advisable to use
these.  Refer to the header files for a detailed description.


Verification
------------
The tlin, tprj1, tsph, tspx, and tspc programs test closure of the linear
transformation routines, projection routines, spherical coordinate
transformation routines, and spectral coordinate transformation routines.

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

tprj1 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.  tprj1 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 (tprj1) 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 tprj2 and tcel which plot test grids for visual inspection of
scaling, orientation, and other macroscopic characteristics of the
projections.

twcs1 tests closure of wcss2p() and wcsp2s() 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.


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.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


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

$Id: README,v 3.3 2003/10/22 07:27:10 mcalabre Exp $
