------------------------------------------------------------------------------
                                  WCSLIB 4.1
------------------------------------------------------------------------------
    WCSLIB 4.1 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2005, Mark Calabretta

    WCSLIB is free software; you can redistribute it and/or modify it under
    the terms of the GNU General Public License as published by the Free
    Software Foundation; either version 2 of the License, or (at your option)
    any later version.

    WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
    details.

    You should have received a copy of the GNU General Public License along
    with WCSLIB; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA
------------------------------------------------------------------------------

WCSLIB is a C library that implements the "World Coordinate System" (WCS)
convention in FITS (Flexible Image Transport System).  Refer to ../C/README.

This directory contains wrappers, written in C, that allow FORTRAN programs
to use WCSLIB.


USAGE
-----
A prerequisite for using these wrappers is an understanding of the usage of
the associated C routines, in particular the data structures they are based
on.  The principle difficulty in creating the wrappers was the need to manage
these C structs from within FORTRAN, all the moreso as they contain pointers
to allocated memory, pointers to C functions, and other structs that
themselves contain similar entities.

To this end, routines have been provided to set and retrieve values of the
various structs, for example WCSPUT and WCSGET for the wcsprm struct.  These
must be used in conjunction with wrappers on the routines provided to manage
the structs in C, for example WCSINI, WCSSUB, WCSCOPY, WCSFREE, and WCSPRT
which wrap wcsini(), wcssub(), wcscopy(), wcsfree(), and wcsprt().

The various *PUT and *GET routines are based on codes defined in FORTRAN
include files (*.inc) in this directory (if your FORTRAN compiler does not
support the INCLUDE statement then you will need to include these manually
wherever necessary).  Codes are defined as parameters with names like
WCS_CRPIX which refers to the "crpix" member of the wcsprm struct (if your
FORTRAN compiler does not support long symbolic names then you will need to
rename these).

The include files also contain parameters, such as WCSLEN, that define the
length of an INTEGER array that must be declared to hold the struct.  This
length may differ for different platforms depending on how the C compiler
aligns data within the structs.  A test program for the C library, twcs,
prints the size of the struct in sizeof(int) units and the values in the
FORTRAN include files must equal or exceed these.

The *PUT routines set only one element of an array at a time; the final one
or two integer arguments of these routines specify 1-relative array indices
(N.B. not 0-relative as in C).  The one exception is the pv array in prjprm.

The *PUT routines also reset the flag element to signal that the struct needs
to be reinitialized.  Therefore, if you wish to set the flag itself to -1
prior to the first call to WCSINI, for example, then that WCSPUT must be the
last one before the call.

The *GET routines retrieve whole arrays at a time and expect array arguments
of the appropriate length where necessary.  Note that they do not initialize
the structs.

A basic coding fragment is

      INTEGER   LNGIDX, STATUS
      CHARACTER CTYPE1*72

      INCLUDE 'wcs.inc'

*     WCSLEN is defined as a parameter in wcs.inc.
      INTEGER   WCS(WCSLEN)

*     Allocate memory and set default values for 2 axes.
      STATUS = WCSPUT (WCS, WCS_FLAG, -1, 0, 0)
      STATUS = WCSINI (2, WCS)

*     Set CRPIX1, and CRPIX2; WCS_CRPIX is defined in wcs.inc.
      STATUS = WCSPUT (WCS, WCS_CRPIX, 512D0, 1, 0)
      STATUS = WCSPUT (WCS, WCS_CRPIX, 512D0, 2, 0)

*     Set PC1_2 to 5.0 (I = 1, J = 2).
      STATUS = WCSPUT (WCS, WCS_PC, 5D0, 1, 2)

*     Set CTYPE1 to 'RA---SIN'; N.B. must be given as CHARACTER*72.
      CTYPE1 = 'RA---SIN'
      STATUS = WCSPUT (WCS, WCS_CTYPE, CTYPE1, 1, 0)

*     Set PV1_3 to -1.0 (I = 1, M = 3).
      STATUS = WCSPUT (WCS, WCS_PV, -1D0, 1, 3)

      etc.

*     Initialize.
      STATUS = WCSSET (WCS)

*     Find the "longitude" axis.
      STATUS = WCSGET (WCS, WCS_LNG, LNGIDX)

*     Free memory.
      STATUS = WCSFREE (WCS)

Refer to the various FORTRAN test programs for further programming examples.
In particular, twcs and twcsmix show how to retrieve elements of the celprm
and prjprm structs contained within the wcsprm struct.

Note that the data type of the third argument to the *PUT and *GET routines
may differ depending on the data type of the corresponding C struct member; be
it int, double, or char[].  It is essential that the FORTRAN data type match
that of the C struct for int and double types, and be a CHARACTER variable of
the correct length for char[] types.  Compilers (e.g. g77) may warn of
inconsistent usage of this argument but this can (usually) be safely ignored.

A basic assumption made by the wrappers is that an INTEGER variable is no less
than half the size of a DOUBLE PRECISION.


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 that you may
need to tailor for your purposes.

Being wrappers, the C routines here rely on the header files supplied with the
C library and these are presumed to reside in ../C.  By default, the wrappers,
whose names by common convention have an underscore ("_") suffix, are inserted
in the C library, ../C/libwcs.a.  If your C/FORTRAN compiler combination does
not use the underscore convention you may need to rename the wrapper
functions.  This may be done conveniently with a C preprocessor macro.

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

   gmake test

Please inform me of any difficulties you may have with the installation.


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

$Id: README,v 4.1 2005/08/27 07:48:21 cal103 Exp $
