pydicom.pixels.encoders.base.EncodeRunner

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

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

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

Delete option name from the runner.

encode(index: int | None) bytes[source]

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

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

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

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

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[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: np.ndarray | Dataset | Buffer) None[source]

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

Validate the encoding options and source pixel data.