[fitsbits] WCSLIB 3.6

Mark Calabretta Mark.Calabretta at atnf.CSIRO.AU
Wed Aug 25 03:18:46 EDT 2004


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.





More information about the fitsbits mailing list