# pydicom.overlay_data_handlers.numpy_handler

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

Supported transfer syntaxes

- 1.2.840.10008.1.2 : Implicit VR Little Endian
- 1.2.840.10008.1.2.1 : Explicit VR Little Endian
- 1.2.840.10008.1.2.1.99 : Deflated Explicit VR Little Endian
- 1.2.840.10008.1.2.2 : Explicit VR Big Endian

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.
`supports_transfer_syntax`(transfer_syntax) | Return `True` if the handler supports the transfer_syntax.

`pydicom.overlay_data_handlers.numpy_handler.``get_expected_length`(elem, unit='bytes')

  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.overlay_data_handlers.numpy_handler.``get_overlay_array`(ds, group)

  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.overlay_data_handlers.numpy_handler.``is_available`()

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

  New in version 1.4.

`pydicom.overlay_data_handlers.numpy_handler.``reshape_overlay_array`(elem, arr)

  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

`pydicom.overlay_data_handlers.numpy_handler.``supports_transfer_syntax`(transfer_syntax)

  Return `True` if the handler supports the transfer_syntax.

  New in version 1.4.

  Parameters: | transfer_syntax (uid.UID) – The Transfer Syntax UID of the Pixel Data that is to be used with the handler.