[fitswcs] WCSLIB 7.6 releaed

Mark Calabretta mark at calabretta.id.au
Tue Apr 13 09:52:59 EDT 2021


Greetings,

WCSLIB 7.6 is now available:

  ftp://ftp.atnf.csiro.au/pub/software/wcslib/wcslib.tar.bz2

There are a number of new functions in this release, notably wcspcx()
and wcstrim(), as per the change log appended below.  A description of
the API for the two aforementioned functions is also appended.

The FITS WCS papers, WCSLIB (including the online manual), and related
resources are available from

  https://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html

Mark Calabretta



WCSLIB version 7.6 (2021/04/13)
-------------------------------

* C library

  - Bug fix in tabs2x() triggered for 1-dimensional coordinate lookup
    tables on axes > 1.  Reported by Mihai Cara.

  - In datfix(), don't return status 0 if no change was made (fix for
    change made at release 7.4).  Reported by Derek Homeier.

  - New function wcspcx() in the wcsfix suite regularizes the linear
    transformation component of a coordinate description to make it more
    human-readable.  It decomposes CDi_ja into PCi_ja and CDELTia in
    such a way that CDELTia forms meaningful scaling parameters, often
    leaving an orthogonal or near-orthogonal matrix.  Optionally, it can
    then permute rows of this matrix to unscramble axis permutations.

    A test header may be generated from wcspcx.keyrec for input to
    wcsware (not exercised as part of the standard test suite).

  - New function wcstrim() frees memory allocated by wcsinit() for
    arrays in a wcsprm struct that remain unused after the struct has
    been set up.

  - New functions wcssize(), auxsize(), tabsize(), linsize(), dissize(),
    celsize(), prjsize(), spcsize(), and wcserr_size() compute the total
    size of the relevant structs, including allocated memory.

  - In the C test suite, inserted a brief pause in tprj2 and tspc, which
    otherwise have now become a blur.

* Fortran wrappers

  - Added wrappers for wcspcx(), wcstrim(), wcssize(), auxsize(),
    tabsize(), linsize(), dissize(), celsize(), prjsize(), spcsize(),
    and wcserr_size().

* Utilities

  - Added -c, -cp, -C, and -Cp options to wcsware to apply wcspcx()
    in a variety of ways, -m to apply wcstrim(), and -z to report the
    total size of the wcsprm struct with a breakdown of the sizes of
    its constituent structs.

  - Fixed compiler warnings for sundazel (portability issue).

* Installation

  - Upped the required version of Flex to 2.6.0 (was 2.5.9).  Problems
    with Flex 2.5.39 reported by Derek Homeier.

    Also added '--disable-flex' as a new configure option to force the
    use of the pre-generated Flex sources.

------------------------------------------------------------------------------

* wcspcx() - regularize PCi_j
* ---------------------------
* wcspcx() "regularizes" the linear transformation matrix component of the
* coordinate transformation (PCi_ja) to make it more human-readable.
*
* Normally, upon encountering a FITS header containing a CDi_ja matrix,
* wcsset() simply treats it as PCi_ja and sets CDELTia to unity.  However,
* wcspcx() decomposes CDi_ja into PCi_ja and CDELTia in such a way that
* CDELTia form meaningful scaling parameters.  In practice, the residual
* PCi_ja matrix will often then be orthogonal, i.e. unity, or describing a
* pure rotation, axis permutation, or reflection, or a combination thereof.
*
* The decomposition is based on normalizing the length in the transformed
* system (i.e. intermediate pixel coordinates) of the orthonormal basis
* vectors of the pixel coordinate system.  This deviates slightly from the
* prescription given by Eq. (4) of WCS Paper I, namely Sum(j=1,N)(PCi_ja)² = 1,
* in replacing the sum over j with the sum over i.  Consequently, the columns
* of PCi_ja will consist of unit vectors.  In practice, especially in cubes
* and higher dimensional images, at least some pairs of these unit vectors, if
* not all, will often be orthogonal or close to orthogonal.
*
* The sign of CDELTia is chosen to make the PCi_ja matrix as close to the,
* possibly permuted, unit matrix as possible, except that where the coordinate
* description contains a pair of celestial axes, the sign of CDELTia is set
* negative for the longitude axis and positive for the latitude axis.
*
* Optionally, rows of the PCi_ja matrix may also be permuted to diagonalize
* it as far as possible, thus undoing any transposition of axes in the
* intermdiate pixel coordinate system.
*
* If the coordinate description contains a celestial plane, then the angle of
* rotation of each of the basis vectors associated with the celestial axes is
* returned.  For a pure rotation the two angles should be identical.  Any
* difference between them is a measure of axis skewness.
*
* The decomposition is not performed for axes involving a sequent distortion
* function that is defined in terms of CDi_ja, such as TPV, TNX, or ZPX, which
* always are.  The independent variables of the polynomial are therefore
* intermediate world coordinates rather than intermediate pixel coordinates.
* Because sequent distortions are always applied before CDELTia, if CDi_ja was
* translated to PCi_ja plus CDELTia, then the distortion would be altered
* unless the polynomial coefficients were also adjusted to account for the
* change of scale.
*
* wcspcx() requires the wcsprm struct to have been set up by wcsset(), and
* will invoke it if necessary.  The wcsprm struct is reset on return with an
* explicit call to wcsset().
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Given:
*   dopc      int       If 1, then PCi_ja and CDELTia, as given, will be
*                       recomposed according to the above prescription.  If 0,
*                       the operation is restricted to decomposing CDi_ja.
*
*   permute   int       If 1, then after decomposition (or recomposition),
*                       permute rows of PCi_ja to make the axes of the
*                       intermediate pixel coordinate system match as closely
*                       as possible those of the pixel coordinates.  That is,
*                       make it as close to a diagonal matrix as possible.
*                       However, celestial axes are special in always being
*                       paired, with the longitude axis preceding the latitude
*                       axis.
*
*                       All WCS entities indexed by i, such as CTYPEia,
*                       CRVALia, CDELTia, etc., including coordinate lookup
*                       tables, will also be permuted as necessary to account
*                       for the change to PCi_ja.  This does not apply to
*                       CRPIXja, nor prior distortion functions.  These
*                       operate on pixel coordinates, which are not affected
*                       by the permutation.
*
* Returned:
*   rotn      double[2] Rotation angle [deg] of each basis vector associated
*                       with the celestial axes.  For a pure rotation the two
*                       angles should be identical.  Any difference between
*                       them is a measure of axis skewness.
*
*                       May be set to the NULL pointer if this information is
*                       not required.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                         2: Memory allocation failed.
*                         5: CDi_j matrix not used.
*                         6: Sequent distortion function present.

------------------------------------------------------------------------------

* wcstrim() - Free unused arrays in the wcsprm struct
* ---------------------------------------------------
* wcstrim() frees memory allocated by wcsinit() for arrays in the wcsprm
* struct that remains unused after it has been set up by wcsset().
*
* The free'd array members are associated with FITS WCS keyrecords that are
* rarely used and usually just bloat the struct: wcsprm::crota, wcsprm::colax,
* wcsprm::cname, wcsprm::crder, wcsprm::csyer, wcsprm::czphs, and
* wcsprm::cperi.  If unused, wcsprm::pv, wcsprm::ps, and wcsprm::cd are also
* freed.
*
* Once these arrays have been freed, a test such as
=
=        if (!undefined(wcs->cname[i])) {...}
=
* must be protected as follows
=
=        if (wcs->cname && !undefined(wcs->cname[i])) {...}
=
* In addition, if wcsprm::npv is non-zero but less than wcsprm::npvmax, then
* the unused space in wcsprm::pv will be recovered (using realloc()).
* Likewise for wcsprm::ps.
*
* Given and returned:
*   wcs       struct wcsprm*
*                       Coordinate transformation parameters.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Null wcsprm pointer passed.
*                        14: wcsprm struct is unset.



More information about the fitswcs mailing list