pydicom.pixels.decoders.base.DecodeRunner#

class pydicom.pixels.decoders.base.DecodeRunner(tsyntax: UID)[source]#

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

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_dtype`(index)	Return a `numpy.dtype` suitable for containing the pixel data for the decoded frame at index.
`frame_length`([unit, index])	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_frame_option`(index, name[, default])	Return the value of the option name for all frames or the frame at index.
`get_option`(name[, default])	Return the value of the option name.
`iter_decode`()	Yield decoded frames from the encoded pixel data.
`pixel_properties`(index[, as_frame])	Return a dict containing the Image Pixel module related properties, must be called after decoding frame index has been completed.
`process`(arr, index)	Return arr after applying zero or more processing operations.
`reshape`(arr, index[, as_frame])	Return a reshaped `ndarray` arr.
`set_decoders`(decoders)	Set the decoders use for decoding compressed pixel data.
`set_frame_option`(index, name, value)	Set an option for the frame at index.
`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
`index`	Return the index of the frame currently being encoded or decoded.
`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`
`is_encapsulated`	Return `True` if the corresponding Transfer Syntax UID uses an encapsulated encoding.
`is_native`	Return `True` if the corresponding Transfer Syntax UID uses native encoding.
`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[source]#

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[source]#: 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_dtype(index: int) → dtype[source]#

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

Added in version 3.1.

Parameters:: index (int) – The index of the frame to return the dtype for.

frame_length(unit: str = 'bytes', index: int | None = None) → int | float[source]#

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

Changed in version 3.1: Added the index parameter.

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").
index (int | None, optional) – If None return the length determined using the expected pixel data property values (default), otherwise return the length calculated using the property values determined during encoding or decoding for the frame at index.

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 Bits Allocated 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[source]#

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_frame_option(index: int | None, name: str, default: Any = None) → Any[source]#

Return the value of the option name for all frames or the frame at index.

Added in version 3.1.

Parameters:

index (int | None) – The index of the frame to get the option for, or if None then the corresponding value for all frames.
name (str) – The name of the option to get.
default (Any, optional) – The value to return if either index or name is not found.

Returns:

The option value for the frame at index or the default if no such frame exists or if no name option exists.

Return type:

Any

Raises:

ValueError – If index is None and multiple inconsistent values for the option are found.

get_option(name: str, default: Any = None) → Any[source]#: Return the value of the option name.

property index: int#: Return the index of the frame currently being encoded or decoded.

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

property is_encapsulated: bool#: Return True if the corresponding Transfer Syntax UID uses an encapsulated encoding.

property is_native: bool#: Return True if the corresponding Transfer Syntax UID uses native encoding.

iter_decode() → Iterator[bytes | bytearray][source]#: Yield decoded frames from the encoded pixel data.

Changed in version 3.1: Add support for encapsulated single bit images (Bits Allocated = 1)

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(index: int | None, as_frame: bool = False) → dict[str, str | int][source]#

Return a dict containing the Image Pixel module related properties, must be called after decoding frame index has been completed.

Changed in version 3.1: Added the index parameter.

Deprecated since version 3.1: The as_frame parameter will be removed in v4.0, use index instead.

Parameters:

index (int | None) – If None then return the properties for the entire (single or multi-framed) pixel data, otherwise return the properties for the frame at index.
as_frame (bool, optional) – If True then return the properties for a single frame (requires passing the frame’s index as index), otherwise return the properties for the entire pixel data (requires passing None as the index).

Returns:

A dict containing the values for:

bits_allocated
bits_stored (if the pixel keyword is "PixelData")
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")

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, index: int | None) → tuple[ndarray, DecodeOptions][source]#

Return arr after applying zero or more processing operations.

Changed in version 3.1: Added the index parameter.

Parameters:

arr (np.ndarray) – The image data to process, may be the entire single or multi-framed pixel data (if index is None) or the data from a single frame (if index is not None).
index (int | None) – If None then arr contains the entire pixel data and may be single or multi-framed, otherwise arr contains the data from the single frame at index.

Returns:

numpy.ndarray – The array with the applied processing.
dict[str, int | str] – A dict containing the changes to the image pixel properties due to the processing, will be empty if index is not None.

reshape(arr: ndarray, index: int | None, as_frame: bool = False) → ndarray[source]#

Return a reshaped ndarray arr.

Changed in version 3.1: Added the index parameter.

Deprecated since version 3.1: The as_frame parameter will be removed in v4.0, use index instead.

Parameters:

arr (np.ndarray) – The 1D array to be reshaped.
index (int | None) – If None then arr contains the entire (single or multi-framed) pixel data, otherwise arr contains a single frame’s worth of pixel data for the frame at index.
as_frame (bool, optional) – If True then treat arr as only containing a single frame’s worth of pixel data (requires passing the frame’s index as index), otherwise treat arr as containing the full amount of pixel data which requires passing None as the index (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[source]#

Set the decoders use for decoding compressed pixel data.

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

set_frame_option(index: int, name: str, value: Any) → None[source]#

Set an option for the frame at index.

Added in version 3.1.

Parameters:

index (int) – The index of the frame to set the option for.
name (str) – The name of the option to set.
value (Any) – The value of the option.

set_option(name: str, value: Any) → None[source]#

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

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

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[source]#: Validate the decoding options and source buffer (if any).