Support for WCS trees

[dsberry]

Context:
There is an ongoing effort to allow interchange of WCS information between AST (the WCS system used by LSST) and gWCS. Folded into this is an attempt to produce an IVOA model for WCS interchange that is compatible with both AST and gWCS. The people involved in this effort are @stscicrawford, @nden, David Berry (AST) , Tim Jenness (LSST) and Mark Cresitello-Dittmar (IVOA). Whilst AST and gWCS have many similarities, one of the ways in which they differ is that gWCS uses a single linear chain of transforms and frames to represent a complete WCS, whereas AST can use multiple chains connected together into a tree. Many AST-based systems (including LSST) currently make use of this facility to allow multiple coordinate systems to be derived from a single "parent" coordinate system. This is like a generalised form of the "alternate axis" facility included in the FITS-WCS standard (paper I, section 2.5). One common use for instance is to record details of alternative pixel coordinates schemes (e.g. the pixel coordinates of a cut-out within some larger parent data array or the pixel coordinates within multiple CCDs in the same focal plane).

The AST<>gWCS conversion process needs to handle trees in some way. One option is to flatten the tree into an equivalent single chain when going from AST to gWCS. This approach has the disadvantage of potentially requiring the resulting chain to include inverted duplicates of transforms needed to backtrack up the tree in order to move between branches. This not only requires more storage but also reduces the accuracy of transformations due to a larger number of transforms being involved. Another option is just to copy over the main "trunk" of the tree, and ignore off-shoot branches. Obviously though a round-trip would potentially loose significant information using this option. A more speculative option is to extend ASDF/gWCS to include support for trees. This would clearly involve a serious amount of effort and is therefore not likely to happen any time soon. However, the group of people mentioned above are still interested in whether it could, in theory, be done.

An initial step could be to extend the definition of the ASDF wcs object in some backward-compatible way so that it can describe trees as well as single chains with minimal, if any, changes to gWCS. One suggestion is that the AST->gWCS converter could produce ASDF with the changes described below. The current version of gWCS would ignore all but the main trunk, but some future version of gWCS could potentially use the extra information in the tree. We're interested in what potential problems people see with this suggestion:

Possible changes to ASDF wcs object:
Currently an ASDF 'step' contains a required frame and an optional transform. The frame describes the inputs to the transform. An ASDF 'wcs' object contains a list of chained steps. All steps in the chain must include a transform, except for the last step which must not include a transform. One way to produce trees could be to modify the schema so that the 'frame' component in a step may be an actual frame (as it is at the moment) or a reference to another step, in which case the frame in the referenced step describes the inputs to the transform.

Multiple steps would still be gathered together into a single list inside a 'wcs' object, as at the moment, but the existing rules for the list would be extended as follows:

1. The first step must contain a real frame (not a reference to another step).
2. subsequent steps are composed into a single chain until a step is found that has no transform. This step marks the end of the current chain (the chain that started at the first step). So far this is
   exactly the same as the current schema.
3. If any steps remain, the next step marks the start of a new chain and must contain a reference to one of the earlier steps, instead of an actual frame.
4. This new chain extends to the next step that has no transform.
5. Repeat steps 3) and 4) until the list of steps is exhausted
6. All steps must contain a transform except for those that mark the end of a chain.

I've attempted to illustrate this in the following sketch, which shows an example of a list of steps being used to describe a simple tree: If the wcs object contains more than one chain, the first chain could be seen as the "primary" chain in some sense - i.e. if the complete wcs object is used to transform a pixel position, then the first chain defines the transformation to be applied. This convention serves the same purpose as the "base" and "current" properties of an AST FrameSet.

One feature of this scheme is that existing ASDF wcs objects are still legal - they obey all the above rules. gWCS presumably stops reading steps as soon as it finds a step that has no transform, meaning that any remaining steps (constituting off-shoot branches) would be ignored. Thus this scheme seems to be backward-compatible.

How to implement referencing could be an issue. Using yaml anchors and aliases is probably the obvious way, but may not be the most convenient to work with in practice because some yaml readers may hide the anchor-alias relationship, substituting the referenced object directly in place of the alias. This would mean that re-constructing the tree would involve searching through all the steps for one that contains an identical frame. It may be more convenient to instead adopt some bespoke referencing scheme for this particular purpose. Say for instance, adding an optional "id" component to the target "step" structure and then specifying that id (instead of a frame) in the referencing step. The following text file contains an example of what this could look like for the tree shown in tree.png.

tree.txt