pydicom.encoders.base.Encoder

class pydicom.encoders.base.Encoder(uid: UID)[source]

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.

New in version 2.2.

__init__(uid: UID) None[source]

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

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

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

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

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

Remove a plugin from the encoder.

Parameters:

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