Cutout2D

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

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:
data : ndarray

The 2D data array from which to extract the cutout array.

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

size : int, array-like, 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.

wcs : WCS, 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_value : number, 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.

copy : bool, 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:
data : 2D ndarray

The 2D cutout array.

shape : 2 tuple

The (ny, nx) shape of the cutout array.

shape_input : 2 tuple

The (ny, nx) shape of the input (original) array.

input_position_cutout : 2 tuple

The (unrounded) (x, y) position with respect to the cutout array.

input_position_original : 2 tuple

The original (unrounded) (x, y) input position (with respect to the original array).

slices_original : 2 tuple of slice objects

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 tuple of slice objects

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_original : 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_cutout : 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.

wcs : WCS or 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] [edit on github]

Plot the cutout region on a matplotlib Axes instance.

Parameters:
ax : matplotlib.axes.Axes instance, optional

If None, then the current matplotlib.axes.Axes instance is used.

fill : bool, optional

Set whether to fill the cutout patch. The default is False.

kwargs : optional

Any keyword arguments accepted by matplotlib.patches.Patch.

Returns:
ax : matplotlib.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] [edit on github]

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

Parameters:
original_position : tuple

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

Returns:
cutout_position : tuple

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

to_original_position(cutout_position)[source] [edit on github]

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

Parameters:
cutout_position : tuple

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

Returns:
original_position : tuple

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