Skip to main content
`Ctrl`+`K`

# Cutout2D

class astropy.nddata.Cutout2D(data, position, size, wcs=None, mode='trim', fill_value=nan, copy=False, *, limit_rounding_method=<ufunc 'ceil'>)

  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 `python: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 `python: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 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 `python: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.

    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.

    limit_rounding_method `python:callable()`

      The rounding method when calculating the minimum and maximum pixel indices. This must be a callable function. Examples: `ceil`, `floor`, `round`. Default is `ceil`.

  Attributes:
    data 2D `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_original `python: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 `python: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 `python:None`

      A WCS object associated with the cutout array if a `wcs` was input.

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

    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)

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

    Parameters:
      original_position `python:tuple`

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

    Returns:
      cutout_position `python:tuple`

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

    See also

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

    Parameters:
      cutout_position `python:tuple`

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

    Returns:
      original_position `python:tuple`

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

    See also

    `to_cutout_position`