# pydicom.pixels.encoders.base.Encoder

class pydicom.pixels.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 a plugin to the class instance.
  `add_plugins`(plugins) | Add multiple plugins to the class instance.
  `encode`(src, *[, index, validate, ...]) | Return an encoded frame of the pixel data in src as `bytes`.
  `iter_encode`(src, *[, validate, encoding_plugin]) | Yield encoded frames of the pixel data in src as `bytes`.
  `remove_plugin`(label) | Remove a plugin.

  Attributes

  `UID` | Return the corresponding Transfer Syntax UID as `UID`.
  `available_plugins` | Return a tuple containing available plugins.
  `is_available` | Return `True` if plugins are available that can be used to encode or decode data, `False` otherwise.
  `is_encapsulated` | Return `True` if the decoder is for an encapsulated transfer syntax, `False` otherwise.
  `is_native` | Return `True` if the decoder is for an native transfer syntax, `False` otherwise.
  `missing_dependencies` | Return nice strings for plugins with missing dependencies.

  property UID: <property object at 0x7dd5bdef2f70>

    Return the corresponding Transfer Syntax UID as `UID`.

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

    Add a plugin to the class instance.

    Warning

    This method is not thread-safe.

    The requirements for encoding plugins are available here, while the requirements for decoding plugins are available here.

    Only encoding plugins should be added to `Encoder` class instances and only decoding plugins should be added to `Decoder` class instances.

    Parameters:

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

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

    Raises:

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

      - AttributeError – If the plugin’s required functions and attributes aren’t found in the module.

  add_plugins(plugins: list[tuple[str, tuple[str, str]]]) → None

    Add multiple plugins to the class instance.

    Warning

    This method is not thread-safe.

    The requirements for encoding plugins are available here, while the requirements for decoding plugins are available here.

    Only encoding plugins should be added to `Encoder` class instances and only decoding plugins should be added to `Decoder` class instances.

    Parameters:

      plugins (list[tuple[str, tuple[str, str]]]) –

      A list of [label, import path] for the plugins, where:

      - label is the label to use for the plugin, which should be unique.

      - import path is the module import path and the function’s name (e.g. `('pydicom.pixels.encoders.pylibjpeg', 'encode_pixel_data')` or `('pydicom.pixels.decoders.pylibjpeg', 'decode_pixel_data')`).

  property available_plugins: tuple[str, ...]

    Return a tuple containing available plugins.

  encode(src: bytes | np.ndarray | Dataset, *, index: int | None = None, validate: bool = True, encoding_plugin: str = '', **kwargs: Any) → bytes

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

    Warning

    With the exception of RLE Lossless, this method requires the installation of additional packages to perform the actual pixel data encoding. See the encoding documentation for more information.

    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, planes) for single frame, multi-sample data.

          - (frames, rows, columns) for multi-frame, single sample data.

          - (frames, rows, columns, planes) 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. src should use 1, 2, 4 or 8 bytes per pixel, whichever of these is sufficient for the (0028,0103) Bits Stored value.

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

      - validate (bool, optional) – If `True` (default) then validate the supplied encoding options and pixel data prior to encoding, otherwise if `False` no validation will be performed.

      - 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`.

      - **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 plugins are available that can be used to encode or decode data, `False` otherwise.

  property is_encapsulated: bool

    Return `True` if the decoder is for an encapsulated transfer syntax, `False` otherwise.

  property is_native: bool

    Return `True` if the decoder is for an native transfer syntax, `False` otherwise.

  iter_encode(src: bytes | np.ndarray | Dataset, *, validate: bool = True, encoding_plugin: str = '', **kwargs: Any) → Iterator[bytes]

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

    Warning

    With the exception of RLE Lossless, this method requires the installation of additional packages to perform the actual pixel data encoding. See the encoding documentation for more information.

    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, planes) for single frame, multi-sample data.

          - (frames, rows, columns) for multi-frame, single sample data.

          - (frames, rows, columns, planes) 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. src should use 1, 2, 4 or 8 bytes per pixel, whichever of these is sufficient for the (0028,0103) Bits Stored value.

      - validate (bool, optional) – If `True` (default) then validate the supplied encoding options and pixel data prior to encoding, otherwise if `False` no validation will be performed.

      - 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`.

      - **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.

  property missing_dependencies: list[str]

    Return nice strings for plugins with missing dependencies.

  remove_plugin(label: str) → None

    Remove a plugin.

    Warning

    This method is not thread-safe.

    Parameters:

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