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

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.