GWCS Documentation

GWCS is a package for managing the World Coordinate System (WCS) of astronomical data.


GWCS takes a general approach to the problem of expressing transformations between pixel and world coordinates. The term “World Coordinate System” encapsulates this transformation, although that term is sometimes misunderstood to mean “the FITS implementation of WCS” (See the discussion in APE14 for more on this topic).

GWCS supports a data model which includes the entire transformation pipeline from input coordinates (detector by default) to world coordinates. Transformations can be chained, joined or combined with arithmetic operators using the flexible framework of compound models in modeling. In the case of a celestial output frame coordinates provides further transformations between standard coordinate frames. Spectral output coordinates are instances of Quantity and are transformed to other units with the tools in that package. The goal is to provide a flexible toolkit which is easily extendable by adding new transforms and frames.


gwcs requires:

To install from source:

git clone
cd gwcs
python install

To install the latest release:

pip install gwcs

GWCS is also available as part of astroconda.

Getting Started

The WCS data model represents a pipeline of transformations from some initial coordinate frame to a standard coordinate frame. It is implemented as a list of steps executed in order. Each step defines a starting coordinate frame and the transform to the next frame in the pipeline. The last step has no transform, only a frame which is the output frame of the total transform. As a minimum a WCS object has an input_frame (defaults to “detector”), an output_frame and the transform between them.

As an example, consider a typical WCS of an image without distortion.

The following imports are generally useful:

>>> import numpy as np
>>> from astropy.modeling.models import (Shift, Scale, Rotation2D,
...        Pix2Sky_TAN, RotateNative2Celestial, Mapping, Polynomial2D)
>>> from astropy import coordinates as coord
>>> from astropy import units as u
>>> from gwcs import wcs
>>> from gwcs import coordinate_frames as cf

The forward_transform is constructed as a combined model using astropy.modeling. The frames are subclasses of CoordinateFrame (although strings are acceptable too).

Create a transform to convert detector coordinates to ICRS.

>>> det2sky = (Shift(-10.5) & Shift(-13.2) | Rotation2D(0.0023) | \
...    Scale(.01) & Scale(.04) | Pix2Sky_TAN() | \
...    RotateNative2Celestial(5.6, -72.05, 180)).rename("detector2sky")

Create a coordinate frame associated with the detector and a celestial frame.

>>> detector_frame = cf.Frame2D(name="detector", axes_names=("x", "y"), unit=(u.pix, u.pix))
>>> sky_frame = cf.CelestialFrame(reference_frame=coord.ICRS(), name='icrs')

Initialize the WCS:

>>> wcsobj = wcs.WCS(forward_transform=det2sky, input_frame=detector_frame, output_frame=sky_frame)
>>> print(wcsobj)
  From   Transform
-------- ------------
detector detector2sky
    icrs         None

To convert a pixel (x, y) = (1, 2) to sky coordinates, call the WCS object as a function:

>>> sky = wcsobj(1, 2)
>>> print(sky)
    (5.284139265842838, -72.49775640633504)

The invert() method evaluates the backward_transform() if available, otherwise applies an iterative method to calculate the reverse coordinates.

>>> wcsobj.invert(*sky)    
    (1.0, 2.0)


gwcs.wcs Module


WCS([forward_transform, input_frame, …]) Basic WCS class.

Class Inheritance Diagram

Inheritance diagram of gwcs.wcs.WCS

gwcs.coordinate_frames Module

Defines coordinate frames and ties them to data axes.


Frame2D([axes_order, unit, axes_names, name]) A 2D coordinate frame.
CelestialFrame([axes_order, …]) Celestial Frame Representation
SpectralFrame([axes_order, reference_frame, …]) Represents Spectral Frame
CompositeFrame(frames[, name]) Represents one or more frames.
CoordinateFrame(naxes, axes_type, axes_order) Base class for Coordinate Frames.
TemporalFrame([axes_order, reference_time, …]) A coordinate frame for time axes.

Class Inheritance Diagram

Inheritance diagram of gwcs.coordinate_frames.Frame2D, gwcs.coordinate_frames.CelestialFrame, gwcs.coordinate_frames.SpectralFrame, gwcs.coordinate_frames.CompositeFrame, gwcs.coordinate_frames.CoordinateFrame, gwcs.coordinate_frames.TemporalFrame

gwcs.selector Module

The classes in this module create discontinuous transforms.

The main class is RegionsSelector. It maps inputs to transforms and evaluates the transforms on the corresponding inputs. Regions are well defined spaces in the same frame as the inputs. Regions are assigned unique labels (int or str). The region labels are used as a proxy between inputs and transforms. An example is the location of IFU slices in the detector frame.

RegionsSelector uses two structures:
  • A mapping of inputs to labels - “label_mapper”
  • A mapping of labels to transforms - “transform_selector”

A “label_mapper” is also a transform, a subclass of astropy.modeling.core.Model, which returns the labels corresponding to the inputs.

An instance of a LabelMapper class is passed to RegionsSelector. The labels are used by RegionsSelector to match inputs to transforms. Finally, RegionsSelector evaluates the transforms on the corresponding inputs. Label mappers and transforms take the same inputs as RegionsSelector. The inputs should be filtered appropriately using the inputs_mapping argument which is ian instance of Mapping. The transforms in “transform_selector” should have the same number of inputs and outputs.

This is illustrated below using two regions, labeled 1 and 2

| +-+       |
| | |  +-+  |
| |1|  |2|  |
| | |  +-+  |
| +-+       |
                   | label mapper |
                     ^       |
                     |       V
           ----------|   +-------+
           |             | label |
         +--------+      +-------+
--->     | inputs |          |
         +--------+          V
              |          +--------------------+
              |          | transform_selector |
              |          +--------------------+
              V                  |
         +-----------+           |
         | transform |<-----------
         | outputs |

The base class _LabelMapper can be subclassed to create other label mappers.


LabelMapperArray(mapper[, inputs_mapping, name]) Maps array locations to labels.
LabelMapperDict(inputs, mapper[, …]) Maps a number to a transform, which when evaluated returns a label.
LabelMapperRange(inputs, mapper[, …]) The structure this class uses maps a range of values to a transform.
RegionsSelector(inputs, outputs, selector, …) This model defines discontinuous transforms.
LabelMapper(inputs, mapper[, no_label, …]) Maps inputs to regions.

Class Inheritance Diagram

Inheritance diagram of gwcs.selector.LabelMapperArray, gwcs.selector.LabelMapperDict, gwcs.selector.LabelMapperRange, gwcs.selector.RegionsSelector, gwcs.selector.LabelMapper

gwcs.wcstools Module


wcs_from_fiducial(fiducial[, …]) Create a WCS object from a fiducial point in a coordinate frame.
grid_from_bounding_box(bounding_box[, step, …]) Create a grid of input points from the WCS bounding_box.