------------------------------------------------------------------------------
                            WCSLIB (FORTRAN suite)
------------------------------------------------------------------------------
WCSLIB consists of independent FORTRAN and C 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 Calabretta and Eric W. Greisen, a draft of which is available
from

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

or

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

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.f        High level WCS driver routines.
   cel.f        Spherical projection driver routines.
   sph.f        WCS spherical coordinate transformation routines.
   proj.f       Implementation of the WCS spherical projections.
   lin.f        Implementation of the WCS linear transformation.
   wcstrig.f    Impementation of FORTRAN trigonometric functions
                which deal with degrees rather than radians (optional).

   tlin.f       Test closure of the linear transformation routines.
   tproj1.f     Test closure of the WCS projection routines.
   tproj2.f     Plot test grids for each projection (requires PGPLOT and
                X11).
   tsph.f       Test closure of the WCS spherical coordinate
                transformation routines.
   tcel.f       Plot oblique test grids (requires PGPLOT and X11).
   twcs1.f      Test closure of wcsfwd() and wcsrev().
   twcs2.f      Test closure of wcsmix() (requires PGPLOT and X11).


Usage caveats
-------------
Usage of the routines is described in the prologue comments in wcs.f, cel.f,
sph.f, proj.f and lin.f.  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.f, and LINFWD and LINREV
described in lin.f.  The twcs1.f, tcel.f and tlin.f 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 arrays which contain coordinate
transformation and projection parameters (WCS, LIN, CEL and PRJ) are also used
to store intermediate values derived from the parameters.  Particular elements
of these arrays serve as 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 assume sensible
default values if omitted from the FITS header, this condition must be
signalled explicitly as described in the prologue to cel.f.


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 subroutine 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.  In particular, if your FORTRAN compiler
does not provide the non-standard intrinsic functions COSD, SIND, TAND, ACOSD,
ASIND, ATAND, and ATAN2D then you will need to set the WCSTRIG variable as
described in the makefile (see note below).  You should then be able to build
'libwcs_f.a' via

   gmake

A suite of test programs is also provided to verify the library (see below).  
You can compile and exercise these 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.

Many FORTRAN compilers supply these as intrinsic functions and in such cases
the compiler will use them automatically since none of the routines declares
them EXTERNAL.  Otherwise, a separate file "wcstrig.f" contains
DOUBLE PRECISION implementations based on the standard FORTRAN trigonometric
functions.

Note that the routines explicitly declare these functions as DOUBLE PRECISION
in case the external implementations are used.  Where the implicit forms are
supplied by the compiler then, according to the ANSI X3.9-1978 FORTRAN
standard (p8-5), such declaration does not remove the generic properties of
the intrinsic functions.


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

$Id: README,v 2.4 1999/12/14 01:07:11 mcalabre Exp $
