# pydicom.encoders.base.Encoder

class pydicom.encoders.base.Encoder(uid: UID)

  Factory class for data encoders.

  Every available `Encoder` instance in pydicom corresponds directly to a single DICOM Transfer Syntax UID, and provides a mechanism for converting raw unencoded source data to meet the requirements of that transfer syntax using one or more encoding plugins.

  Added in version 2.2.

  __init__(uid: UID) → None

    Create a new data encoder.

    Parameters:

      uid (pydicom.uid.UID) – The Transfer Syntax UID that the encoder supports.

  Methods

  `__init__`(uid) | Create a new data encoder.
  `add_plugin`(label, import_path) | Add an encoding plugin to the encoder.
  `encode`(src[, idx, encoding_plugin, ...]) | Return an encoded frame of the pixel data in src as `bytes`.
  `iter_encode`(src[, encoding_plugin, ...]) | Yield encoded frames of the pixel data in src as `bytes`.
  `kwargs_from_ds`(ds) | Return a kwargs dict from ds.
  `remove_plugin`(label) | Remove a plugin from the encoder.

  Attributes

  `UID` | Return the encoder's corresponding Transfer Syntax UID as `UID`.
  `is_available` | Return `True` if the encoder has plugins available that can be used to encode data, `False` otherwise.
  `missing_dependencies` | Return nice strings for plugins with missing dependencies as List[str].
  `name` | Return the name of the encoder as `str`.

  property UID: UID

    Return the encoder’s corresponding Transfer Syntax UID as `UID`.

  add_plugin(label: str, import_path: Tuple[str, str]) → None

    Add an encoding plugin to the encoder.

    The requirements for encoding plugins are available here.

    Parameters:

      - label (str) – The label to use for the plugin, should be unique for the encoder.

      - import_path (Tuple[str, str]) – The module import path and the encoding function’s name (e.g. `('pydicom.encoders.pylibjpeg', 'encode_pixel_data')`).

    Raises:

      - ModuleNotFoundError – If the module import path is incorrect or unavailable.

      - AttributeError – If the plugin’s encoding function, `is_available()` or `ENCODER_DEPENDENCIES` aren’t found in the module.

  encode(src: bytes | numpy.ndarray | Dataset, idx: int | None = None, encoding_plugin: str = '', decoding_plugin: str = '', **kwargs: Any) → bytes

    Return an encoded frame of the pixel data in src as `bytes`.

    Parameters:

      - src (bytes, numpy.ndarray or pydicom.dataset.Dataset) –

        Single or multi-frame pixel data as one of the following:

        - `ndarray`: the uncompressed pixel data, should be `shaped` as:

          - (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 and multi-sample data.

        - `Dataset`: the dataset containing the uncompressed Pixel Data to be encoded.

        - `bytes`: the uncompressed little-endian ordered pixel data. Using `bytes` as the src will bypass some of the validation checks and is only recommended for advanced users.

      - idx (int, optional) – Required when src contains multiple frames, this is the index of the frame to be encoded.

      - encoding_plugin (str, optional) – The name of the pixel data encoding plugin to use. If encoding_plugin is not specified then all available plugins will be tried (default). For information on the available plugins for each encoder see the `API documentation`.

      - decoding_plugin (str, optional) – Placeholder for future functionality.

      - **kwargs –

        The following keyword parameters are required when src is `bytes` or `ndarray`:

        - `'rows'`: `int` - the number of rows of pixels in src, maximum 65535.

        - `'columns'`: `int` - the number of columns of pixels in src, maximum 65535.

        - `'number_of_frames'`: `int` - the number of frames in src.

        - `'samples_per_pixel'`: `int` - the number of samples per pixel in src, should be 1 or 3.

        - `'bits_allocated'`: `int` - the number of bits used to contain each pixel, should be a multiple of 8.

        - `'bits_stored'`: `int` - the number of bits actually used per pixel. For example, an `ndarray` src might have a `dtype` of `'uint16'` (range 0 to 65535) but only contain 12-bit pixel values (range 0 to 4095).

        - `'pixel_representation'`: `int` - the type of data being encoded, `0` for unsigned, `1` for 2’s complement (signed)

        - `'photometric_interpretation'`: `str` - the intended color space of the encoded pixel data, such as `'YBR_FULL'`.

        Optional keyword parameters for the encoding plugin may also be present. See the encoding plugin options for more information.

    Returns:

      The encoded pixel data.

    Return type:

      bytes

  property is_available: bool

    Return `True` if the encoder has plugins available that can be used to encode data, `False` otherwise.

  iter_encode(src: bytes | numpy.ndarray | Dataset, encoding_plugin: str = '', decoding_plugin: str = '', **kwargs: Any) → Iterator[bytes]

    Yield encoded frames of the pixel data in src as `bytes`.

    Parameters:

      - src (bytes, numpy.ndarray or pydicom.dataset.Dataset) –

        Single or multi-frame pixel data as one of the following:

        - `ndarray`: the uncompressed pixel data, should be `shaped` as:

          - (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 and multi-sample data.

        - `Dataset`: the dataset containing the uncompressed Pixel Data to be encoded.

        - `bytes`: the uncompressed little-endian ordered pixel data. Using `bytes` as the src will bypass some of the validation checks and is only recommended for advanced users.

      - encoding_plugin (str, optional) – The name of the pixel data encoding plugin to use. If encoding_plugin is not specified then all available plugins will be tried (default). For information on the available plugins for each encoder see the `API documentation`.

      - decoding_plugin (str, optional) – If src is a `Dataset` containing compressed Pixel Data then this is the name of the `pixel data decoding handler`. If decoding_plugin is not specified then all available handlers will be tried (default).

      - **kwargs –

        The following keyword parameters are required when src is `bytes` or `ndarray`:

        - `'rows'`: `int` - the number of rows of pixels in src, maximum 65535.

        - `'columns'`: `int` - the number of columns of pixels in src, maximum 65535.

        - `'number_of_frames'`: `int` - the number of frames in src.

        - `'samples_per_pixel'`: `int` - the number of samples per pixel in src, should be 1 or 3.

        - `'bits_allocated'`: `int` - the number of bits used to contain each pixel, should be a multiple of 8.

        - `'bits_stored'`: `int` - the number of bits actually used per pixel. For example, an `ndarray` src might have a `dtype` of `'uint16'` (range 0 to 65535) but only contain 12-bit pixel values (range 0 to 4095).

        - `'pixel_representation'`: `int` - the type of data being encoded, `0` for unsigned, `1` for 2’s complement (signed)

        - `'photometric_interpretation'`: `str` - the intended color space of the encoded pixel data, such as `'YBR_FULL'`.

        Optional keyword parameters for the encoding plugin may also be present. See the encoding plugin options for more information.

    Yields:

      bytes – An encoded frame of pixel data.

  static kwargs_from_ds(ds: Dataset) → Dict[str, int | str]

    Return a kwargs dict from ds.

    Parameters:

      ds (pydicom.dataset.Dataset) – The dataset to use as a source of keyword parameters.

    Returns:

      A dict with the following keys, with values from the corresponding dataset elements:

      - `'rows'`: `int`

      - `'columns'`: `int`

      - `'samples_per_pixel'`: `int`

      - `'number_of_frames'`: `int`, default `1` if not present

      - `'bits_allocated'`: `int`

      - `'bits_stored'`: `int`

      - `'pixel_representation'`: `int`

      - `'photometric_interpretation'`: `str`

    Return type:

      Dict[str, Union[int, str]]

  property missing_dependencies: List[str]

    Return nice strings for plugins with missing dependencies as List[str].

  property name: str

    Return the name of the encoder as `str`.

  remove_plugin(label: str) → None

    Remove a plugin from the encoder.

    Parameters:

      label (str) – The label of the plugin to remove.