Native Interface

The Native Interface is the original GWCS interface that allows complete access to GWCS functionality.

There are three main methods performing transformations and additional ones to help with WCS introspection.

forward() method evaluates the WCS transformation from the input frame (first frame in the transform) to the output coordinate frame. For convenience, the same can be achieved by invoking the WCS object as a function.

>>> from gwcs import examples
>>> wcsobj = examples.gwcs_3d_spatial_wave()
>>> result = wcsobj(1, 1, 1)
>>> print(result)
(2.0, 3.0, 2.0)

The invert method evaluates the backward transform.

>>> wcsobj.invert(*result)
(1.0, 1.0, 1.0)

GWCS keeps track of units defined in the transforms, the inputs (if quantities) and the coordinate frames. The type of the result matches the type of the inputs. If the input is Quantities the result is quantities, even if the transforms do not support units. In this case the units defined in the coordinate frames are used. The Native API does not work with High Level Objects. These are supported only by the High Level API.

It is possible to evaluate any transform between two intermediate frames using the transform method.

>>> from astropy import units as u
>>> from gwcs import examples
>>> wcsobj = examples.gwcs_with_pipeline_celestial()
>>> print(wcsobj.available_frames)
['input', 'celestial', 'output']
>>> wcsobj.celestial
<CelestialFrame(name="celestial", unit=(Unit("arcsec"), Unit("deg")), axes_names=('lon', 'lat'),
... axes_order=(0, 1), reference_frame=<ICRS Frame>)>
>>> print(wcsobj.transform("celestial", "input", 60*u.arcsec, 60*u.deg))
(<Quantity 3. pix>, <Quantity 4. pix>)

In this example from_frame comes after to_frame in the general WCS pipeline, essentially evaluating the inverse of the transform between input and celestial. Also, typing the name of any frame in the pipeline shows some of the attributes of the frame.

Note

The Native API methods do their best to function under a principle of “least surprise”. Thus one should expect the following input/output behavior:

Input Type	Output Type
Numerical	Numerical
Quantity	Quantity
High-Level	Return Error