pydicom.pixels.encoders.base.EncodeRunner

class pydicom.pixels.encoders.base.EncodeRunner(tsyntax: UID)

Class for managing the pixel data encoding process.

Added in version 3.0.

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

__init__(tsyntax: UID) → None

Create a new runner for encoding data as tsyntax.

Parameters:

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

Methods

__init__(tsyntax)	Create a new runner for encoding data as tsyntax.
del_option(name)	Delete option name from the runner.
encode(index)	Return an encoded frame of pixel data as bytes.
frame_length([unit])	Return the expected length (in number of bytes or pixels) of each frame of pixel data.
get_frame(index)	Return a frame's worth of uncompressed pixel data as bytes.
get_option(name[, default])	Return the value of the option name.
set_encoders(encoders)	Set the encoders use for encoding 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 encoded.
validate()	Validate the encoding options and source pixel data.

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_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 numpy.ndarray containing the 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.

del_option(name: str) → None

Delete option name from the runner.

encode(index: int | None) → bytes

Return an encoded frame of pixel data as bytes.

Parameters:

index (int | None) – If index is None then the pixel data only contains one frame, otherwise index is the frame number to be encoded.

Returns:

The encoded pixel data frame.

Return type:

bytes

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_frame(index: int | None) → bytes

Return a frame’s worth of uncompressed pixel data as bytes.

Parameters:

index (int | None) – If the pixel data only has one from then use None, otherwise index is the index of the frame to be returned.

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

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_keyword: str

Return the expected pixel keyword of the data.

Returns:

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

Return type:

str

property pixel_representation: int

Return the expected pixel representation of the data.

property planar_configuration: int

Return the expected planar configuration of the data.

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_encoders(encoders: dict[str, Callable[[bytes, EncodeRunner], bytes | bytearray]]) → None

Set the encoders use for encoding compressed pixel data.

Parameters:

encoders (dict[str, EncodeFunction]) – A dict of {name: encoder 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: np.ndarray | Dataset | Buffer) → None

Set the pixel data to be encoded.

Parameters:

src (bytes | bytearray | memoryview | pydicom.dataset.Dataset | numpy.ndarray) –

• If a buffer-like then the encoded pixel data

• If a Dataset then a dataset containing the pixel data and associated group 0x0028 elements.

• If a numpy.ndarray then an array containing the image data.

property src: bytes | bytearray | memoryview | ndarray

Return the buffer-like or numpy.ndarray containing the pixel data.

property transfer_syntax: UID

Return the expected transfer syntax corresponding to the data.

validate() → None

Validate the encoding options and source pixel data.