pydicom.pixels.utils.compress

pydicom.pixels.utils.compress(ds: Dataset, transfer_syntax_uid: str, arr: np.ndarray | None = None, *, encoding_plugin: str = '', encapsulate_ext: bool = False, generate_instance_uid: bool = True, jls_error: int | None = None, j2k_cr: list[float] | None = None, j2k_psnr: list[float] | None = None, **kwargs: Any) → Dataset[source]

Compress uncompressed pixel data and update ds in-place with the resulting encapsulated codestream.

Added in version 3.0.

The dataset ds must already have the following Image Pixel module elements present with correct values that correspond to the resulting compressed pixel data:

  • (0028,0002) Samples per Pixel

  • (0028,0004) Photometric Interpretation

  • (0028,0008) Number of Frames (if more than 1 frame will be present)

  • (0028,0010) Rows

  • (0028,0011) Columns

  • (0028,0100) Bits Allocated

  • (0028,0101) Bits Stored

  • (0028,0103) Pixel Representation

If Samples per Pixel is greater than 1 then the following element is also required:

  • (0028,0006) Planar Configuration

This method will add the file meta dataset if none is present and add or modify the following elements:

  • (0002,0010) Transfer Syntax UID

  • (7FE0,0010) Pixel Data

If the compressed pixel data is too large for encapsulation using a basic offset table then an extended offset table will also be used, in which case the following elements will also be added:

  • (7FE0,0001) Extended Offset Table

  • (7FE0,0002) Extended Offset Table Lengths

If generate_instance_uid is True (default) then a new (0008,0018) SOP Instance UID value will be generated.

Supported Transfer Syntax UIDs

UID

Plugins

Encoding Guide

Name

Value

JPEG-LS Lossless

1.2.840.10008.1.2.4.80

pyjpegls

JPEG-LS

JPEG-LS Near Lossless

1.2.840.10008.1.2.4.81

JPEG 2000 Lossless

1.2.840.10008.1.2.4.90

pylibjpeg

JPEG 2000

JPEG 2000

1.2.840.10008.1.2.4.91

RLE Lossless

1.2.840.10008.1.2.5

pydicom, pylibjpeg, gdcm

RLE Lossless

Examples

Compress the existing uncompressed Pixel Data in place:

>>> from pydicom import examples
>>> from pydicom.pixels import compress
>>> from pydicom.uid import RLELossless
>>> ds = examples.ct
>>> compress(ds, RLELossless)
>>> ds.save_as("ct_rle_lossless.dcm")
Parameters:

  • ds (pydicom.dataset.Dataset) – The dataset to be compressed.

  • transfer_syntax_uid (pydicom.uid.UID) – The UID of the transfer syntax to use when compressing the pixel data.

  • arr (numpy.ndarray, optional) – Compress the uncompressed pixel data in arr and use it to set the Pixel Data. If arr is not used then the existing uncompressed Pixel Data in the dataset will be compressed instead. The shape, dtype and contents of the array should match the dataset.

  • encoding_plugin (str, optional) – Use encoding_plugin to compress the pixel data. See the user guide for a list of plugins available for each UID and their dependencies. If not specified then all available plugins will be tried (default).

  • encapsulate_ext (bool, optional) – If True then force the addition of an extended offset table. If False (default) then an extended offset table will be added if needed for large amounts of compressed Pixel Data, otherwise just the basic offset table will be used.

  • generate_instance_uid (bool, optional) – If True (default) then generate a new (0008,0018) SOP Instance UID value for the dataset using generate_uid(), otherwise keep the original value.

  • jls_error (int, optional) – JPEG-LS Near Lossless only. The allowed absolute compression error in the pixel values.

  • j2k_cr (list[float], optional) – JPEG 2000 only. A list of the compression ratios to use for each quality layer. There must be at least one quality layer and the minimum allowable compression ratio is 1. When using multiple quality layers they should be ordered in decreasing value from left to right. For example, to use 2 quality layers with 20x and 5x compression ratios then j2k_cr should be [20, 5]. Cannot be used with j2k_psnr.

  • j2k_psnr (list[float], optional) – JPEG 2000 only. A list of the peak signal-to-noise ratios (in dB) to use for each quality layer. There must be at least one quality layer and when using multiple quality layers they should be ordered in increasing value from left to right. For example, to use 2 quality layers with PSNR of 80 and 300 then j2k_psnr should be [80, 300]. Cannot be used with j2k_cr.

  • **kwargs – Optional keyword parameters for the encoding plugin may also be present. See the encoding plugins options for more information.