# 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) → 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[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).