gwcs.wcs.WCS¶

class gwcs.wcs.WCS(forward_transform, input_frame=None, output_frame=None, name=None)¶

Bases: Pipeline, WCSAPIMixin

Basic WCS class.

Parameters:

forward_transform (ForwardTransform) – 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_frame (str | CoordinateFrameProtocol | None, default: None) – A coordinates object or a string name.
output_frame (str | CoordinateFrameProtocol | None, default: None) – A coordinates object or a string name.
name (str | None, default: None) – a name for this WCS

Attributes¶

`array_shape`	The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim`.
`available_frames`	List of all the frame names in this WCS in their order in the pipeline
`axis_correlation_matrix`	Returns an (`world_n_dim`, `pixel_n_dim`) matrix that indicates using booleans whether a given world coordinate depends on a given pixel coordinate.
`backward_transform`	Return the total backward transform if available - from output to input coordinate system.
`bounding_box`	Return the bounding box of the pipeline.
`forward_transform`	Return the forward transform of the pipeline.
`input_frame`	Return the input frame name of the pipeline.
`low_level_wcs`	Returns a reference to the underlying low-level WCS object.
`name`	Return the name for this WCS.
`output_frame`	Return the output frame name of the pipeline.
`pipeline`	Allow direct access to the raw pipeline steps.
`pixel_axis_names`	An iterable of strings describing the name for each pixel axis.
`pixel_bounds`	The bounds (in pixel coordinates) inside which the WCS is defined, as a list with `pixel_n_dim` `(min, max)` tuples.
`pixel_n_dim`	The number of axes in the pixel coordinate system.
`pixel_shape`	The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim` in `(x, y)` order (where for an image, `x` is the horizontal coordinate and `y` is the vertical coordinate) (optional).
`serialized_classes`	Indicates whether Python objects are given in serialized form or as actual Python objects.
`unit`	The unit of the coordinates in the output coordinate system.
`world_axis_names`	An iterable of strings describing the name for each world axis.
`world_axis_object_classes`	A dictionary giving information on constructing high-level objects for the world coordinates.
`world_axis_object_components`	A list with `world_n_dim` elements giving information on constructing high-level objects for the world coordinates.
`world_axis_physical_types`	An iterable of strings describing the physical type for each world axis.
`world_axis_units`	An iterable of strings given the units of the world coordinates for each axis.
`world_n_dim`	The number of axes in the world coordinate system.

property WCS.array_shape: tuple[int, ...] | None¶: The shape of the data that the WCS applies to as a tuple of length pixel_n_dim. If the WCS is valid in the context of a dataset with a particular shape, then this property can be used to store the shape of the data. This can be used for example if implementing slicing of WCS objects. This is an optional property, and it should return None if a shape is not known or relevant. The shape should be given in (row, column) order (the convention for arrays in Python).

property WCS.available_frames: list[str]¶: List of all the frame names in this WCS in their order in the pipeline

property WCS.axis_correlation_matrix¶: Returns an (world_n_dim, pixel_n_dim) matrix that indicates using booleans whether a given world coordinate depends on a given pixel coordinate. This defaults to a matrix where all elements are True in the absence of any further information. For completely independent axes, the diagonal would be True and all other entries False.

property WCS.backward_transform: Model¶

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

Raises:: NotImplementedError – An analytical inverse does not exist.

property WCS.bounding_box: ModelBoundingBox | CompoundBoundingBox | None¶: Return the bounding box of the pipeline.

property WCS.forward_transform: Model¶: Return the forward transform of the pipeline.

property WCS.input_frame: CoordinateFrameProtocol¶: Return the input frame name of the pipeline.

property WCS.low_level_wcs¶: Returns a reference to the underlying low-level WCS object.

property WCS.name: str¶: Return the name for this WCS.

property WCS.output_frame: CoordinateFrameProtocol¶: Return the output frame name of the pipeline.

property WCS.pipeline: list[Step]¶: Allow direct access to the raw pipeline steps.

property WCS.pixel_axis_names: tuple[str, ...]¶: An iterable of strings describing the name for each pixel axis.

property WCS.pixel_bounds: tuple[tuple[float, float], ...] | None¶: The bounds (in pixel coordinates) inside which the WCS is defined, as a list with pixel_n_dim (min, max) tuples. The bounds should be given in [(xmin, xmax), (ymin, ymax)] order. WCS solutions are sometimes only guaranteed to be accurate within a certain range of pixel values, for example when defining a WCS that includes fitted distortions. This is an optional property, and it should return None if a shape is not known or relevant.

property WCS.pixel_n_dim: int¶: The number of axes in the pixel coordinate system.

property WCS.pixel_shape: tuple[int, ...] | None¶

The shape of the data that the WCS applies to as a tuple of length pixel_n_dim in (x, y) order (where for an image, x is the horizontal coordinate and y is the vertical coordinate) (optional).

If the WCS is valid in the context of a dataset with a particular shape, then this property can be used to store the shape of the data. This can be used for example if implementing slicing of WCS objects. This is an optional property, and it should return None if a shape is neither known nor relevant.

property WCS.serialized_classes: bool¶: Indicates whether Python objects are given in serialized form or as actual Python objects.

property WCS.unit: tuple[Unit | None, ...] | None¶: The unit of the coordinates in the output coordinate system.

property WCS.world_axis_names: tuple[str, ...]¶: An iterable of strings describing the name for each world axis.

property WCS.world_axis_object_classes: WorldAxisObjectClasses¶

A dictionary giving information on constructing high-level objects for the world coordinates.

Each key of the dictionary is a string key from world_axis_object_components, and each value is a tuple with three elements or four elements:

The first element of the tuple must be a class or a string specifying the fully-qualified name of a class, which will specify the actual Python object to be created.
The second element, should be a tuple specifying the positional arguments required to initialize the class. If world_axis_object_components specifies that the world coordinates should be passed as a positional argument, this this tuple should include None placeholders for the world coordinates.
The third tuple element must be a dictionary with the keyword arguments required to initialize the class.
Optionally, for advanced use cases, the fourth element (if present) should be a callable Python object that gets called instead of the class and gets passed the positional and keyword arguments. It should return an object of the type of the first element in the tuple.

Note that we don’t require the classes to be Astropy classes since there is no guarantee that Astropy will have all the classes to represent all kinds of world coordinates. Furthermore, we recommend that the output be kept as human-readable as possible.

The classes used here should have the ability to do conversions by passing an instance as the first argument to the same class with different arguments (e.g. Time(Time(...), scale='tai')). This is a requirement for the implementation of the high-level interface.

The second and third tuple elements for each value of this dictionary can in turn contain either instances of classes, or if necessary can contain serialized versions that should take the same form as the main classes described above (a tuple with three elements with the fully qualified name of the class, then the positional arguments and the keyword arguments). For low-level API objects implemented in Python, we recommend simply returning the actual objects (not the serialized form) for optimal performance. Implementations should either always or never use serialized classes to represent Python objects, and should indicate which of these they follow using the serialized_classes attribute.

See the document APE 14: A shared Python interface for World Coordinate Systems for examples.

property WCS.world_axis_object_components: list[WorldAxisObjectComponent]¶

A list with world_n_dim elements giving information on constructing high-level objects for the world coordinates.

Each element of the list is a tuple with three items:

The first is a name for the world object this world array corresponds to, which must match the string names used in world_axis_object_classes. Note that names might appear twice because two world arrays might correspond to a single world object (e.g. a celestial coordinate might have both “ra” and “dec” arrays, which correspond to a single sky coordinate object).
The second element is either a string keyword argument name or a positional index for the corresponding class from world_axis_object_classes.
The third argument is a string giving the name of the property to access on the corresponding class from world_axis_object_classes in order to get numerical values. Alternatively, this argument can be a callable Python object that takes a high-level coordinate object and returns the numerical values suitable for passing to the low-level WCS transformation methods.

See the document APE 14: A shared Python interface for World Coordinate Systems for examples.

property WCS.world_axis_physical_types: tuple[str | None, ...] | None¶: An iterable of strings describing the physical type for each world axis. These should be names from the VO UCD1+ controlled Vocabulary (http://www.ivoa.net/documents/latest/UCDlist.html). If no matching UCD type exists, this can instead be "custom:xxx", where xxx is an arbitrary string. Alternatively, if the physical type is unknown/undefined, an element can be None.

property WCS.world_axis_units: tuple[str, ...]¶: An iterable of strings given the units of the world coordinates for each axis. The strings should follow the IVOA VOUnit standard (though as noted in the VOUnit specification document, units that do not follow this standard are still allowed, but just not recommended).

property WCS.world_n_dim: int¶: The number of axes in the world coordinate system.

Methods¶

`array_index_to_world`(*index_arrays)	Convert array indices to world coordinates (represented by Astropy objects).
`array_index_to_world_values`(*index_arrays)	Convert array indices to world coordinates.
`attach_compound_bounding_box`(cbbox, ...)	Attach a compound bounding box dictionary to the pipeline.
`evaluate`(*args[, with_bounding_box, fill_value])	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_frame`(frame)	Return the frame object corresponding to the given frame name.
`get_transform`(from_frame, to_frame)	Return a transform between two coordinate frames.
`in_image`(*args[, with_bounding_box, fill_value])	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[, with_bounding_box, fill_value])	Invert coordinates from output frame to input frame using analytical or user-supplied inverse.
`numerical_inverse`(*args[, tolerance, ...])	Invert coordinates from output frame to input frame using numerical inverse.
`out_of_bounds`(pixel_arrays[, fill_value])
`outside_footprint`(world_arrays)
`pipeline_between`(from_frame, to_frame)	Return a pipeline between the two given frames.
`pixel_to_world`(*pixel_arrays)	Convert pixel coordinates to world coordinates (represented by high-level objects).
`pixel_to_world_values`(*pixel_arrays)	Convert pixel coordinates to world coordinates.
`set_transform`(from_frame, to_frame, transform)	Set/replace the transform between two coordinate frames.
`to_fits`([bounding_box, max_pix_error, ...])	Construct a FITS WCS `-TAB`-based approximation to the WCS in the form of a FITS header and a binary table extension.
`to_fits_sip`([bounding_box, max_pix_error, ...])	Construct a SIP-based approximation to the WCS for the axes corresponding to the `CelestialFrame` 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[, ...])	Transform positions between two frames.
`world_to_array_index`(*world_objects)	Convert world coordinates (represented by Astropy objects) to array indices.
`world_to_array_index_values`(*world_arrays)	Convert world coordinates to array indices.
`world_to_pixel`(*world_objects)	Convert world coordinates (represented by Astropy objects) to pixel coordinates.
`world_to_pixel_values`(*world_arrays)	Convert world coordinates to pixel coordinates.

WCS.array_index_to_world(*index_arrays)¶

Convert array indices to world coordinates (represented by Astropy objects).

If a single high-level object is used to represent the world coordinates (i.e., if len(wcs.world_axis_object_classes) == 1), it is returned as-is (not in a tuple/list), otherwise a tuple of high-level objects is returned. See array_index_to_world_values for pixel indexing and ordering conventions.

WCS.array_index_to_world_values(*index_arrays)¶

Convert array indices to world coordinates. This is the same as pixel_to_world_values except that the indices should be given in (i, j) order, where for an image i is the row and j is the column (i.e. the opposite order to pixel_to_world_values).

Parameters:: index_arrays (LowLevelInput)
Return type:: tuple[LowLevelArray, ...] | LowLevelArray

WCS.attach_compound_bounding_box(cbbox, selector_args)¶

Attach a compound bounding box dictionary to the pipeline.

Parameters:

cbbox (dict[tuple[str, ...], tuple]) –

Dictionary of the bounding box tuples (F order) for each input set
keys: selector argument values: bounding box tuple in F order
selector_args (tuple[str, ...]) – Argument names to the model that are used to select the bounding box

Return type:

None

WCS.evaluate(*args, with_bounding_box=True, fill_value=nan, **kwargs)¶

Executes the forward transform.

Parameters:

args (LowLevelInput) – Inputs in the input coordinate system, separate inputs for each dimension.
with_bounding_box (bool, default: True) – 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_value (float | number, default: nan) – Output value for inputs outside the bounding_box (default is np.nan).
kwargs (dict) – Keyword arguments to be passed to the forward_transform model.

Return type:

tuple[LowLevelInput, ...] | LowLevelInput

WCS.fix_inputs(fixed)¶

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

Parameters:: fixed (dict[str | int, LowLevelArray | Quantity | float | number]) – Keyword arguments with fixed values corresponding to self.selector.
Returns:: new_wcs – A new unique WCS corresponding to the values in fixed.
Return type:: Self

Examples

>>> w = WCS(pipeline, selector={"spectral_order": [1, 2]})
>>> new_wcs = w.set_inputs(spectral_order=2)
>>> new_wcs.inputs
    ("x", "y")

WCS.footprint(bounding_box=None, center=False, axis_type=None)¶

Return the footprint in world coordinates.

Parameters:

bounding_box (tuple) – prop: bounding_box, given as (start, stop) per axis.
center (bool) – If True use the center of the pixel, otherwise use the corner.
axis_type (AxisType | str | None, default: None) – A supported output_frame.axes_type or "all" (default). One of ['spatial', 'spectral', 'temporal'] or a custom type.

Returns:

coord – 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.

Return type:

ndarray

WCS.get_frame(frame)¶

Return the frame object corresponding to the given frame name.

Parameters:: frame (str | CoordinateFrameProtocol) – Name of the frame or the frame object.
Returns:: The frame object corresponding to the given name.
Return type:: CoordinateFrameProtocol

WCS.get_transform(from_frame, to_frame)¶

Return a transform between two coordinate frames.

Parameters:

from_frame (str | CoordinateFrameProtocol) – Initial coordinate frame name of object.
to_frame (str | CoordinateFrameProtocol) – End coordinate frame name or object.

Returns:

Transform between two frames.

Return type:

Mdl

WCS.in_image(*args, with_bounding_box=True, fill_value=nan, **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. 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:

args (LowLevelInput) – Coordinates to be inverted.
kwargs (dict) – keyword arguments to be passed either to backward_transform (when defined) or to the iterative invert method.
with_bounding_box (bool, default: True)
fill_value (float | number, default: nan)

Returns:

result – A single boolean value or an array of boolean values with True indicating that the WCS footprint contains the coordinate and False if input is outside the footprint.

Return type:

bool | ndarray[tuple[int, ...], dtype[bool]]

WCS.insert_frame(input_frame, transform, output_frame)¶

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 CoordinateFrameProtocol can be passed (e.g., the input_frame or output_frame attribute). This frame is never modified.

Parameters:

input_frame (str | CoordinateFrameProtocol) – Coordinate frame at start of new transform
transform (Model) – New transform to be inserted in the pipeline
output_frame (str | CoordinateFrameProtocol) – Coordinate frame at end of new transform

Return type:

None

WCS.insert_transform(frame, transform, after=False)¶

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

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

Parameters:

frame (str | CoordinateFrameProtocol) – Coordinate frame which sets the point of insertion.
transform (Model) – New transform to be inserted in the pipeline
after (bool, default: False) – If True, the new transform is inserted in the pipeline immediately after frame.

Return type:

None

WCS.invert(*args, with_bounding_box=True, fill_value=nan, **kwargs)¶

Invert coordinates from output frame to input frame using analytical or user-supplied inverse. When neither analytical nor user-supplied inverses are defined, a numerical solution will be attempted using numerical_inverse().

Note

Currently numerical inverse is implemented only for 2D imaging WCS.

Parameters:

args (LowLevelInput) – Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by world_n_dim.
with_bounding_box (bool, default: True) – 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_value (float | number, default: nan) – Output value for inputs outside the bounding_box (default is np.nan).
kwargs (dict) – Keyword arguments to be passed to numerical_inverse() (when defined) or to the iterative invert method.

Returns:

result – Returns a tuple of scalar or array values for each axis. Unless input_frame.naxes == 1 when it shall return the value. The return type will be Quantity objects if the transform returns Quantity objects, else values.

Return type:

tuple[LowLevelInput, ...] | LowLevelInput

WCS.numerical_inverse(*args, tolerance=1e-05, maxiter=30, adaptive=True, detect_divergence=True, quiet=True, with_bounding_box=True, fill_value=nan, **kwargs)¶

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 fixed-point iterations algorithm and scipy.optimize.root. The later is used for input coordinates for which vectorized algorithm diverges.

Parameters:

args (float, array like, SkyCoord or Unit) – Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by world_n_dim.
with_bounding_box (bool, 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_value (float, optional) – Output value for inputs outside the bounding_box (default is np.nan).
tolerance (float, 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. Default tolerance is 1.0e-5.
maxiter (int, optional) – Maximum number of iterations allowed to reach a solution. Default is 50.
quiet (bool, 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 by maxiter parameter. Instead, simply return the found solution. Default is True.
adaptive (bool, 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 (see Notes 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 set adaptive = True in which case numerical_inverse() will continue iterating only over the points that have not yet converged to the required accuracy.

Note

When detect_divergence is True, numerical_inverse() will automatically switch to the adaptive algorithm once divergence has been detected.
detect_divergence (bool, 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 the tolerance or maxiter 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 by numerical_inverse() may not be satisfied, in which case consecutive approximations to the solution will diverge regardless of the tolerance or maxiter settings.

When detect_divergence is False, these divergent points will be detected as not having achieved the required accuracy (without further details). In addition, if adaptive is False 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 in NaN or Inf values in the return results (in addition to a performance penalties). Even when detect_divergence is False, numerical_inverse(), at the end of the iterative process, will identify invalid results (NaN or Inf) as “diverging” solutions and will raise NoConvergence unless the quiet parameter is set to True.

When detect_divergence is True (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, if adaptive is True, these points will be excluded from further iterations and if adaptive is False, 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 is False) and such increases will be ignored.

Note

Based on our testing using JWST NIRCAM images, setting detect_divergence to True will incur about 5-10% performance penalty with the larger penalty corresponding to adaptive set to True. Because the benefits of enabling this feature outweigh the small performance penalty, especially when adaptive = False, it is recommended to set detect_divergence to True, 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 raised NoConvergence exception object.

Returns:

result – Returns a tuple of scalar or array values for each axis.

Return type:

tuple

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, set quiet to True. Indices of the points for which the requested accuracy was not achieved (if any) will be listed in the slow_conv attribute of the raised NoConvergence exception object. See NoConvergence documentation for more details.
NotImplementedError – Numerical inverse has not been implemented for this WCS.
ValueError – Invalid argument values.

Examples

>>> from astropy.utils.data import get_pkg_data_filename
>>> from gwcs import NoConvergence
>>> import asdf
>>> import numpy as np

>>> filename = get_pkg_data_filename('data/nircamwcs.asdf', package='gwcs.tests')
>>> with asdf.open(filename, lazy_load=False, ignore_missing_extensions=True) as af:
...    w = af.tree['wcs']

>>> ra, dec = w([1,2,3], [1,1,1])
>>> assert np.allclose(ra, [5.927628, 5.92757069, 5.92751337]);
>>> assert np.allclose(dec, [-72.01341247, -72.01341273, -72.013413])

>>> x, y = w.numerical_inverse(ra, dec)
>>> assert np.allclose(x, [1.00000005, 2.00000005, 3.00000006]);
>>> assert np.allclose(y, [1.00000004, 0.99999979, 1.00000015]);

>>> x, y = w.numerical_inverse(ra, dec, maxiter=3, tolerance=1.0e-10, quiet=False)
Traceback (most recent call last):
...
gwcs.wcs._exception.NoConvergence: 'WCS.numerical_inverse' failed to converge to the
requested accuracy after 3 iterations.

>>> w.numerical_inverse(
...     *w([1, 300000, 3], [2, 1000000, 5], with_bounding_box=False),
...     adaptive=False,
...     detect_divergence=True,
...     quiet=False,
...     with_bounding_box=False
... )
Traceback (most recent call last):
...
gwcs.wcs._exception.NoConvergence: 'WCS.numerical_inverse' failed to converge to the
requested accuracy. After 4 iterations, the solution is diverging at
least for one input point.

>>> # Now try to use some diverging data:
>>> divra, divdec = w([1, 300000, 3], [2, 1000000, 5], with_bounding_box=False)
>>> assert np.allclose(divra, [5.92762673, 148.21600848, 5.92750827])
>>> assert np.allclose(divdec, [-72.01339464, -7.80968079, -72.01334172])
>>> try:
...     x, y = w.numerical_inverse(divra, divdec, maxiter=20,
...                                tolerance=1.0e-4, adaptive=True,
...                                detect_divergence=True,
...                                quiet=False)
... except NoConvergence as e:
...     print(f"Indices of diverging points: {e.divergent}")
...     print(f"Indices of poorly converging points: {e.slow_conv}")
...     print(f"Best solution:\n{e.best_solution}")
...     print(f"Achieved accuracy:\n{e.accuracy}")
Indices of diverging points: None
Indices of poorly converging points: [1]
Best solution:
[[1.00000040e+00 1.99999841e+00]
 [6.33507833e+17 3.40118820e+17]
 [3.00000038e+00 4.99999841e+00]]
Achieved accuracy:
[[2.75925982e-05 1.18471543e-05]
 [3.65405005e+04 1.31364188e+04]
 [2.76552923e-05 1.14789013e-05]]

WCS.out_of_bounds(pixel_arrays, fill_value=nan)¶

WCS.outside_footprint(world_arrays)¶

WCS.pipeline_between(from_frame, to_frame)¶

Return a pipeline between the two given frames.

Parameters:

from_frame (str | CoordinateFrameProtocol) – Initial coordinate frame name of object.
to_frame (str | CoordinateFrameProtocol) – End coordinate frame name or object.

Returns:

A DirectionalWCS (wcs, forward) where wcs is of the type of the calling object. The forward attribute indicates if the wcs/pipeline between the two frames is forward (True, from_frame -> to_frame) or backward (False, to_frame -> from_frame). Note that if from_frame and to_frame are the same, then None is returned.

Return type:

Optional[DirectionalWCS[Self]]

WCS.pixel_to_world(*pixel_arrays)¶

Convert pixel coordinates to world coordinates (represented by high-level objects).

If a single high-level object is used to represent the world coordinates (i.e., if len(wcs.world_axis_object_classes) == 1), it is returned as-is (not in a tuple/list), otherwise a tuple of high-level objects is returned. See pixel_to_world_values for pixel indexing and ordering conventions.

WCS.pixel_to_world_values(*pixel_arrays)¶

Convert pixel coordinates to world coordinates.

This method takes pixel_n_dim scalars or arrays as input, and pixel coordinates should be zero-based. Returns world_n_dim scalars or arrays in units given by world_axis_units. Note that pixel coordinates are assumed to be 0 at the center of the first pixel in each dimension. If a pixel is in a region where the WCS is not defined, NaN can be returned. The coordinates should be specified in the (x, y) order, where for an image, x is the horizontal coordinate and y is the vertical coordinate.

Parameters:: pixel_arrays (LowLevelInput)
Return type:: tuple[LowLevelArray, ...] | LowLevelArray

WCS.set_transform(from_frame, to_frame, transform)¶

Set/replace the transform between two coordinate frames.

Parameters:

from_frame (str | CoordinateFrameProtocol) – Initial coordinate frame.
to_frame (str | CoordinateFrameProtocol) – End coordinate frame.
transform (Model) – Transform between from_frame and to_frame.

Return type:

None

WCS.to_fits(bounding_box=None, max_pix_error=0.25, degree=None, max_inv_pix_error=0.25, inv_degree=None, npoints=32, crpix=None, projection='TAN', bin_ext_name='WCS-TABLE', coord_col_name='coordinates', sampling=1, verbose=False)¶

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 WCS -TAB convention, see “Representations of spectral coordinates in FITS” in Greisen, E. W. et al. A&A 446 (2) 747-771 (2006) . If WCS contains celestial frame, PC/CD formalism will be used for the celestial axes.

Note

SIP distortion fitting requires that the WCS object has only two celestial axes. When WCS does not contain celestial axes, SIP fitting parameters (max_pix_error, degree, max_inv_pix_error, inv_degree, and projection) are ignored. When a WCS, in addition to celestial frame, contains other types of axes, SIP distortion fitting is disabled (only linear terms are fitted for celestial frame).

Parameters:

bounding_box (tuple, optional) – Specifies the range of acceptable values for each input axis. The order of the axes is axes_order. For two image axes bounding_box is of the form ((xmin, xmax), (ymin, ymax)).
max_pix_error (float, 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.
degree (int, iterable, None, optional) –
Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...9]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_pixel_error is ignored.

Note

When WCS object has When degree is None and the WCS object has
max_inv_pix_error (float, optional) – Maximum allowed inverse error over the domain of the pixel array in pixel units. If None, no inverse is generated.
inv_degree (int, iterable, None, optional) – Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...9]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_inv_pixel_error is ignored.
npoints (int, optional) – The number of points in each dimension to sample the bounding box for use in the SIP fit. Minimum number of points is 3.
crpix (list of float, None, optional) – Coordinates (1-based) of the reference point for the new FITS WCS. When not provided, i.e., when set to None (default) the reference pixel will be chosen near the center of the bounding box for axes corresponding to the celestial frame.
projection (str, Pix2SkyProjection, optional) – Projection to be used for the created FITS WCS. It can be specified as a string of three characters specifying a FITS projection code from Table 13 in Representations of World Coordinates in FITS (Paper I), Greisen, E. W., and Calabretta, M. R., A & A, 395, 1061-1075, 2002. Alternatively, it can be an instance of one of the astropy’s Pix2Sky_* projection models inherited from Pix2SkyProjection.
bin_ext_name (str, optional) – Extension name for the BinTableHDU HDU for those axes groups that will be converted using FITW WCS’ -TAB algorithm. Extension version will be determined automatically based on the number of separable group of axes.
coord_col_name (str, optional) – Field name of the coordinate array in the structured array stored in BinTableHDU data. This corresponds to TTYPEi field in the FITS header of the binary table extension.
sampling (float, 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 to 1/step where step is the distance between grid nodes in pixels. sampling can be specified as a single number to be used for all axes or as a tuple of numbers that specify the sampling for each image axis.
verbose (bool, optional) – Print progress of fits.

Returns:

hdr (Header) – Header with WCS-TAB information associated (to be used) with image data.
hdulist (a list of BinTableHDU) – A Python list of binary table extensions containing the coordinate array for TAB extensions; one extension per separable axes group.

Raises:

ValueError – When bounding_box is not defined either through the input bounding_box parameter or this object’s bounding_box property.
ValueError – When sampling is a tuple of length larger than 1 that does not match the number of image axes.
RuntimeError – If the number of image axes (~gwcs.WCS.pixel_n_dim) is larger than the number of world axes (~gwcs.WCS.world_n_dim).

WCS.to_fits_sip(bounding_box=None, max_pix_error=0.25, degree=None, max_inv_pix_error=0.25, inv_degree=None, npoints=32, crpix=None, projection='TAN', verbose=False)¶

Construct a SIP-based approximation to the WCS for the axes corresponding to the CelestialFrame in the form of a FITS header.

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

Parameters:

bounding_box (tuple, 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_error (float, 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. Ignored when degree is an integer or a list with a single degree.
degree (int, iterable, None, optional) – Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...9]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_pixel_error is ignored.
max_inv_pix_error (float, optional) – Maximum allowed inverse error over the domain of the pixel array in pixel units. If None, no inverse is generated. Ignored when degree is an integer or a list with a single degree.
inv_degree (int, iterable, None, optional) – Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...9]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_inv_pixel_error is ignored.
npoints (int, optional) – The number of points in each dimension to sample the bounding box for use in the SIP fit. Minimum number of points is 3.
crpix (list of float, None, optional) – Coordinates (1-based) of the reference point for the new FITS WCS. When not provided, i.e., when set to None (default) the reference pixel will be chosen near the center of the bounding box for axes corresponding to the celestial frame.
projection (str, Pix2SkyProjection, optional) –
Projection to be used for the created FITS WCS. It can be specified as a string of three characters specifying a FITS projection code from Table 13 in Representations of World Coordinates in FITS (Paper I), Greisen, E. W., and Calabretta, M. R., A & A, 395, 1061-1075, 2002. Alternatively, it can be an instance of one of the astropy’s Pix2Sky_* projection models inherited from Pix2SkyProjection.
verbose (bool, optional) – Print progress of fits.

Returns:

hdr – FITS header with all SIP WCS keywords

Return type:

Header

Raises:

ValueError – If the WCS is not at least 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 to floating point problems that arise with high powers.

WCS.to_fits_tab(bounding_box=None, bin_ext_name='WCS-TABLE', coord_col_name='coordinates', sampling=1)¶

Parameters:

bounding_box (tuple, optional) – Specifies the range of acceptable values for each input axis. The order of the axes is axes_order. For two image axes bounding_box is of the form ((xmin, xmax), (ymin, ymax)).
bin_ext_name (str, optional) – Extension name for the BinTableHDU HDU for those axes groups that will be converted using FITW WCS’ -TAB algorithm. Extension version will be determined automatically based on the number of separable group of axes.
coord_col_name (str, optional) – Field name of the coordinate array in the structured array stored in BinTableHDU data. This corresponds to TTYPEi field in the FITS header of the binary table extension.
sampling (float, 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 to 1/step where step is the distance between grid nodes in pixels. sampling can be specified as a single number to be used for all axes or as a tuple of numbers that specify the sampling for each image axis.

Returns:

hdr (Header) – Header with WCS-TAB information associated (to be used) with image data.
bin_table_hdu (BinTableHDU) – Binary table extension containing the coordinate array.

Raises:

ValueError – When bounding_box is not defined either through the input bounding_box parameter or this object’s bounding_box property.
ValueError – When sampling is a tuple of length larger than 1 that does not match the number of image axes.
RuntimeError – If the number of image axes (~gwcs.WCS.pixel_n_dim) is larger than the number of world axes (~gwcs.WCS.world_n_dim).

WCS.transform(from_frame, to_frame, *args, with_bounding_box=True, fill_value=nan, **kwargs)¶

Transform positions between two frames.

Parameters:

from_frame (str | CoordinateFrameProtocol) – Initial coordinate frame.
to_frame (str | CoordinateFrameProtocol) – Coordinate frame into which to transform.
args (float | ndarray) – Inputs in from_frame, separate inputs for each dimension.
with_bounding_box (bool, default: True) – 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_value (float | number, default: nan) – Output value for inputs outside the bounding_box (default is np.nan).

Return type:

tuple[LowLevelArray, ...] | LowLevelArray

WCS.world_to_array_index(*world_objects)¶

Convert world coordinates (represented by Astropy objects) to array indices.

If pixel_n_dim is 1, this method returns a single scalar or array, otherwise a tuple of scalars or arrays is returned. See world_to_array_index_values for pixel indexing and ordering conventions. The indices should be returned as rounded integers.

WCS.world_to_array_index_values(*world_arrays)¶

Convert world coordinates to array indices. This is the same as world_to_pixel_values except that the indices should be returned in (i, j) order, where for an image i is the row and j is the column (i.e. the opposite order to pixel_to_world_values). The indices should be returned as rounded integers.

Parameters:: world_arrays (LowLevelInput)
Return type:: tuple[LowLevelArray, ...] | LowLevelArray

WCS.world_to_pixel(*world_objects)¶

Convert world coordinates (represented by Astropy objects) to pixel coordinates.

If pixel_n_dim is 1, this method returns a single scalar or array, otherwise a tuple of scalars or arrays is returned. See world_to_pixel_values for pixel indexing and ordering conventions.

WCS.world_to_pixel_values(*world_arrays)¶

Convert world coordinates to pixel coordinates.

This method takes world_n_dim scalars or arrays as input in units given by world_axis_units. Returns pixel_n_dim scalars or arrays. Note that pixel coordinates are assumed to be 0 at the center of the first pixel in each dimension. If a world coordinate does not have a matching pixel coordinate, NaN can be returned. The coordinates should be returned in the (x, y) order, where for an image, x is the horizontal coordinate and y is the vertical coordinate.

Parameters:: world_arrays (LowLevelInput)
Return type:: tuple[LowLevelArray, ...] | LowLevelArray