WCSAPIMixin¶

class gwcs.api.WCSAPIMixin[source]¶

Bases: BaseLowLevelWCS, HighLevelWCSMixin, NativeAPIMixin

A mix-in class that is intended to be inherited by the WCS class and provides the low- and high-level WCS API described in the astropy APE 14 (https://doi.org/10.5281/zenodo.1188875).

Attributes Summary

`array_shape`	The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim`.
`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.
`bounding_box`	The input_frame's bounding box
`forward_transform`	The forward transformation model from the input_frame to the output_frame.
`input_frame`	The input coordinate frame.
`low_level_wcs`	Returns a reference to the underlying low-level WCS object.
`output_frame`	The output coordinate frame.
`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.
`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.

Methods Summary

`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.
`evaluate`(*args[, with_bounding_box, fill_value])	Executes the forward transform.
`invert`(*args[, with_bounding_box, fill_value])	Invert coordinates from output frame to input frame using analytical or user-supplied inverse.
`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.
`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.

Attributes Documentation

array_shape¶: 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).

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.

bounding_box¶: The input_frame’s bounding box

forward_transform¶: The forward transformation model from the input_frame to the output_frame.

input_frame¶: The input coordinate frame.

low_level_wcs¶

output_frame¶: The output coordinate frame.

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

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

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.

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

world_axis_names¶: An iterable of strings describing the name for each world axis.

world_axis_object_classes¶

world_axis_object_components¶

world_axis_physical_types¶: 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.

world_axis_units¶: 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).

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

Methods Documentation

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.

array_index_to_world_values(*index_arrays: ndarray[tuple[Any, ...], dtype[generic]] | Quantity) → tuple[ndarray[tuple[Any, ...], dtype[generic]], ...] | ndarray[tuple[Any, ...], dtype[generic]][source]¶: 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).

abstractmethod evaluate(*args: ndarray[tuple[Any, ...], dtype[generic]] | Quantity, with_bounding_box: bool = True, fill_value: float | number = nan, **kwargs) → tuple[ndarray[tuple[Any, ...], dtype[generic]] | Quantity, ...] | ndarray[tuple[Any, ...], dtype[generic]] | Quantity¶

Executes the forward transform.

argsfloat or array-like: Inputs in the input coordinate system, separate inputs for each dimension.
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).

Other Parameters:

kwargsdict: Keyword arguments to be passed to the forward_transform model.

abstractmethod invert(*args: ndarray[tuple[Any, ...], dtype[generic]] | Quantity, with_bounding_box: bool = True, fill_value: float | number = nan, **kwargs) → tuple[ndarray[tuple[Any, ...], dtype[generic]] | Quantity, ...] | ndarray[tuple[Any, ...], dtype[generic]] | Quantity¶

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 a numerical inverse algorithm.

Note

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

Parameters:

argsfloat, array like: 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 to fill_value.
fill_valuefloat, optional: Output value for inputs outside the bounding_box (default is np.nan).

Returns:

resulttuple or value: 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.

Other Parameters:

kwargsdict: Keyword arguments to be passed to the backward_transform model (when defined) or to the iterative invert method.

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.

pixel_to_world_values(*pixel_arrays: ndarray[tuple[Any, ...], dtype[generic]] | Quantity) → tuple[ndarray[tuple[Any, ...], dtype[generic]], ...] | ndarray[tuple[Any, ...], dtype[generic]][source]¶

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.

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.

world_to_array_index_values(*world_arrays: ndarray[tuple[Any, ...], dtype[generic]] | Quantity) → tuple[ndarray[tuple[Any, ...], dtype[generic]], ...] | ndarray[tuple[Any, ...], dtype[generic]][source]¶: 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.

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.

world_to_pixel_values(*world_arrays: ndarray[tuple[Any, ...], dtype[generic]] | Quantity) → tuple[ndarray[tuple[Any, ...], dtype[generic]], ...] | ndarray[tuple[Any, ...], dtype[generic]][source]¶

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.