pydicom.pixels.utils.unpack_bits

pydicom.pixels.utils.unpack_bits(src: bytes, as_array: bool = True) → ndarray | bytes[source]

Unpack the bit-packed data in src.

Suitable for use when (0028,0011) Bits Allocated or (60xx,0100) Overlay Bits Allocated is 1.

If NumPy is available then it will be used to unpack the data, otherwise only the standard library will be used, which is about 20 times slower.

Changed in version 2.3: Added the as_array keyword parameter, support for unpacking without NumPy, and added bytes as a possible return type

Parameters:

  • src (bytes) – The bit-packed data.

  • as_array (bool, optional) – If False then return the unpacked data as bytes, otherwise return a numpy.ndarray (default, requires NumPy).

Returns:

The unpacked data as an numpy.ndarray (if NumPy is available and as_array == True) or bytes otherwise.

Return type:

bytes or numpy.ndarray

Raises:

ValueError – If as_array is True and NumPy is not available.

References

DICOM Standard, Part 5, Section 8.1.1 and Annex D