astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- N-dimensional datasets (`astropy.nddata`) »
- Cutout2D

# Cutout2D

class `astropy.nddata.``Cutout2D`(data, position, size, wcs=None, mode=u'trim', fill_value=nan, copy=False)

  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.

  Returns:

  result : `Cutout2D`

  > A cutout object containing the 2D cutout data array and the updated WCS, if `wcs` is 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 : 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)

    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.