Cutout2D¶

class astropy.nddata.utils.Cutout2D(data, position, size, wcs=None, mode='trim', fill_value=nan, copy=False)[source]¶

Bases: object

Create a cutout object from a 2D array.

The returned object will contain a 2D cutout array. If copy=False (default), the cutout array is a view into the original data array, otherwise the cutout array will contain a copy of the original data.

If a WCS object is input, then the returned object will also contain a copy of the original WCS, but updated for the cutout array.

For example usage, see 2D Cutout Images.

Warning

The cutout WCS object does not currently handle cases where the input WCS object contains distortion lookup tables described in the FITS WCS distortion paper.

Parameters:

datandarray: The 2D data array from which to extract the cutout array.
positionpython:tuple or SkyCoord: The position of the cutout array’s center with respect to the data array. The position can be specified either as a (x, y) tuple of pixel coordinates or a SkyCoord, in which case wcs is a required input.
sizepython:int, numpy:array_like, or Quantity: The size of the cutout array along each axis. If size is a scalar number or a scalar Quantity, then a square cutout of size will be created. If size has two elements, they should be in (ny, nx) order. Scalar numbers in size are assumed to be in units of pixels. size can also be a Quantity object or contain Quantity objects. Such Quantity objects must be in pixel or angular units. For all cases, size will be converted to an integer number of pixels, rounding the the nearest integer. See the mode keyword for additional details on the final cutout size.

Note

If size is in angular units, the cutout size is converted to pixels using the pixel scales along each axis of the image at the CRPIX location. Projection and other non-linear distortions are not taken into account.
wcsWCS, optional: A WCS object associated with the input data array. If wcs is not None, then the returned cutout object will contain a copy of the updated WCS for the cutout data array.
mode{‘trim’, ‘partial’, ‘strict’}, optional: The mode used for creating the cutout data array. For the 'partial' and 'trim' modes, a partial overlap of the cutout array and the input data array is sufficient. For the 'strict' mode, the cutout array has to be fully contained within the data array, otherwise an PartialOverlapError is raised. In all modes, non-overlapping arrays will raise a NoOverlapError. In 'partial' mode, positions in the cutout array that do not overlap with the data array will be filled with fill_value. In 'trim' mode only the overlapping elements are returned, thus the resulting cutout array may be smaller than the requested shape.
fill_valuepython:float or python:int, optional: If mode='partial', the value to fill pixels in the cutout array that do not overlap with the input data. fill_value must have the same dtype as the input data array.
copybool, optional: If False (default), then the cutout data will be a view into the original data array. If True, then the cutout data will hold a copy of the original data array.

Examples

>>> import numpy as np
>>> from astropy.nddata.utils import Cutout2D
>>> from astropy import units as u
>>> data = np.arange(20.).reshape(5, 4)
>>> cutout1 = Cutout2D(data, (2, 2), (3, 3))
>>> print(cutout1.data)  
[[ 5.  6.  7.]
 [ 9. 10. 11.]
 [13. 14. 15.]]

>>> print(cutout1.center_original)
(2.0, 2.0)
>>> print(cutout1.center_cutout)
(1.0, 1.0)
>>> print(cutout1.origin_original)
(1, 1)

>>> cutout2 = Cutout2D(data, (2, 2), 3)
>>> print(cutout2.data)  
[[ 5.  6.  7.]
 [ 9. 10. 11.]
 [13. 14. 15.]]

>>> size = u.Quantity([3, 3], u.pixel)
>>> cutout3 = Cutout2D(data, (0, 0), size)
>>> print(cutout3.data)  
[[0. 1.]
 [4. 5.]]

>>> cutout4 = Cutout2D(data, (0, 0), (3 * u.pixel, 3))
>>> print(cutout4.data)  
[[0. 1.]
 [4. 5.]]

>>> cutout5 = Cutout2D(data, (0, 0), (3, 3), mode='partial')
>>> print(cutout5.data)  
[[nan nan nan]
 [nan  0.  1.]
 [nan  4.  5.]]

Attributes:

data2D ndarray: The 2D cutout array.
shape(2,) python:tuple: The (ny, nx) shape of the cutout array.
shape_input(2,) python:tuple: The (ny, nx) shape of the input (original) array.
input_position_cutout(2,) python:tuple: The (unrounded) (x, y) position with respect to the cutout array.
input_position_original(2,) python:tuple: The original (unrounded) (x, y) input position (with respect to the original array).
slices_original(2,) python:tuple of slice object: A tuple of slice objects for the minimal bounding box of the cutout with respect to the original array. For mode='partial', the slices are for the valid (non-filled) cutout values.
slices_cutout(2,) python:tuple of slice object: A tuple of slice objects for the minimal bounding box of the cutout with respect to the cutout array. For mode='partial', the slices are for the valid (non-filled) cutout values.
xmin_original, ymin_original, xmax_original, ymax_originalpython:float: The minimum and maximum x and y indices of the minimal rectangular region of the cutout array with respect to the original array. For mode='partial', the bounding box indices are for the valid (non-filled) cutout values. These values are the same as those in bbox_original.
xmin_cutout, ymin_cutout, xmax_cutout, ymax_cutoutpython:float: The minimum and maximum x and y indices of the minimal rectangular region of the cutout array with respect to the cutout array. For mode='partial', the bounding box indices are for the valid (non-filled) cutout values. These values are the same as those in bbox_cutout.
wcsWCS or python:None: A WCS object associated with the cutout array if a wcs was input.

Attributes Summary

`bbox_cutout`	The bounding box `((ymin, ymax), (xmin, xmax))` of the minimal rectangular region of the cutout array with respect to the cutout array.
`bbox_original`	The bounding box `((ymin, ymax), (xmin, xmax))` of the minimal rectangular region of the cutout array with respect to the original array.
`center_cutout`	The central `(x, y)` position of the cutout array with respect to the cutout array.
`center_original`	The central `(x, y)` position of the cutout array with respect to the original array.
`origin_cutout`	The `(x, y)` index of the origin pixel of the cutout with respect to the cutout array.
`origin_original`	The `(x, y)` index of the origin pixel of the cutout with respect to the original array.
`position_cutout`	The `(x, y)` position index (rounded to the nearest pixel) in the cutout array.
`position_original`	The `(x, y)` position index (rounded to the nearest pixel) in the original array.

Methods Summary

`plot_on_original`([ax, fill])	Plot the cutout region on a matplotlib Axes instance.
`to_cutout_position`(original_position)	Convert an `(x, y)` position in the original large array to the `(x, y)` position in the cutout array.
`to_original_position`(cutout_position)	Convert an `(x, y)` position in the cutout array to the original `(x, y)` position in the original large array.

Attributes Documentation

bbox_cutout¶: The bounding box ((ymin, ymax), (xmin, xmax)) of the minimal rectangular region of the cutout array with respect to the cutout array. For mode='partial', the bounding box indices are for the valid (non-filled) cutout values.

bbox_original¶: The bounding box ((ymin, ymax), (xmin, xmax)) of the minimal rectangular region of the cutout array with respect to the original array. For mode='partial', the bounding box indices are for the valid (non-filled) cutout values.

center_cutout¶: The central (x, y) position of the cutout array with respect to the cutout array. For mode='partial', the central position is calculated for the valid (non-filled) cutout values.

center_original¶: The central (x, y) position of the cutout array with respect to the original array. For mode='partial', the central position is calculated for the valid (non-filled) cutout values.

origin_cutout¶: The (x, y) index of the origin pixel of the cutout with respect to the cutout array. For mode='partial', the origin pixel is calculated for the valid (non-filled) cutout values.

origin_original¶: The (x, y) index of the origin pixel of the cutout with respect to the original array. For mode='partial', the origin pixel is calculated for the valid (non-filled) cutout values.

position_cutout¶: The (x, y) position index (rounded to the nearest pixel) in the cutout array.

position_original¶: The (x, y) position index (rounded to the nearest pixel) in the original array.

Methods Documentation

plot_on_original(ax=None, fill=False, **kwargs)[source]¶

Plot the cutout region on a matplotlib Axes instance.

Parameters:

axmatplotlib.axes.Axes instance, optional: If None, then the current matplotlib.axes.Axes instance is used.
fillbool, optional: Set whether to fill the cutout patch. The default is False.
kwargsoptional: Any keyword arguments accepted by matplotlib.patches.Patch.

Returns:

axmatplotlib.axes.Axes instance: The matplotlib Axes instance constructed in the method if ax=None. Otherwise the output ax is the same as the input ax.

to_cutout_position(original_position)[source]¶

Convert an (x, y) position in the original large array to the (x, y) position in the cutout array.

Parameters:

original_positionpython:tuple: The (x, y) pixel position in the original large array.

Returns:

cutout_positionpython:tuple: The corresponding (x, y) pixel position in the cutout array.

to_original_position(cutout_position)[source]¶

Convert an (x, y) position in the cutout array to the original (x, y) position in the original large array.

Parameters:

cutout_positionpython:tuple: The (x, y) pixel position in the cutout array.

Returns:

original_positionpython:tuple: The corresponding (x, y) pixel position in the original large array.

Navigation

Cutout2D¶