pydicom.pixels.decoders.base.DecodeRunner

class pydicom.pixels.decoders.base.DecodeRunner(tsyntax: UID)

Class for managing the pixel data decoding process.

Added in version 3.0.

This class is not intended to be used directly. For decoding pixel data use the Decoder instance corresponding to the transfer syntax of the pixel data.

__init__(tsyntax: UID) → None

Create a new runner for decoding data encoded as tsyntax.

Parameters:

tsyntax (pydicom.uid.UID) – The transfer syntax UID corresponding to the pixel data to be decoded.

Methods

__init__(tsyntax)	Create a new runner for decoding data encoded as tsyntax.
decode(index)	Decode the frame of pixel data at index.
del_option(name)	Delete option name from the runner.
frame_length([unit])	Return the expected length (in number of bytes or pixels) of each frame of pixel data.
get_data(src, offset, length)	Return length bytes from src, starting at offset.
get_option(name[, default])	Return the value of the option name.
iter_decode()	Yield decoded frames from the encoded pixel data.
pixel_properties([as_frame])	Return a dict containing the Image Pixel module related properties.
process(arr)	Return arr after applying zero or more processing operations.
reshape(arr[, as_frame])	Return a reshaped ndarray arr.
set_decoders(decoders)	Set the decoders use for decoding compressed pixel data.
set_option(name, value)	Set a runner option.
set_options(**kwargs)	Set multiple runner options.
set_source(src)	Set the pixel data to be decoded.
validate()	Validate the decoding options and source buffer (if any).

Attributes

bits_allocated	Return the expected number of bits allocated used by the data.
bits_stored	Return the expected number of bits stored used by the data.
columns	Return the expected number of columns in the data.
extended_offsets	Return the extended offsets table and lengths
is_array	Return True if the pixel data source is an ndarray
is_binary	Return True if the pixel data source is BinaryIO
is_buffer	Return True if the pixel data source is a buffer-like
is_dataset	Return True if the pixel data source is a Dataset
number_of_frames	Return the expected number of frames in the data.
options	Return a reference to the runner's options dict.
photometric_interpretation	Return the expected photometric interpretation of the data.
pixel_dtype	Return a numpy.dtype suitable for containing the decoded pixel data.
pixel_keyword	Return the expected pixel keyword of the data.
pixel_representation	Return the expected pixel representation of the data.
planar_configuration	Return the expected planar configuration of the data.
rows	Return the expected number of rows in the data.
samples_per_pixel	Return the expected number of samples per pixel in the data.
src	Return the buffer-like or file-like containing the encoded pixel data.
transfer_syntax	Return the expected transfer syntax corresponding to the data.

property bits_allocated: int

Return the expected number of bits allocated used by the data.

property bits_stored: int

Return the expected number of bits stored used by the data.

property columns: int

Return the expected number of columns in the data.

decode(index: int) → bytes | bytearray

Decode the frame of pixel data at index.

Parameters:

index (int) – The index of the frame to be decoded.

Returns:

The decoded frame of pixel data.

Return type:

bytes | bytearray

del_option(name: str) → None

Delete option name from the runner.

property extended_offsets: tuple[list[int], list[int]] | tuple[bytes, bytes] | None

Return the extended offsets table and lengths

Returns:

Returns the extended offsets and lengths as either lists of int or their equivalent encoded values, or None if no extended offsets have been set.

Return type:

tuple[list[int], list[int]] | tuple[bytes, bytes] | None

frame_length(unit: str = 'bytes') → int | float

Return the expected length (in number of bytes or pixels) of each frame of pixel data.

Parameters:

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

Returns:

The expected length of a single frame of pixel data in either whole bytes or pixels, excluding the NULL trailing padding byte for odd length data. For “pixels”, an integer will always be returned. For “bytes”, a float will be returned for images with BitsAllocated of 1 whose frames do not consist of a whole number of bytes.

Return type:

int | float

get_data(src: bytes | bytearray | memoryview | BinaryIO, offset: int, length: int) → bytes

Return length bytes from src, starting at offset.

Parameters:

• src (buffer-like | file-like) – The source of the data to be returned. If a file-like then the file position after reading will returned to the original offset.

• offset (int) – The starting offset of the data in src.

• length (int) – The number of bytes to try to return.

Returns:

The data from src, may return fewer bytes if the end of src is reached before offset + length.

Return type:

bytes

get_option(name: str, default: Any | None = None) → Any

Return the value of the option name.

property is_array: bool

Return True if the pixel data source is an ndarray

property is_binary: bool

Return True if the pixel data source is BinaryIO

property is_buffer: bool

Return True if the pixel data source is a buffer-like

property is_dataset: bool

Return True if the pixel data source is a Dataset

iter_decode() → Iterator[bytes | bytearray]

Yield decoded frames from the encoded pixel data.

property number_of_frames: int

Return the expected number of frames in the data.

property options: DecodeOptions | EncodeOptions

Return a reference to the runner’s options dict.

property photometric_interpretation: str

Return the expected photometric interpretation of the data.

property pixel_dtype: dtype

Return a numpy.dtype suitable for containing the decoded pixel data.

property pixel_keyword: str

Return the expected pixel keyword of the data.

Returns:

One of "PixelData", "FloatPixelData", "DoubleFloatPixelData"

Return type:

str

pixel_properties(as_frame: bool = False) → dict[str, str | int]

Return a dict containing the Image Pixel module related properties.

Parameters:

as_frame (bool, optional) – If True then don’t include properties that aren’t appropriate for a single frame. Default False.

Returns:

A dict containing the values for:

• bits_allocated

• bits_stored

• columns

• photometric_interpretation

• samples_per_pixel

• rows

• number_of_frames

• planar_configuration (if samples_per_pixel > 1)

• pixel_representation (if the pixel keyword is "PixelData")

The returned values depend on whether or not this method is called before or after decoding the pixel data, as the decoding plugins and image processing functions may update the values as needed to reflect the corresponding decoded data. For example, if the pixel data is converted from the YCbCr to RGB color space then the photometric_interpretation value will be changed to match after the data has been decoded.

Return type:

dict[str, str | int]

property pixel_representation: int

Return the expected pixel representation of the data.

property planar_configuration: int

Return the expected planar configuration of the data.

process(arr: ndarray) → tuple[np.ndarray, dict[str, str | int]]

Return arr after applying zero or more processing operations.

Returns:

• numpy.ndarray – The array with the applied processing.

• dict[str, int | str] – A dict containing any required changes to the image pixel properties due to the processing.

reshape(arr: ndarray, as_frame: bool = False) → ndarray

Return a reshaped ndarray arr.

Parameters:

• arr (np.ndarray) – The 1D array to be reshaped.

• as_frame (bool, optional) – If True then treat arr as only containing a single frame’s worth of pixel data, otherwise treat arr as containing the full amount of pixel data (default).

Returns:

A view of the input arr reshaped to:

• (rows, columns) for single frame, single sample data

• (rows, columns, samples) for single frame, multi-sample data

• (frames, rows, columns) for multi-frame, single sample data

• (frames, rows, columns, samples) for multi-frame, multi-sample data

Return type:

np.ndarray

property rows: int

Return the expected number of rows in the data.

property samples_per_pixel: int

Return the expected number of samples per pixel in the data.

set_decoders(decoders: dict[str, Callable[[bytes, DecodeRunner], bytes | bytearray]]) → None

Set the decoders use for decoding compressed pixel data.

Parameters:

decoders (dict[str, DecodeFunction]) – A dict of {name: decoder function}.

set_option(name: str, value: Any) → None

Set a runner option.

Parameters:

• name (str) – The name of the option to be set.

• value (Any) – The value of the option.

set_options(**kwargs: DecodeOptions | EncodeOptions) → None

Set multiple runner options.

Parameters:

kwargs (dict[str, Any]) – A dictionary containing the options as {name: value}, where name is the name of the option and value is it’s value.

set_source(src: Buffer | Dataset | BinaryIO) → None

Set the pixel data to be decoded.

Parameters:

src (bytes | bytearray | memoryview | pydicom.dataset.Dataset) – If a buffer-like then the encoded pixel data, otherwise the Dataset containing the pixel data and associated group 0x0028 elements.

property src: bytes | bytearray | memoryview | BinaryIO

Return the buffer-like or file-like containing the encoded pixel data.

property transfer_syntax: UID

Return the expected transfer syntax corresponding to the data.

validate() → None

Validate the decoding options and source buffer (if any).