gwcs.coordinate_frames

This module defines coordinate frames for describing the inputs and/or outputs of a transform.

In the block diagram, the WCS pipeline has a two stage transformation (two astropy Model instances), with an input frame, an output frame and an intermediate frame.

Diagram

ASCII

┌───────────────┐
│               │
│     Input     │
│     Frame     │
│               │
└───────┬───────┘
        │
  ┌─────▼─────┐
  │ Transform │
  └─────┬─────┘
        │
┌───────▼───────┐
│               │
│  Intermediate │
│     Frame     │
│               │
└───────┬───────┘
        │
  ┌─────▼─────┐
  │ Transform │
  └─────┬─────┘
        │
┌───────▼───────┐
│               │
│    Output     │
│     Frame     │
│               │
└───────────────┘

Each frame instance is both metadata for the inputs/outputs of a transform and also a converter between those inputs/outputs and richer coordinate representations of those inputs/outputs.

For example, an output frame of type SpectralFrame provides metadata to the WCS object such as the axes_type being "SPECTRAL" and the unit of the output etc. The output frame also provides a converter of the numeric output of the transform to a SpectralCoord object, by combining this metadata with the numerical values.

axes_order and conversion between objects and arguments

One of the key concepts regarding coordinate frames is the axes_order argument. This argument is used to map from the components of the frame to the inputs/outputs of the transform. To illustrate this consider this situation where you have a forward transform which outputs three coordinates [lat, lambda, lon]. These would be represented as a SpectralFrame and a CelestialFrame, however, the axes of a CelestialFrame are always [lon, lat], so by specifying two frames as

[SpectralFrame(axes_order=(1,)), CelestialFrame(axes_order=(2, 0))]

we would map the outputs of this transform into the correct positions in the frames. As shown below, this is also used when constructing the inputs to the inverse transform.

When taking the output from the forward transform the following transformation is performed by the coordinate frames:

Diagram

ASCII

                lat, lambda, lon
                │      │     │
                └──────┼─────┼────────┐
           ┌───────────┘     └──┐     │
           │                    │     │
 ┌─────────▼────────┐    ┌──────▼─────▼─────┐
 │                  │    │                  │
 │  SpectralFrame   │    │  CelestialFrame  │
 │                  │    │                  │
 │       (1,)       │    │      (2, 0)      │
 │                  │    │                  │
 └─────────┬────────┘    └──────────┬────┬──┘
           │                        │    │
           │                        │    │
           ▼                        ▼    ▼
SpectralCoord(lambda)    SkyCoord((lon, lat))

When considering the backward transform the following transformations take place in the coordinate frames before the transform is called:

Diagram

ASCII

SpectralCoord(lambda)    SkyCoord((lon, lat))
            │                        │    │
            └─────┐     ┌────────────┘    │
                  │     │    ┌────────────┘
                  ▼     ▼    ▼
              [lambda, lon, lat]
                  │     │    │
                  │     │    │
           ┌──────▼─────▼────▼────┐
           │                      │
           │  Sort by axes_order  │
           │                      │
           └────┬──────┬─────┬────┘
                │      │     │
                ▼      ▼     ▼
                lat, lambda, lon

Classes

AxisType(*values)	Enumeration of the Axis types
BaseCoordinateFrame(*args, **kwargs)	Legacy base class for coordinate frames.
CelestialFrame([axes_order, ...])	Representation of a Celesital coordinate system.
CompositeFrame(frames[, name])	Represents one or more frames.
CoordinateFrame(naxes, axes_type, axes_order)	Base class for Coordinate Frames.
CoordinateFrameProtocol(*args, **kwargs)	API Definition for a Coordinate frame
EmptyFrame([name, naxes])	Represents a "default" detector frame.
Frame2D([axes_order, unit, axes_names, ...])	A 2D coordinate frame.
FrameProperties(axes_type, unit, axes_names, ...)
SpectralFrame([axes_order, reference_frame, ...])	Represents Spectral Frame
StokesFrame([axes_order, axes_names, name, ...])	A coordinate frame for representing Stokes polarisation states.
TemporalFrame(reference_frame[, unit, ...])	A coordinate frame for time axes.
WorldAxisObjectClass(class_object, ...)	A tuple to document the individual elements of the world_axis_object_classes of the WCS API.
WorldAxisObjectClassConverter(class_object, ...)	Same as the WorldAxisObjectClass but with an additional converter field.
WorldAxisObjectComponent(name, position, ...)	A tuple to document the individual elements of the world_axis_object_components of the WCS API.
_LegacyCoordinateFrameProtocol(*args, **kwargs)	Original API definition for a coordinate frame.

Exceptions

EmptyFrameDeprecationWarning
EmptyFrameUnitsWarning

Functions

get_ctype_from_ucd(ucd)

Return the FITS CTYPE corresponding to a UCD1 value.