[fitsbits] Primary & Alternate WCS Keyword Order

[Mark Calabretta]

On Tue 2012/06/26 11:22:23 MST, Steve Allen wrote

>On 2012 Jun 26, at 10:00, William Pence wrote:
>> Alternatively, why not just eliminate this requirement entirely, by 
>> deleting this sentence: "This keyword, if present, must precede all WCS 
>> keywords except NAXIS in the HDU."  What is the purpose and benefit of 
>> this requirement?
>
>I'm pretty sure I have some correspondence with Eric and Mark when
>that section of WCS paper 1 was being polished, but I'd have to
>go digging to see if this was mentioned.  I am hoping that Mark
>will chime in on this ordering requirement.

The intention was that WCSAXESa would precede all other keywords
for alternate descriptor 'a' so that a parser could allocate
memory for the coordinate description before the individual WCS
keywords were encountered.  The primary description is in no way
special in this regard, being just one of the 27 possible.

However, this is largely a crock because the very definition of
WCSAXESa thwarts this intent.  The problem lies in the fact that
its use is optional.  This is explained in the prologue of
wcspih.l, WCSLIB's image header parser:

  Use of the WCSAXESa keyword is not mandatory.  Its default
  value is "the larger of NAXIS and the largest index of these
  keywords [i.e. CRPIXj, PCi_j or CDi_j, CDELTi, CTYPEi, CRVALi,
  and CUNITi] found in the FITS header".  Consequently the
  definition of WCSAXESa effectively invalidates the use
  of NAXIS for determining the number of coordinate axes and
  forces a preliminary pass through the header to determine the
  "largest index" in headers where WCSAXESa was omitted.

  Furthermore, since the use of WCSAXESa is optional, there is
  no way to determine the number of coordinate representations
  (the "a" value) other than by parsing all of the WCS
  keywords in the header; even if WCSAXESa was specified for
  some representations it cannot be known in advance whether
  it was specified for all of those present in the header.

  Hence the definition of WCSAXESa forces the scanner to
  be implemented in two passes.  The first pass is used to
  determine the number of coordinate representations (up to
  27) and the number of coordinate axes in each.  Effectively
  WCSAXESa is ignored unless it exceeds the "largest index"
  in which case the keywords for the extra axes assume their
  default values.  The number of PVi_ma and PSi_ma keywords
  in each representation is also counted in the first pass.

By way of example, suppose that a header contained CTYPE4Z
as the last keyword before END, and that there were no other
WCS keywords for the 'Z' representation, not even WCSAXESZ.
Then a parser reading sequentially through the header would
not know that a 'Z' representation existed until it had scanned
the whole header.  All of the omitted WCS keywords for 'Z'
would then spring into existence assuming their default value.

Thus, if the software implements alternate representations as
an array of structs (as does WCSLIB), then it does not know how
many structs to allocate, nor their size, until the header has
been read to the end (nor indeed the number of PVi_ma nor PSi_ma
keywords).  Hence a parser has no option but to scan the header
twice, or else to use realloc() as each new representation is
discovered.  But if the parser uses realloc(), then the reason
for putting WCSAXESa first is removed anyway.

Hence, for the software, there is no reason to prefer an order
for WCSAXESa.

WCSAXESa's other role is in defining the number of coordinate
axes in cases where it is greater than NAXIS.  Degenerate axes
(i.e. with NAXISj = 1) have been used in radio images from the
early days of FITS to indicate that there are extra coordinate
axes.  See Sect. 7.4.3 of WCS Paper II for a non-trivial
example.  Although this long-standing usage was and still is
legal, it was argued that it could cause problems for some older
FITS readers which were unaware of this usage, and which were
unlikely ever to be modified to support the new WCS standard.
However, they would simply ignore a new keyword such as
WCSAXESa, so this could be used to record a number of coordinate
axes greater that NAXIS.  (Inevitably the older, unadapted
readers would make a mess of the new WCS, but at least they
could still read the array.)

On the other hand, extra coordinate axes can be defined simply
by writing at least one WCS keyword for the last axis.  Hence,
WCSAXESa is largely irrelevant.  The main thing is that parsers
must be able to accept that WCS keywords might exist for more
coordinate axes than indicated by NAXIS.

It might make sense for WCSAXESa to be less than NAXIS if there
are degenerate axes (which should come last), but it doesn't
make sense for WCSAXESa to be less than the number of non-
degenerate axes.

In general, for the benefit of human readers, it is better to
group all keywords for a particular representation together, as
is done in the examples given in the WCS papers.  That includes
WCSAXESa, if you think it's worth writing at all, and it would
be politer if it preceeded the other keywords for its
representation.

Regards,
Mark Calabretta