pydicom.pixels.decoders.base.Decoder¶

class pydicom.pixels.decoders.base.Decoder(uid: UID)[source]¶

Factory class for pixel data decoders.

Every available Decoder instance in pydicom corresponds directly to a single DICOM Transfer Syntax UID, and provides a mechanism for decoding encoded source data using one or more decoding plugins.

Added in version 3.0.

__init__(uid: UID) → None[source]¶

Create a new data decoder.

Parameters:: uid (pydicom.uid.UID) – The Transfer Syntax UID that the decoder supports.

Methods

`__init__`(uid)	Create a new data decoder.
`add_plugin`(label, import_path)	Add a plugin to the class instance.
`add_plugins`(plugins)	Add multiple plugins to the class instance.
`as_array`(src, *[, index, validate, raw, ...])	Return decoded pixel data as `ndarray`.
`as_buffer`(src, *[, index, validate, ...])	Return the raw decoded pixel data as a buffer-like.
`iter_array`(src, *[, indices, raw, validate, ...])	Yield pixel data frames as `ndarray`.
`iter_buffer`(src, *[, indices, validate, ...])	Yield raw decoded pixel data frames as a buffer-like.
`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[source]¶

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

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')).

as_array(src: Dataset | Buffer | BinaryIO, *, index: int | None = None, validate: bool = True, raw: bool = False, decoding_plugin: str = '', **kwargs: DecodeOptions) → tuple[np.ndarray, dict[str, str | int]][source]¶

Return decoded pixel data as ndarray.

Warning

This method requires NumPy and may require the installation of additional packages to perform the actual pixel data decoding. See the pixel data decompression documentation for more information.

Processing

The following processing operations on the raw pixel data are always performed:

Natively encoded bit-packed pixel data for a bits allocated of 1 will be unpacked.
Natively encoded pixel data with a photometric interpretation of "YBR_FULL_422" will have it’s sub-sampling removed.
The output array will be reshaped to the specified dimensions.
JPEG-LS or JPEG 2000 encoded data whose signedness doesn’t match the expected pixel representation will be converted to match.

If raw = False (the default) then the following processing operation will also be performed:

Pixel data with a photometric interpretation of "YBR_FULL" or "YBR_FULL_422" will be converted to RGB.

Parameters:

src (Dataset | buffer-like | file-like) –
Single or multi-frame pixel data as one of the following:
- Dataset: a dataset containing the pixel data to be decoded and the corresponding Image Pixel module elements.
- bytes | bytearray | memoryview: the encoded (and possibly encapsulated) pixel data to be decoded.
- BinaryIO: a file-like positioned at the start of the pixel data element’s value. The position will be returned to the starting offset prior to returning the array.
When src is not a Dataset then a number of keyword parameters are also required. Please see the decoding options documentation for more information.
index (int | None, optional) – If None (default) then return an array containing all the frames in the pixel data, otherwise return one containing only the frame from the specified index, which starts at 0 for the first frame.
raw (bool, optional) – If True then return the decoded pixel data after only minimal processing (see the processing section above). If False (default) then additional processing may be applied to convert the pixel data to it’s most commonly used form (such as converting from YCbCr to RGB). To return the raw pixel data with no processing whatsoever, use the as_buffer() method.
validate (bool, optional) – If True (default) then validate the supplied decoding options and encoded pixel data prior to decoding, otherwise if False no validation will be performed.
decoding_plugin (str, optional) – The name of the decoding plugin to use when decoding compressed pixel data. If no decoding_plugin is specified (default) then all available plugins will be tried and the result from the first successful one returned. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding are also available, please see the decoding options documentation for more information.

Returns:

numpy.ndarray – One or more frames of decoded pixel data 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, multi-sample data
The dtype for the array will have an itemsize sufficient to contain pixels of at least bits allocated.

A writeable ndarray is returned by default. For native transfer syntaxes with view_only=True, a read-only ndarray will be returned if src is immutable.
dict[str, str | int] – The Image Pixel module element values resulting from the decoding process that describe the array. See DecodeRunner.pixel_properties() for the possible contents.

Return the raw decoded pixel data as a buffer-like.

Warning

This method should only be used by advanced users who understand the intricacies of converting raw decoded DICOM pixel data to a usable form. It may also require the installation of additional packages to perform the actual pixel data decoding (see the pixel data decompression documentation for more information).

Parameters:

src (Dataset | buffer-like | file-like) –
Single or multi-frame pixel data as one of the following:
- Dataset: a dataset containing the pixel data to be decoded and the corresponding Image Pixel module elements.
- bytes | bytearray | memoryview: the encoded (and possibly encapsulated) pixel data to be decoded.
- BinaryIO: a file-like positioned at the start of the pixel data element’s value. The position will be returned to the starting offset prior to returning the buffer.
When src is not a Dataset then a number of keyword parameters are also required. Please see the decoding options documentation for more information.
index (int | None, optional) – If None (default) then return a buffer-like containing all the frames in the pixel data, otherwise return one containing only the frame from the specified index, which starts at 0 for the first frame.
validate (bool, optional) – If True (default) then validate the supplied decoding options and encoded pixel data prior to decoding, otherwise if False no validation will be performed.
decoding_plugin (str, optional) – The name of the decoding plugin to use when decoding compressed pixel data. If no decoding_plugin is specified (default) then all available plugins will be tried and the result from the first successful one returned. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding are also available, please see the decoding options documentation for more information.

Returns:

bytes | bytearray | memoryview – One or more frames of raw decoded pixel data.

For natively encoded pixel data when src is a buffer-like the same type in src will be returned, except if view_only is True in which case a memoryview on the original buffer will be returned instead. If src is a file-like then bytes will always be returned.

8-bit pixel data encoded as OW using Explicit VR Big Endian will be returned as-is and may need byte-swapping. To facilitate this an extra byte before the expected start (for an odd index) or after the expected end (for an even index) is returned if the frame contains an odd number of pixels.
dict[str, str | int] – The Image Pixel module element values resulting from the decoding process that describe the decoded pixel data. See DecodeRunner.pixel_properties() for the possible contents.

property available_plugins: tuple[str, ...]¶: Return a tuple containing available plugins.

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_array(src: Dataset | Buffer | BinaryIO, *, indices: Iterable[int] | None = None, raw: bool = False, validate: bool = True, decoding_plugin: str = '', **kwargs: Any) → Iterator[tuple[np.ndarray, dict[str, str | int]]][source]¶

Yield pixel data frames as ndarray.

Warning

This method requires NumPy and may require the installation of additional packages to perform the actual pixel data decoding. See the pixel data decompression documentation for more information.

Processing

The following processing operations on the raw pixel data are always performed:

Natively encoded bit-packed pixel data for a bits allocated of 1 will be unpacked.
Natively encoded pixel data with a photometric interpretation of "YBR_FULL_422" will have it’s sub-sampling removed.
The output array will be reshaped to the specified dimensions.
JPEG-LS or JPEG 2000 encoded data whose signedness doesn’t match the expected pixel representation will be converted to match.

If raw = False (the default) then the following processing operation will also be performed:

Pixel data with a photometric interpretation of "YBR_FULL" or "YBR_FULL_422" will be converted to "RGB".

Parameters:

src (Dataset | buffer-like | file-like) –
Single or multi-frame pixel data as one of the following:
- Dataset: a dataset containing the pixel data to be decoded and the corresponding Image Pixel module elements.
- bytes | bytearray | memoryview: the encoded (and possibly encapsulated) pixel data to be decoded.
- BinaryIO: a file-like positioned at the start of the pixel data element’s value. The position will be returned to the starting offset only after all frames have been yielded.
When src is not a Dataset then a number of keyword parameters are also required. Please see the decoding options documentation for more information.
indices (Iterable[int] | None, optional) – If None (default) then iterate through the entire pixel data, otherwise only iterate through the frames specified by indices.
raw (bool, optional) – If True then yield the decoded pixel data after only minimal processing (see the processing section above). If False (default) then additional processing may be applied to convert the pixel data to it’s most commonly used form (such as converting from YCbCr to RGB). To yield frames of pixel data with no processing whatsoever, use the iter_buffer() method.
validate (bool, optional) – If True (default) then validate the supplied decoding options and encoded pixel data prior to decoding, otherwise if False no validation will be performed.
decoding_plugin (str, optional) – The name of the decoding plugin to use when decoding compressed pixel data. If no decoding_plugin is specified (default) then all available plugins will be tried and the result from the first successful one yielded. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding are also available, please see the decoding options documentation for more information.

Yields:

numpy.ndarray – A single frame of decoded and reshaped pixel data, with shape:
- (rows, columns) for single sample data
- (rows, columns, samples) for multi-sample data
The dtype for the array will have an itemsize sufficient to contain pixels of at least bits allocated.

A writeable ndarray is returned by default. For native transfer syntaxes with view_only=True a read-only ndarray will be yielded if src is immutable.
dict[str, str | int] – The Image Pixel module element values resulting from the decoding process that describe the array. See DecodeRunner.pixel_properties() for the possible contents.

Yield raw decoded pixel data frames as a buffer-like.

Warning

This method should only be used by advanced users who understand the intricacies of converting raw decoded DICOM pixel data to a usable form. It may also require the installation of additional packages to perform the actual pixel data decoding (see the pixel data decompression documentation for more information).

Parameters:

src (Dataset | buffer-like | file-like) –
Single or multi-frame pixel data as one of the following:
- Dataset: a dataset containing the pixel data to be decoded and the corresponding Image Pixel module elements.
- bytes | bytearray | memoryview: the encoded (and possibly encapsulated) pixel data to be decoded.
- BinaryIO: a file-like positioned at the start of the pixel data element’s value. The position will be returned to the starting offset only after all frames have been yielded.
When src is not a Dataset then a number of keyword parameters are also required. Please see the decoding options documentation for more information.
indices (Iterable[int] | None, optional) – If None (default) then iterate through the entire pixel data, otherwise only iterate through the frames specified by indices.
validate (bool, optional) – If True (default) then validate the supplied decoding options and encoded pixel data prior to decoding, otherwise if False no validation will be performed.
decoding_plugin (str, optional) – The name of the decoding plugin to use when decoding compressed pixel data. If no decoding_plugin is specified (default) then all available plugins will be tried and the result from the first successful one yielded. For information on the available plugins for each decoder see the API documentation.
**kwargs – Optional keyword parameters for controlling decoding are also available, please see the decoding options documentation for more information.

Yields:

bytes | bytearray | memoryview – A single frame of decoded pixel data.
- For natively encoded pixel data when src is a buffer-like the same type in src will be yielded, except if view_only is True in which case a memoryview on the original buffer will be yielded instead. If src is a file-like then bytes will always be yielded.
- Encapsulated pixel data will be yielded as bytearray.
8-bit pixel data encoded as OW using Explicit VR Big Endian will be yielded as-is and may need byte-swapping. To facilitate this an extra byte before the expected start (for an odd index) or after the expected end (for an even index) is yielded if the frame contains an odd number of pixels.
dict[str, str | int] – The Image Pixel module element values resulting from the decoding process that describe the decoded frame of pixel data. See DecodeRunner.pixel_properties() for the possible contents.

property missing_dependencies: list[str]¶: Return nice strings for plugins with missing dependencies.

remove_plugin(label: str) → None[source]¶

Remove a plugin.

Warning

This method is not thread-safe.

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