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 originaldata
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.
 positiontuple 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 aSkyCoord
, in which casewcs
is a required input. sizeint, arraylike,
Quantity
The size of the cutout array along each axis. If
size
is a scalar number or a scalarQuantity
, then a square cutout ofsize
will be created. Ifsize
has two elements, they should be in(ny, nx)
order. Scalar numbers insize
are assumed to be in units of pixels.size
can also be aQuantity
object or containQuantity
objects. SuchQuantity
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 themode
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 theCRPIX
location. Projection and other nonlinear distortions are not taken into account. wcs
WCS
, optional A WCS object associated with the input
data
array. Ifwcs
is notNone
, 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 inputdata
array is sufficient. For the'strict'
mode, the cutout array has to be fully contained within thedata
array, otherwise anPartialOverlapError
is raised. In all modes, nonoverlapping arrays will raise aNoOverlapError
. In'partial'
mode, positions in the cutout array that do not overlap with thedata
array will be filled withfill_value
. In'trim'
mode only the overlapping elements are returned, thus the resulting cutout array may be smaller than the requestedshape
. fill_valuenumber, optional
If
mode='partial'
, the value to fill pixels in the cutout array that do not overlap with the inputdata
.fill_value
must have the samedtype
as the inputdata
array. copybool, optional
If
False
(default), then the cutout data will be a view into the originaldata
array. IfTrue
, then the cutout data will hold a copy of the originaldata
array.
 data
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.
 shape2 tuple
The
(ny, nx)
shape of the cutout array. shape_input2 tuple
The
(ny, nx)
shape of the input (original) array. input_position_cutout2 tuple
The (unrounded)
(x, y)
position with respect to the cutout array. input_position_original2 tuple
The original (unrounded)
(x, y)
input position (with respect to the original array). slices_original2 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 (nonfilled) cutout values. slices_cutout2 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 (nonfilled) cutout values. xmin_original, ymin_original, xmax_original, ymax_originalfloat
The minimum and maximum
x
andy
indices of the minimal rectangular region of the cutout array with respect to the original array. Formode='partial'
, the bounding box indices are for the valid (nonfilled) cutout values. These values are the same as those inbbox_original
. xmin_cutout, ymin_cutout, xmax_cutout, ymax_cutoutfloat
The minimum and maximum
x
andy
indices of the minimal rectangular region of the cutout array with respect to the cutout array. Formode='partial'
, the bounding box indices are for the valid (nonfilled) cutout values. These values are the same as those inbbox_cutout
. wcs
WCS
orNone
A WCS object associated with the cutout array if a
wcs
was input.
 data2D
Attributes Summary
The bounding box
((ymin, ymax), (xmin, xmax))
of the minimal rectangular region of the cutout array with respect to the cutout array.The bounding box
((ymin, ymax), (xmin, xmax))
of the minimal rectangular region of the cutout array with respect to the original array.The central
(x, y)
position of the cutout array with respect to the cutout array.The central
(x, y)
position of the cutout array with respect to the original array.The
(x, y)
index of the origin pixel of the cutout with respect to the cutout array.The
(x, y)
index of the origin pixel of the cutout with respect to the original array.The
(x, y)
position index (rounded to the nearest pixel) in the cutout array.The
(x, y)
position index (rounded to the nearest pixel) in the original array.Methods Summary
plot_on_original
(self[, ax, fill])Plot the cutout region on a matplotlib Axes instance.
to_cutout_position
(self, original_position)Convert an
(x, y)
position in the original large array to the(x, y)
position in the cutout array.to_original_position
(self, 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. Formode='partial'
, the bounding box indices are for the valid (nonfilled) 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. Formode='partial'
, the bounding box indices are for the valid (nonfilled) cutout values.

center_cutout
¶ The central
(x, y)
position of the cutout array with respect to the cutout array. Formode='partial'
, the central position is calculated for the valid (nonfilled) cutout values.

center_original
¶ The central
(x, y)
position of the cutout array with respect to the original array. Formode='partial'
, the central position is calculated for the valid (nonfilled) cutout values.

origin_cutout
¶ The
(x, y)
index of the origin pixel of the cutout with respect to the cutout array. Formode='partial'
, the origin pixel is calculated for the valid (nonfilled) cutout values.

origin_original
¶ The
(x, y)
index of the origin pixel of the cutout with respect to the original array. Formode='partial'
, the origin pixel is calculated for the valid (nonfilled) 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
(self, ax=None, fill=False, **kwargs)[source]¶ Plot the cutout region on a matplotlib Axes instance.
 Parameters
 ax
matplotlib.axes.Axes
instance, optional If
None
, then the currentmatplotlib.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
.
 ax
 Returns
 ax
matplotlib.axes.Axes
instance The matplotlib Axes instance constructed in the method if
ax=None
. Otherwise the outputax
is the same as the inputax
.
 ax

to_cutout_position
(self, original_position)[source]¶ Convert an
(x, y)
position in the original large array to the(x, y)
position in the cutout array. Parameters
 original_positiontuple
The
(x, y)
pixel position in the original large array.
 Returns
 cutout_positiontuple
The corresponding
(x, y)
pixel position in the cutout array.

to_original_position
(self, 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_positiontuple
The
(x, y)
pixel position in the cutout array.
 Returns
 original_positiontuple
The corresponding
(x, y)
pixel position in the original large array.