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[source]

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

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[source]

Return a numpy.ndarray of the Overlay Data.

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[source]

Return True if the handler has its dependencies met.

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

Return a reshaped numpy.ndarray arr.

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