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: UID

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.