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

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


Manifest
--------
FORTRAN/
   Makefile     GNU makefile for installing the WCSLIB FORTRAN wrappers.
   README       This file.

   lin_f.c      FORTRAN wrappers for lin.c.
   lin.inc      FORTRAN include file for manipulating the "linprm" struct.

   prj_f.c      FORTRAN wrappers for prj.c.
   prj.inc      FORTRAN include file for manipulating the "prjprm" struct.

   sph_f.c      FORTRAN wrappers for sph.c.

   cel_f.c      FORTRAN wrappers for cel.c.
   cel.inc      FORTRAN include file for manipulating the "celprm" struct.

   spx_f.c      FORTRAN wrappers for spx.c.
   spx.inc      FORTRAN include file for manipulating the "spxprm" struct.

   spc_f.c      FORTRAN wrappers for spc.c.
   spc.inc      FORTRAN include file for manipulating the "spcprm" struct.

   wcs_f.c      FORTRAN wrappers for wcs.c.
   wcs.inc      FORTRAN include file for manipulating the "wcsprm" struct.

   cylfix_f.c   FORTRAN wrappers for cylfix.c.

test/
   tlin.f       FORTRAN analogue of tlin.c.
   tprj1.f      FORTRAN analogue of tprj1.c.
   tprj2.f      FORTRAN analogue of tprj2.c.
   tsph.f       FORTRAN analogue of tsph.c.
   tcel.f       FORTRAN analogue of tcel.c.
   tspx.f       FORTRAN analogue of tspx.c.
   tspc.f       FORTRAN analogue of tspc.c.
   twcs1.f      FORTRAN analogue of twcs1.c.
   twcs2.f      FORTRAN analogue of twcs2.c.
   twcsprt.f    FORTRAN analogue of twcsprt.c.


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 which
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, WCSCPY, WCSFREE, and WCSPRT which wrap
wcsini(), wcscpy(), 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, which define the
length of an INTEGER array which 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, twcsprt,
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.

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 = 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)

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

Note that the data type of 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 which 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 conveniently be done 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 3.1 2003/04/28 08:17:55 mcalabre Exp $
