# pydicom.overlays.numpy_handler

Use the numpy package to convert supported Overlay Data to a `numpy.ndarray`.

Supported data

The numpy handler supports the conversion of data in the (60xx,3000) Overlay Data element to a `ndarray` provided the related Overlay Plane and Multi-frame Overlay module elements have values given in the table below.

Element | Supported values
--- | ---
Tag | Keyword | Type
(60xx,0010) | OverlayRows | 1 | N > 0
(60xx,0011) | OverlayColumns | 1 | N > 0
(60xx,0015) | NumberOfFramesInOverlay | 1 | N > 0
(60xx,0100) | OverlayBitsAllocated | 1 | 1
(60xx,0102) | OverlayBitPosition | 1 | 0

Functions

`get_expected_length`(elem[, unit]) | Return the expected length (in terms of bytes or pixels) of the Overlay Data.
`get_overlay_array`(ds, group) | Return a `numpy.ndarray` of the Overlay Data.
`is_available`() | Return `True` if the handler has its dependencies met.
`reshape_overlay_array`(elem, arr) | Return a reshaped `numpy.ndarray` arr.

pydicom.overlays.numpy_handler.get_expected_length(elem: Dict[str, Any], unit: str = 'bytes') → int

  Return the expected length (in terms of bytes or pixels) of the Overlay Data.

  New in version 1.4.

  Element | Required or optional
  --- | ---
  Tag | Keyword | Type
  (60xx,0010) | OverlayRows | 1 | Required
  (60xx,0011) | OverlayColumns | 1 | Required
  (60xx,0015) | NumberOfFramesInOverlay | 1 | Required

  Parameters:

    - elem (dict) – A `dict` with the keys as the element keywords and values the corresponding element values (such as `{'OverlayRows': 512, ...}`) for the elements listed in the table above.

    - unit (str, optional) – If `'bytes'` then returns the expected length of the Overlay Data in whole bytes and NOT including an odd length trailing NULL padding byte. If `'pixels'` then returns the expected length of the Overlay Data in terms of the total number of pixels (default `'bytes'`).

  Returns:

    The expected length of the Overlay Data in either whole bytes or pixels, excluding the NULL trailing padding byte for odd length data.

  Return type:

    int

pydicom.overlays.numpy_handler.get_overlay_array(ds: Dataset, group: int) → np.ndarray

  Return a `numpy.ndarray` of the Overlay Data.

  New in version 1.4.

  Parameters:

    - ds (Dataset) – The `Dataset` containing an Overlay Plane module and the Overlay Data to be converted.

    - group (int) – The group part of the Overlay Data element tag, e.g. `0x6000`, `0x6010`, etc. Must be between 0x6000 and 0x60FF.

  Returns:

    The contents of (group,3000) Overlay Data as an array.

  Return type:

    np.ndarray

  Raises:

    - AttributeError – If ds is missing a required element.

    - ValueError – If the actual length of the overlay data doesn’t match the expected length.

pydicom.overlays.numpy_handler.is_available() → bool

  Return `True` if the handler has its dependencies met.

  New in version 1.4.

pydicom.overlays.numpy_handler.reshape_overlay_array(elem: Dict[str, Any], arr: ndarray) → ndarray

  Return a reshaped `numpy.ndarray` arr.

  New in version 1.4.

  Element | Supported values
  --- | ---
  Tag | Keyword | Type
  (60xx,0010) | OverlayRows | 1 | N > 0
  (60xx,0011) | OverlayColumns | 1 | N > 0
  (60xx,0015) | NumberOfFramesInOverlay | 1 | N > 0

  Parameters:

    - elem (dict) – A `dict` with the keys as the element keywords and values the corresponding element values (such as `{'OverlayRows': 512, ...}`) for the elements listed in the table above.

    - arr (numpy.ndarray) – A 1D array containing the overlay data.

  Returns:

    A reshaped array containing the overlay data. The shape of the array depends on the contents of the dataset:

    - For single frame data (rows, columns)

    - For multi-frame data (frames, rows, columns)

  Return type:

    numpy.ndarray

  References

  - DICOM Standard, Part 3, Sections C.9.2 and C.9.3

  - DICOM Standard, Part 5, Section 8.2