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.

New 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, 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.