Support roman level 2 wcs

[braingram]

This is more complicated than the level 3/mosaic wcs and will require supporting:

• wider selection of transforms (the level 3 only uses fitswcs_imaging)
• transform combination via composition, concatenation, etc
• wcs evaluation since we can't map the level 2 wcs to a fits wcs

Using example files from roman build 21 (romancal version 0.22.0) the level 2 wcs contains the following tags:

'tag:astropy.org:astropy/coordinates/frames/icrs-1.1.0',
 'tag:stsci.edu:asdf/core/ndarray-1.1.0',
 'tag:stsci.edu:asdf/transform/affine-1.4.0',
 'tag:stsci.edu:asdf/transform/compose-1.3.0',
 'tag:stsci.edu:asdf/transform/concatenate-1.3.0',
 'tag:stsci.edu:asdf/transform/constant-1.5.0',
 'tag:stsci.edu:asdf/transform/divide-1.3.0',
 'tag:stsci.edu:asdf/transform/identity-1.3.0',
 'tag:stsci.edu:asdf/transform/polynomial-1.2.0',
 'tag:stsci.edu:asdf/transform/property/bounding_box-1.1.0',
 'tag:stsci.edu:asdf/transform/remap_axes-1.4.0',
 'tag:stsci.edu:asdf/transform/rotate_sequence_3d-1.1.0',
 'tag:stsci.edu:asdf/transform/scale-1.3.0',
 'tag:stsci.edu:asdf/transform/shift-1.3.0',
 'tag:stsci.edu:asdf/unit/unit-1.0.0',
 'tag:stsci.edu:gwcs/celestial_frame-1.2.0',
 'tag:stsci.edu:gwcs/frame2d-1.2.0',
 'tag:stsci.edu:gwcs/spherical_cartesian-1.3.0',
 'tag:stsci.edu:gwcs/step-1.3.0',
 'tag:stsci.edu:gwcs/wcs-1.4.0'

The same collection of tags is used for the isolated "_wcs" files that contain both a L1 and L2 wcs (after correcting the pointing by matching sources to gaia). These include:

• top level objects (wcs and step)
• frames (celestial_frame, frame2d, icrs)
• transforms (affine, compose, concatenate, constant, divide, identity, polynomial, remap_axes, rotate_sequence_3d, scale, shift, spherical_cartesian)
• misc (bounding_box, unit)

In addition to supporting the above (to allow us to evaluate the transform) we'll need some user facing WCS API. Perhaps we can model this off of wcslib or some other existing FITS WCS library to make it easier for users to adopt.

[embray]

Some additional thoughts on this:

Anything pertaining to WCS evaluation should be clearly separated from the libasdf core. The core library's responsibility is to read and write ASDF files and provide an extension mechanism for domain-specific interpretation of tagged objects.

It may make sense to support GWCS-related tags in a separate libasdf-gwcs extension (as discussed in #79). However, it is important to distinguish between:

• Deserializing GWCS YAML structures into C-native representations.
• Providing a WCS evaluation engine capable of mapping pixel coordinates to celestial coordinates.

The first is a format-binding problem and fits naturally into a libasdf extension.

The second is a modeling and transform-execution problem, and is substantially larger in scope.

For context, there are already provisional GWCS-related extensions in the repository (e.g., frame2d, step, transform, etc.) that deserialize YAML structures into C structs. Aside from fitswcs_imaging (for compatibility with WCSLIB), transform evaluation itself is not implemented--instead it just provides a relatively easy-to-use translation layer. (As an aside, you can see how this is used in my SE++ fork to instantiate WCSLIB through this intermediate layer here: https://github.com/embray/SourceXtractorPlusPlus/blob/ab4ab831081e5dea8e18e6363fa1c5ec10dddfe6/SEFramework/src/lib/CoordinateSystem/WCS.cpp#L257 ; I originally considered putting WCSLIB support directly into the gwcs libasdf extension too which might be useful, but may also be inflexible--as one can see providing this mapping is about a dozen lines of glue code in C++).

Before expanding transform support further--much less implementing a general-purpose transform engine (even one narrowly focused on Roman L2 WCS)--we should clarify:

• What concrete non-Python use case requires evaluating these transforms in a lower-level language like C or C++?
• Which specific subset of transforms must be supported?
• Is forward evaluation sufficient, or are inverses required?
• Is integration with an existing library under consideration (e.g., AST)?
• Alternatively, is embedding or delegating to the existing Python GWCS package acceptable?

Implementing evaluation for the full set of transforms listed in this issue would effectively require building (or tightly integrating) a coordinate transformation framework comparable in scope to GWCS itself. That is a significant project and should likely be treated as such.

There are a few possible architectural directions:

• If relying on existing GWCS evaluation in Python is sufficient, then reimplementing deserialization and evaluation in C may provide limited benefit. In that case, extracting the GWCS metadata and delegating evaluation to Python (via the existing GWCS ASDF extension) could be simpler and lower risk.

• If WCS evaluation must be supported in a lower-level language for interoperability or performance reasons, then we need to define both the target framework and the level of coupling:

  • Translate directly into an existing system such as Starlink AST (tight coupling),
  • Or define an intermediate C-native representation that mirrors GWCS concepts and can target multiple backends.

Both approaches are viable, but they imply very different design constraints, scope, and long-term maintenance commitments.

I'm very open to exploring feasibility--for example:

• Prototyping deserialization of Level 2 WCS into a transform graph representation.
• Investigating mapping that representation into AST or coupling to AST directly.
• Defining a minimal evaluation API for Roman's specific needs.

However, it would be helpful to explicitly clarify whether the goal is:

• To ensure libasdf can read Roman files at the format level, or
• To provide a C-based WCS evaluation engine for Roman.

Those are different deliverables and require different levels of effort and planning.

Before investing significant development time in this area, a lightweight risk assessment around transform coverage, evaluation directionality, unit/frame handling, and expected consumer environments (C, C++, Java, Python, mixed C/Python, etc.) would help ensure the solution is appropriately scoped and maintainable.

[embray]

Hmm, something I just learned:

Investigating...

[embray]

Well, here's what I've found out so far about AST's YAML support:

• There is some confusion in the naming about YAML vs. ASDF vs. GWCS. The latter two are certainly fungible, since although the asdf-standard transform schemas are not strictly specific to GWCS they are effectively 1-1 with what's supported by GWCS. David S. Berry who wrote this clearly understands the distinction, but it's a little confusing.

  • There are also ambitions in the code to support a "native" AST YAML format that more closely maps to AST's data structures. A comment in the source code reads "Currently, the only schema supported by this class is "ASDF", defined by the Space Telescope Science Institute... At some point in the future support will be added for the AST NATIVE scheme." There is definitely some provisional code for the native format but not 100% clear that it's well-defined yet.
  • This partly explains why it's called YamlChan as opposed to something like AsdfChan.

• It does not understand the full ASDF format; only reads the ASDF tree. In cases where the schemas define use of ndarrays (e.g. for polynomial coefficients) only reading ndarrays with inline data is supported.

• YAML parsing and emitting is performed with the older libyaml library. This makes sense--this was written initially in 2020 when libfyaml was newer and less stable. libyaml only supports stream-oriented event-based reading; no tree structure like libfyaml.

• It works by iterating over YAML events and using it to build a tree structure in its native AstKeyMap format which provides some support for generic values. When reading ASDF in particular it doesn't have a means (that I've found yet) to provide a specific path to a WCS object. Instead it just reads the YAML, up to a document end event, until it's found something that looks like a valid gwcs/wcs.

• The actual data translation is then handled more-or-less how libasdf deserializers work, though it's reading directly into AST's native data structures, or whatever best approximation thereof is supported. In most cases this is pretty clean though there are some corner cases. There are also some huge if (strcmp(...)) else if (strcmp(...)) branches over the tag names.

• Updating it to optionally support libasdf as an alternative backend is certainly possible; unclear if it's needed unless reading binary blocks is required, though it might make some parts more robust.

• According to the AST website:

  Note, currently the YamlChan class only supports celestial coordinate systems (i.e no spectral or time systems are supported)

  This appears to still be the case.

• A limited, but still fairly broad subset of transforms and projections are supported (AST calls them Mappings); I still need to spend more time evaluating exactly which ones and what the specific caveats are.

[braingram]

Thanks for looking into this. I will read through your comments in more detail later. If it's helpful for testing here is an example L2 wcs with all arrays inlined (renamed to .yaml to appease github).

l2_wcs.yaml

[braingram]

re libasdf-gwcs

That sounds good to me. I'll follow up on #79

Before expanding transform support further--much less implementing a general-purpose transform engine (even one narrowly focused on Roman L2 WCS)--we should clarify:

* What concrete non-Python use case requires evaluating these transforms in a lower-level language like C or C++?

The proposal funding this work has the following:

"A C++ ASDF library will integrate with the MSOS pipeline seamlessly and will allow the Roman Level 2 files to be utlized without convertng them to FITS first."

"Adding support for all possible GWCS Python models in C/C++ is a major task and will
not be covered by this work. We will, however, provide support for all Roman GWCS
models, and JWST NIRCam models, which is achievable with this funding. (JWST NIRSpec
and MIRI models are much more complex and will require more effort.)"

One use case is the rapids PIT which does not want to use python for reading and processing roman level 2 files.

* Which specific subset of transforms must be supported?

In addition to the ones listed above we'll need to sort out what's possible for JWST NIRCam models.

* Is forward evaluation sufficient, or are inverses required?

What do you think? I expect users will want both.

* Is integration with an existing library under consideration (e.g., AST)?

At this point yes.

* Alternatively, is embedding or delegating to the existing Python GWCS package acceptable?

Possibly. My understanding is that the rapids PIT is very concerned with performance. This is their major argument for why they don't want to use python (it's slow). I suspect that using this approach would make them much less likely to use libasdf.

Implementing evaluation for the full set of transforms listed in this issue would effectively require building (or tightly integrating) a coordinate transformation framework comparable in scope to GWCS itself. That is a significant project and should likely be treated as such.

In the proposal we had:
Roman and JWST NIRCam Imaging WCS Model Support 2x months FTE

Do you think this estimate is accurate given what we know now?

However, it would be helpful to explicitly clarify whether the goal is:

* To ensure libasdf can read Roman files at the format level, or

* To provide a C-based WCS evaluation engine for Roman.

Those are different deliverables and require different levels of effort and planning.

I see the need as needing to evaluate the level 2 WCS. If an evaluation engine exists (like AST or something else if we can find an alternative) using it seems like a reasonable choice but if it's easier to implement a simple engine that is limited to the Roman L2 WCS I vote for the simpler option.

Before investing significant development time in this area, a lightweight risk assessment around transform coverage, evaluation directionality, unit/frame handling, and expected consumer environments (C, C++, Java, Python, mixed C/Python, etc.) would help ensure the solution is appropriately scoped and maintainable.

That sounds great. Let me know what I can do to help here.

re AST:

It sounds promising. If you think it would be helpful to investigate that some more we can provide a conservative estimate on the effort needed to "support the L2 wcs" and then update it once we learn more.

[nden]

I hope this comment helps in some way.
AST is a general WCS library similar to GWCS. In the long run it may be beneficial to provide full support for AST.

The WCS of Roman and Nircam Level2 files can be split roughly into

• polynomials
• fitswcs_imaging (it includes shift, affine, projection, sky_3d rotation)

Recent versions of wcslib include polynomial transforms. In theory it should be possible to implement the L2 WCSs using wcslib only by ignoring the coordinate frames and essentially converting it to a FITS WCS representation. If this is practical it will reduce the work significantly.