GWCS Documentation¶
GWCS is a package for managing the World Coordinate System (WCS) of astronomical data.
Introduction¶
GWCS takes a general approach to WCS.
It 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.
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.000, 2.000)
See also¶
Reference/API¶
gwcs.wcs Module¶
Classes¶
WCS ([forward_transform, input_frame, ...]) |
Basic WCS class. |
Class Inheritance Diagram¶
digraph inheritanceb3737abe9c { rankdir=LR; size="8.0, 12.0"; "WCS" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Basic WCS class."]; }gwcs.coordinate_frames Module¶
Defines coordinate frames and ties them to data axes.
Classes¶
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 CoordinateFrames. |
Class Inheritance Diagram¶
digraph inheritance31623c0e29 { rankdir=LR; size="8.0, 12.0"; "CelestialFrame" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Celestial Frame Representation"]; "CoordinateFrame" -> "CelestialFrame" [arrowsize=0.5,style="setlinewidth(0.5)"]; "CompositeFrame" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Represents one or more frames."]; "CoordinateFrame" -> "CompositeFrame" [arrowsize=0.5,style="setlinewidth(0.5)"]; "CoordinateFrame" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Base class for CoordinateFrames."]; "Frame2D" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="A 2D coordinate frame."]; "CoordinateFrame" -> "Frame2D" [arrowsize=0.5,style="setlinewidth(0.5)"]; "SpectralFrame" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="Represents Spectral Frame"]; "CoordinateFrame" -> "SpectralFrame" [arrowsize=0.5,style="setlinewidth(0.5)"]; }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 |<-----------
+------------+
|
V
+---------+
| outputs |
+---------+
The base class _LabelMapper can be subclassed to create other label mappers.
Classes¶
LabelMapperArray |
Maps array locations to labels. |
LabelMapperDict |
Maps a number to a transform, which when evaluated returns a label. |
LabelMapperRange |
The structure this class uses maps a range of values to a transform. |
RegionsSelector |
This model defines discontinuous transforms. |