[fitsbits] WCSLIB 3.6

Greetings,

WCSLIB 3.6 is now available from http://www.atnf.csiro.au/~mcalabre.

Change notes are appended.

The main development in this release is a new function that extracts the
coordinate description for a subimage from a wcsprm struct. Rather than
describe it here I have appended the usage notes from wcs.h.

There have also been a few bug fixes, in particular for the FITS WCS
header parser that first appeared in WCSLIB 3.5.

Mark Calabretta
ATNF



WCSLIB version 3.6 (2004/08/25)
-------------------------------

* New service routine, wcssub() extracts the coordinate description for a
subimage from a wcsprm struct. wcscopy() is now implemented as a
preprocessor macro that invokes wcssub(). New test program, twcssub.c,
tests wcssub().

* In wcspih():

1) Fixed handling of string-valued keywords where the inline comment
contains a single-quote character (').

2) Fixed the address arithmetic for EPOCH and VELREF.

3) Translate VSOURCEa into ZSOURCEa if required.

4) Recognize SSYSSRCa.

5) Support free-format string keyvalues, as well as integer and floating-
point keyvalues; documented this in the prologue of wcshdr.h.

6) Allow header cards without inline comments.

7) Fixed function prototyping in wcspih.l (i.e. ANSI and non-ANSI forms were
potentially mixed).

8) Catch an unhandled newline character on the END card that was echoed
to stdout.

9) In error messages, print "ERROR" (uppercase) - POSIX standard.

* Modified wcs.cards to explain and test free-format keyvalues, and also
augmented the inline comment on illegal WCS cards that are to be rejected,
and WCS-like cards to be discarded. Added a header card with no inline
comment.

* Removed vsource from the wcsprm struct and added ssyssrc.

* In wcsini(), fixed a problem with memory management for wcs.pv when NPVMAX
is zero; likewise for wcs.ps and NPSMAX.

* In wcsprt(), don't print auxiliary coordinate system information in arrays
with zero address.

* In wcss2p(), status == 9 (one or more invalid world coordinates) was not
returned appropriately.

* Renamed twcs1.c to twcs.c, and twcs2.c to twcsmix.c.

* "Error status/code/number" is now referred to consistently as the "status
return value".

* Some vestiges of K&R C were removed: preprocessor definition of const, and
K&R function prototypes.

* Worked over the C, FORTRAN, and PGSBOX makefiles, in particular to make them
all consistent.





* Subimage extraction routine for the wcsprm struct; wcssub()
* -----------------------------------------------------------
* wcssub() extracts the coordinate description for a subimage from a wcsprm
* struct. It does a deep copy, using wcsini() to allocate memory for its
* arrays if required. Only the "information to be provided" part of the
* struct is extracted; a call to wcsset() is required to set up the
* remainder.
*
* The world coordinate system of the subimage must be separable in
* the sense that the world coordinates at any point in the subimage must
* depend only on the pixel coordinates of the axes extracted. In practice,
* this means that the PCi_ja matrix of the original image must not contain
* non-zero off-diagonal terms that associate any of the subimage axes with
* any of the non-subimage axes.
*
* Given:
* alloc int If true, allocate memory for the crpix, etc. arrays
* in the destination (see "Memory allocation and
* deallocation below"). Otherwise, it is assumed that
* pointers to these arrays have been set by the caller
* except if they are null pointers in which case memory
* will be allocated for them regardless.
*
* wcssrc const struct wcsprm*
* Struct to extract from.
*
* Given and returned:
* nsub int*
* axes int[] Vector of length *nsub containing the image axis
* numbers to extract. Order is significant; axes[0] is
* the axis number of the input image that corresponds
* to the first axis in the subimage, etc.
*
* nsub (the pointer) may be set to zero, and so also
* may *nsub, to indicate the number of axes in the
* input image; the number of axes will be returned if
* nsub != 0. axes itself (the pointer) may be set to
* zero to indicate the first *nsub axes in their
* original order.
*
* Set both nsub and axes to zero to do a deep copy of
* one wcsprm struct to another.
*
* Subimage extraction by coordinate axis type may be
* done by setting the elements of axes[] to the
* following special preprocessor macro values:
*
* WCSSUB_LONGITUDE: Celestial longitude.
* WCSSUB_LATITUDE: Celestial latitude.
* WCSSUB_CUBEFACE: Quadcube CUBEFACE axis.
* WCSSUB_SPECTRAL: Spectral axis.
* WCSSUB_STOKES: Stokes axis.
*
* See note 2 below for further usage notes.
*
* On return, *nsub will contain the number of axes in
* the subimage; this may be zero if there were no axes
* of the required type(s) (in which case no memory will
* be allocated). axes[] will contain the axis numbers
* that were extracted. The vector length must be
* sufficient to contain all axis numbers. No checks
* are performed to verify that the coordinate axes are
* consistent, this is done by wcsset().
*
* wcsdst struct wcsprm*
* Struct describing the subimage. wcsdst-flag should
* be set to -1 if wcsdst was not previously initialized
* (memory leaks may result if it was previously
* initialized).
*
* Function return value:
* int Status return value:
* 0: Success.
* 1: Null wcsprm pointer passed.
* 2: Memory allocation failed.
* 12: Invalid subimage specification.
* 13: Non-separable subimage coordinate system.
*
*
* Copy routine for the wcsprm struct; wcscopy()
* ---------------------------------------------
* wcscopy() does a deep copy of one wcsprm struct to another. As of
* WCSLIB 3.6, it is implemented as a preprocessor macro that invokes
* wcssub() with the nsub and axes pointers both set to zero.

:
:

* 2) In wcssub(), combinations of subimage axes of particular types may be
* extracted in the same order as they occur the input image by combining
* preprocessor codes, for example
*
* *nsub = 1;
* axes[0] = WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL;
*
* would extract the longitude, latitude, and spectral axes in the same
* order as the input image. If one of each were present, *nsub = 3
* would be returned.
*
* For convenience, WCSSUB_CELESTIAL is defined as the combination
* WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.
*
* The codes may also be negated to extract all but the types specified,
* for example
*
* *nsub = 4;
* axes[0] = WCSSUB_LONGITUDE;
* axes[1] = WCSSUB_LATITUDE;
* axes[2] = WCSSUB_CUBEFACE;
* axes[3] = -(WCSSUB_SPECTRAL | WCSSUB_STOKES);
*
* The last of these specifies all axis types other than spectral or
* Stokes. However, as extraction is done in the order specified by
* axes[] a longitude axis (if present) would be extracted first (via
* axes[0]) and not subsequently (via axes[3]). Likewise for the
* latitude and cubeface axes in this example.
*
* From the foregoing, it is apparent that the value of *nsub returned
* may be less than or greater than that given. However, it will never
* exceed the number of axes in the input image.