[fitsbits] 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 fitsbits
mailing list