WCS

class gwcs.wcs.WCS(forward_transform=None, input_frame='detector', output_frame=None, name='')[source]

Bases: gwcs.api.GWCSAPIMixin

Basic WCS class.

Parameters
forward_transformModel or a list

The transform between input_frame and output_frame. A list of (frame, transform) tuples where frame is the starting frame and transform is the transform from this frame to the next one or output_frame. The last tuple is (transform, None), where None indicates the end of the pipeline.

input_framestr, CoordinateFrame

A coordinates object or a string name.

output_framestr, CoordinateFrame

A coordinates object or a string name.

namestr

a name for this WCS

Attributes Summary

available_frames

List all frames in this WCS object.

backward_transform

Return the total backward transform if available - from output to input coordinate system.

bounding_box

Return the range of acceptable values for each input axis.

forward_transform

Return the total forward transform - from input to output coordinate frame.

input_frame

Return the input coordinate frame.

name

Return the name for this WCS.

output_frame

Return the output coordinate frame.

pipeline

Return the pipeline structure.

unit

The unit of the coordinates in the output coordinate system.

Methods Summary

__call__(*args, **kwargs)

Executes the forward transform.

fix_inputs(fixed)

Return a new unique WCS by fixing inputs to constant values.

footprint([bounding_box, center, axis_type])

Return the footprint in world coordinates.

get_transform(from_frame, to_frame)

Return a transform between two coordinate frames.

insert_transform(frame, transform[, after])

Insert a transform before (default) or after a coordinate frame.

invert(*args, **kwargs)

Invert coordinates.

set_transform(from_frame, to_frame, transform)

Set/replace the transform between two coordinate frames.

to_fits_sip([bounding_box, max_pix_error, …])

Construct a SIP-based approximation to the WCS in the form of a FITS header

transform(from_frame, to_frame, *args, **kwargs)

Transform positions between two frames.

Attributes Documentation

available_frames

List all frames in this WCS object.

Returns
available_framesdict

{frame_name: frame_object or None}

backward_transform

Return the total backward transform if available - from output to input coordinate system.

Raises
NotImplementedError :

An analytical inverse does not exist.

bounding_box

Return the range of acceptable values for each input axis. The order of the axes is axes_order.

forward_transform

Return the total forward transform - from input to output coordinate frame.

input_frame

Return the input coordinate frame.

name

Return the name for this WCS.

output_frame

Return the output coordinate frame.

pipeline

Return the pipeline structure.

unit

The unit of the coordinates in the output coordinate system.

Methods Documentation

__call__(*args, **kwargs)[source]

Executes the forward transform.

argsfloat or array-like

Inputs in the input coordinate system, separate inputs for each dimension.

with_unitsbool

If True returns a SkyCoord or Quantity object, by using the units of the output cooridnate frame. Optional, default=False.

with_bounding_boxbool, optional

If True(default) values in the result which correspond to any of the inputs being outside the bounding_box are set to fill_value.

fill_valuefloat, optional

Output value for inputs outside the bounding_box (default is np.nan).

fix_inputs(fixed)[source]

Return a new unique WCS by fixing inputs to constant values.

Parameters
fixeddict

Keyword arguments with fixed values corresponding to self.selector.

Returns
new_wcsWCS

A new unique WCS corresponding to the values in fixed.

Examples

>>> w = WCS(pipeline, selector={"spectral_order": [1, 2]}) 
>>> new_wcs = w.set_inputs(spectral_order=2) 
>>> new_wcs.inputs 
    ("x", "y")
footprint(bounding_box=None, center=False, axis_type='all')[source]

Return the footprint in world coordinates.

Parameters
bounding_boxtuple of floats: (start, stop)

prop: bounding_box

centerbool

If True use the center of the pixel, otherwise use the corner.

axis_typestr

A supported output_frame.axes_type or “all” (default). One of [‘spatial’, ‘spectral’, ‘temporal’] or a custom type.

Returns
coordndarray

Array of coordinates in the output_frame mapping corners to the output frame. For spatial coordinates the order is clockwise, starting from the bottom left corner.

get_transform(from_frame, to_frame)[source]

Return a transform between two coordinate frames.

Parameters
from_framestr or CoordinateFrame

Initial coordinate frame name of object.

to_framestr, or instance of CoordinateFrame

End coordinate frame name or object.

Returns
transformModel

Transform between two frames.

insert_transform(frame, transform, after=False)[source]

Insert a transform before (default) or after a coordinate frame.

Append (or prepend) a transform to the transform connected to frame.

Parameters
framestr or CoordinateFrame

Coordinate frame which sets the point of insertion.

transformModel

New transform to be inserted in the pipeline

afterbool

If True, the new transform is inserted in the pipeline immediately after frame.

invert(*args, **kwargs)[source]

Invert coordinates.

The analytical inverse of the forward transform is used, if available. If not an iterative method is used.

Parameters
argsfloat, array like, SkyCoord or Unit

coordinates to be inverted

kwargsdict

keyword arguments to be passed to the iterative invert method.

with_bounding_boxbool, optional

If True(default) values in the result which correspond to any of the inputs being outside the bounding_box are set to fill_value.

fill_valuefloat, optional

Output value for inputs outside the bounding_box (default is np.nan).

set_transform(from_frame, to_frame, transform)[source]

Set/replace the transform between two coordinate frames.

Parameters
from_framestr or CoordinateFrame

Initial coordinate frame.

to_framestr, or instance of CoordinateFrame

End coordinate frame.

transformModel

Transform between from_frame and to_frame.

to_fits_sip(bounding_box=None, max_pix_error=0.25, degree=None, max_inv_pix_error=0.25, inv_degree=None, npoints=32, verbose=False)[source]

Construct a SIP-based approximation to the WCS in the form of a FITS header

This assumes a tangent projection.

The default mode in using this attempts to achieve roughly 0.25 pixel accuracy over the whole image.

Parameters
bounding_boxtuple, optional

A pair of tuples, each consisting of two numbers Represents the range of pixel values in both dimensions ((xmin, xmax), (ymin, ymax))

max_pix_errorfloat, optional

Maximum allowed error over the domain of the pixel array. This error is the equivalent pixel error that corresponds to the maximum error in the output coordinate resulting from the fit based on a nominal plate scale.

degreeint, optional

Degree of the SIP polynomial. If supplied, max_pixel_error is ignored.

max_inv_errorfloat, optional

Maximum allowed inverse error over the domain of the pixel array in pixel units. If None, no inverse is generated.

inv_degreeint, optional

Degree of the inverse SIP polynomial. If supplied max_inv_pixel_error is ignored.

npointsint, optional

The number of points in each dimension to sample the bounding box for use in the SIP fit.

verbosebool, optional

print progress of fits

Returns
FITS header with all SIP WCS keywords
Raises
ValueError

If the WCS is not 2D, an exception will be raised. If the specified accuracy (both forward and inverse, both rms and maximum) is not achieved an exception will be raised.

Notes

Use of this requires a judicious choice of required accuracies. Attempts to use higher degrees (~7 or higher) will typically fail due floating point problems that arise with high powers.

transform(from_frame, to_frame, *args, **kwargs)[source]

Transform positions between two frames.

Parameters
from_framestr or CoordinateFrame

Initial coordinate frame.

to_framestr, or instance of CoordinateFrame

Coordinate frame into which to transform.

argsfloat or array-like

Inputs in from_frame, separate inputs for each dimension.

output_with_unitsbool

If True - returns a SkyCoord or Quantity object.

with_bounding_boxbool, optional

If True(default) values in the result which correspond to any of the inputs being outside the bounding_box are set to fill_value.

fill_valuefloat, optional

Output value for inputs outside the bounding_box (default is np.nan).