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