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_transform
Model
or a list The transform between
input_frame
andoutput_frame
. A list of (frame, transform) tuples whereframe
is the starting frame andtransform
is the transform from this frame to the next one oroutput_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
 forward_transform
Attributes Summary
List all frames in this WCS object.
Return the total backward transform if available  from output to input coordinate system.
Return the range of acceptable values for each input axis.
Return the total forward transform  from input to output coordinate frame.
Return the input coordinate frame.
Return the name for this WCS.
Return the output coordinate frame.
Return the pipeline structure.
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.
in_image
(*args, **kwargs)This method tests if one or more of the input world coordinates are contained within forward transformation’s image and that it maps to the domain of definition of the forward transformation.
insert_frame
(input_frame, transform, …)Insert a new frame into an existing pipeline.
insert_transform
(frame, transform[, after])Insert a transform before (default) or after a coordinate frame.
invert
(*args, **kwargs)Invert coordinates from output frame to input frame using analytical or usersupplied inverse.
numerical_inverse
(*args, **kwargs)Invert coordinates from output frame to input frame using numerical inverse.
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 SIPbased approximation to the WCS in the form of a FITS header
to_fits_tab
([bounding_box, bin_ext_name, …])Construct a FITS WCS
TAB
based approximation to the WCS in the form of a FITS header and a binary table extension.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 arraylike
Inputs in the input coordinate system, separate inputs for each dimension.
 with_unitsbool
If
True
returns aSkyCoord
orQuantity
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_wcs
WCS
A new unique WCS corresponding to the values in
fixed
.
 new_wcs
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.
 from_framestr or
 Returns
 transform
Model
Transform between two frames.
 transform

in_image
(*args, **kwargs)[source]¶ This method tests if one or more of the input world coordinates are contained within forward transformation’s image and that it maps to the domain of definition of the forward transformation. In practical terms, this function tests that input world coordinate(s) can be converted to input frame and that it is within the forward transformation’s
bounding_box
when defined. Parameters
 Returns

insert_frame
(input_frame, transform, output_frame)[source]¶ Insert a new frame into an existing pipeline. This frame must be anchored to a frame already in the pipeline by a transform. This existing frame is identified solely by its name, although an entire
CoordinateFrame
can be passed (e.g., theinput_frame
oroutput_frame
attribute). This frame is never modified. Parameters
 input_framestr or
CoordinateFrame
Coordinate frame at start of new transform
 transform
Model
New transform to be inserted in the pipeline
 output_frame: str or `~gwcs.coordinate_frame.CoordinateFrame`
Coordinate frame at end of new transform
 input_framestr or

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.
 transform
Model
New transform to be inserted in the pipeline
 afterbool
If True, the new transform is inserted in the pipeline immediately after
frame
.
 framestr or

invert
(*args, **kwargs)[source]¶ Invert coordinates from output frame to input frame using analytical or usersupplied inverse. When neither analytical nor usersupplied inverses are defined, a numerical solution will be attempted using
numerical_inverse()
.Note
Currently numerical inverse is implemented only for 2D imaging WCS.
 Parameters
 argsfloat, array like,
SkyCoord
orUnit
Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by
world_n_dim
. 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 tofill_value
. fill_valuefloat, optional
Output value for inputs outside the bounding_box (default is
np.nan
). with_unitsbool, optional
If
True
returns aSkyCoord
orQuantity
object, by using the units of the output cooridnate frame. Default isFalse
.
 argsfloat, array like,
 Returns
 resulttuple
Returns a tuple of scalar or array values for each axis.
 Other Parameters
 kwargsdict
Keyword arguments to be passed to
numerical_inverse()
(when defined) or to the iterative invert method.

numerical_inverse
(*args, **kwargs)[source]¶ Invert coordinates from output frame to input frame using numerical inverse.
Note
Currently numerical inverse is implemented only for 2D imaging WCS.
Note
This method uses a combination of vectorized fixedpoint iterations algorithm and
scipy.optimize.root
. The later is used for input coordinates for which vectorized algorithm diverges. Parameters
 argsfloat, array like,
SkyCoord
orUnit
Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by
world_n_dim
. 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 tofill_value
. fill_valuefloat, optional
Output value for inputs outside the bounding_box (default is
np.nan
). with_unitsbool, optional
If
True
returns aSkyCoord
orQuantity
object, by using the units of the output cooridnate frame. Default isFalse
. tolerancefloat, optional
Absolute tolerance of solution. Iteration terminates when the iterative solver estimates that the “true solution” is within this many pixels current estimate, more specifically, when the correction to the solution found during the previous iteration is smaller (in the sense of the L2 norm) than
tolerance
. Defaulttolerance
is 1.0e5. maxiterint, optional
Maximum number of iterations allowed to reach a solution. Default is 50.
 quietbool, optional
Do not throw
NoConvergence
exceptions when the method does not converge to a solution with the required accuracy within a specified number of maximum iterations set bymaxiter
parameter. Instead, simply return the found solution. Default isTrue
.
 argsfloat, array like,
 Returns
 resulttuple
Returns a tuple of scalar or array values for each axis.
 Other Parameters
 adaptivebool, optional
Specifies whether to adaptively select only points that did not converge to a solution within the required accuracy for the next iteration. Default (
True
) is recommended.Note
The
numerical_inverse()
uses a vectorized implementation of the method of consecutive approximations (seeNotes
section below) in which it iterates over all input points regardless until the required accuracy has been reached for all input points. In some cases it may be possible that almost all points have reached the required accuracy but there are only a few of input data points for which additional iterations may be needed (this depends mostly on the characteristics of the geometric distortions for a given instrument). In this situation it may be advantageous to setadaptive
=True
in which casenumerical_inverse()
will continue iterating only over the points that have not yet converged to the required accuracy.Note
When
detect_divergence
isTrue
,numerical_inverse()
will automatically switch to the adaptive algorithm once divergence has been detected. detect_divergencebool, optional
Specifies whether to perform a more detailed analysis of the convergence to a solution. Normally
numerical_inverse()
may not achieve the required accuracy if either thetolerance
ormaxiter
arguments are too low. However, it may happen that for some geometric distortions the conditions of convergence for the the method of consecutive approximations used bynumerical_inverse()
may not be satisfied, in which case consecutive approximations to the solution will diverge regardless of thetolerance
ormaxiter
settings.When
detect_divergence
isFalse
, these divergent points will be detected as not having achieved the required accuracy (without further details). In addition, ifadaptive
isFalse
then the algorithm will not know that the solution (for specific points) is diverging and will continue iterating and trying to “improve” diverging solutions. This may result inNaN
orInf
values in the return results (in addition to a performance penalties). Even whendetect_divergence
isFalse
,numerical_inverse()
, at the end of the iterative process, will identify invalid results (NaN
orInf
) as “diverging” solutions and will raiseNoConvergence
unless thequiet
parameter is set toTrue
.When
detect_divergence
isTrue
(default),numerical_inverse()
will detect points for which current correction to the coordinates is larger than the correction applied during the previous iteration if the requested accuracy has not yet been achieved. In this case, ifadaptive
isTrue
, these points will be excluded from further iterations and ifadaptive
isFalse
,numerical_inverse()
will automatically switch to the adaptive algorithm. Thus, the reported divergent solution will be the latest converging solution computed immediately before divergence has been detected.Note
When accuracy has been achieved, small increases in current corrections may be possible due to rounding errors (when
adaptive
isFalse
) and such increases will be ignored.Note
Based on our testing using JWST NIRCAM images, setting
detect_divergence
toTrue
will incur about 510% performance penalty with the larger penalty corresponding toadaptive
set toTrue
. Because the benefits of enabling this feature outweigh the small performance penalty, especially whenadaptive
=False
, it is recommended to setdetect_divergence
toTrue
, unless extensive testing of the distortion models for images from specific instruments show a good stability of the numerical method for a wide range of coordinates (even outside the image itself).Note
Indices of the diverging inverse solutions will be reported in the
divergent
attribute of the raisedNoConvergence
exception object.
 Raises
 NoConvergence
The iterative method did not converge to a solution to the required accuracy within a specified number of maximum iterations set by the
maxiter
parameter. To turn off this exception, setquiet
toTrue
. Indices of the points for which the requested accuracy was not achieved (if any) will be listed in theslow_conv
attribute of the raisedNoConvergence
exception object.See
NoConvergence
documentation for more details. NotImplementedError
Numerical inverse has not been implemented for this WCS.
 ValueError
Invalid argument values.

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.
 transform
Model
Transform between
from_frame
andto_frame
.
 from_framestr or

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 SIPbased 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.

to_fits_tab
(bounding_box=None, bin_ext_name='WCSTABLE', coord_col_name='coordinates', sampling=1)[source]¶ Construct a FITS WCS
TAB
based approximation to the WCS in the form of a FITS header and a binary table extension. For the description of the FITS WCSTAB
convention, see “Representations of spectral coordinates in FITS” in Greisen, E. W. et al. A&A 446 (2) 747771 (2006) . Parameters
 bounding_boxtuple, optional
Specifies the range of acceptable values for each input axis. The order of the axes is
axes_order
. For two image axesbounding_box
is of the form((xmin, xmax), (ymin, ymax))
. bin_ext_namestr, optional
Extension name for the
BinTableHDU
extension. coord_col_namestr, optional
Field name of the coordinate array in the structured array stored in
BinTableHDU
data. This corresponds toTTYPEi
field in the FITS header of the binary table extension. samplingfloat, tuple, optional
The target “density” of grid nodes per pixel to be used when creating the coordinate array for the
TAB
FITS WCS convention. It is equal to1/step
wherestep
is the distance between grid nodes in pixels.sampling
can be specified as a single number to be used for all axes or as atuple
of numbers that specify the sampling for each image axis.
 Returns
 hdr
Header
Header with WCSTAB information associated (to be used) with image data.
 bin_table
BinTableHDU
Binary table extension containing the coordinate array.
 hdr
 Raises
 ValueError
When
bounding_box
is not defined either through the inputbounding_box
parameter or this object’sbounding_box
property. ValueError
When
sampling
is atuple
of length larger than 1 that does not match the number of image axes. RuntimeError
If the number of image axes (
pixel_n_dim
) is larger than the number of world axes (world_n_dim
).

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 arraylike
Inputs in
from_frame
, separate inputs for each dimension. output_with_unitsbool
 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).
 from_framestr or