[fitsbits] programming interfaces for WCS defaults

[David Berry]

Steve,

> However in mentioning this I note yet another question that must be
> answered by UIs and APIs.  Suppose that a UI/API offers the option of
> choosing a WCS by the value of one of the WCSNAMEa cards, and suppose
> also that the application uses established, pre-WCS meanings for
> "physical", "logical", and/or "image" coordinates.  Then suppose that
> a FITS file author includes WCSNAMEa cards with those values.
> 
> How does a UI/API unambiguously offer the option, and how does it
> distinguish between the established, pre-WCS meaning of "logical" and
> the WCSNAMEa version with a value "logical"?
> 
> This question could be construed as a need to establish some reserved
> values for WCSNAMEa which have particular definitions, but that
> could be difficult if existing usages are inconsistent.

Rodney Warren-Smith and I put some thought into this a while back for the
Starlink AST subroutine library - how to identify a required coordinate
frame within a disparate collection of arbitrary coordinate frames, all
joined together by mappings. The solution we came up with has two parts; 
firstly, naming conventions, and secondly, a facility to allow the user
to specify a "template" coordinate frame and then to search through the
available frames to find one (or more) frames which match the template. In
this sense, I am thinking of a frame (or "a WCS" in FITS parlance) as
something which has a set of properties such as 

  - Name (e.g. from WCSNAME)
  - class (e.g. a "sky" frame if its CTYPE values conforms to paper II,
           or a "spectral" frame if it conforms to paper II,
           otherwise a "simple" frame - other classes could be defined)
  - Number of axes (e.g. from WCSAXES)
  
Specific classes may have extra properties. For instance, a sky frame
would also have properties for:

  - system ( FK4, FK5, ecliptic, galactic, etc)
  - equinox   
  - epoch

A spectral frame would have properties for standard of rest, rest frequency, 
etc.

So the user creates a frame to use as a template, and sets values for any
required properties. This template is then compared against each
available coordinate frame in turn looking for frames with the same
properties. Now (this is the trick), any properties which have not been
assigned a value in the template are used as "wild-cards", that is, they
match *any* value when the template is compared against a target frame.

That's the outline of it. We implemented this idea in AST some years
ago and it has turned out to be quiet succesfull. There are some extra
complications, like what to do if a template matches a frame except for
the order of the axes (that is, do you want to find a frame in which axis
1 is definately RA and axis 2 is definately DEC, or are you willing to
live with a frame in which they are the other way round). 

This system allows the user to locate a frame with given properties, but
there is still the question of how to distinguish between frames with
similar properties. For this, the only solution would seem to be to
establish naming conventions (e.g. for WCSNAME). One option is to adopt a
solution comparable with XML namespaces, in which the values assigned to
WCSNAME can have an optional prefix indicating the organisation which
provides the definition of the following frame name. So you may have

   WCSNAMEA = 'starlink.ac.uk:PIXEL'

which means the coordinate frame has name "PIXEL", as defined by 
starlink (our "PIXEL" cordinate system represents pixel offsets from a
specified origin which is not necessarily the bottom left pixel in the
image). On the other hand, another image may have

   WCSNAMEA = 'iraf.noao.edu:PIXEL'

This coordinate frame would also have name PIXEL, but this time it should
be interpreted using IRAF's definition of the PIXEL frame.

So when creating a template frame, the user could either; 1) leave the
frame name unspecified (i.e. match any frame name), 2) give an unqualified
name such as "PIXEL" requesting *any* PIXEL frame, or 3) give a fully
qualified name such as 'starlink.ac.uk:PIXEL'.

The relevant AST routines are AST_FINDFRAME (astFindFrame in C) and 
AST_CONVERT (astConvert in C), documented AST at: 

http://www.starlink.rl.ac.uk/star/docs/sun210.htx/sun210.html (Fortran)

and 

http://www.starlink.rl.ac.uk/star/docs/sun211.htx/sun211.html (C)

David