What's Changed

Major backwards-incompatible changes:

• The value for JPEGLossless has changed to 1.2.840.10008.1.2.4.57.
• The encoding used when saving datasets with dcmwrite() and Dataset.save_as() defaults to the set Transfer Syntax UID.
• Dataset.pixel_array will convert YCbCr Pixel Data to RGB by default when possible.
• read_file() and write_file() have been removed, use dcmread() and dcmwrite() instead.

Please see the release notes for a full list of changes.

New Contributors

• @smjoshiatglobus made their first contribution in #1820
• @radarhere made their first contribution in #1912
• @kwsp made their first contribution in #1960
• @erikogabrielsson made their first contribution in #1995
• @paddyroddy made their first contribution in #2018
• @jstark-tpx made their first contribution in #2069
• @or150 made their first contribution in #2078
• @naterichman made their first contribution in #1560
• @haraldreingruber-dedalus made their first contribution in #2119

Full Changelog: v2.4.4...v3.0.0

The major breaking changes with the version 3.0 release are:

The value for JPEGLossless has changed to 1.2.840.10008.1.2.4.57 .

The encoding used when saving datasets defaults to the set Transfer Syntax UID .

Dataset.pixel_array will convert YCbCr Pixel Data to RGB by default when possible.

read_file and write_file have been removed.

Changes

Removed support for Python <= 3.9.

All tag formats changed to upper case, no space e.g. “(7FE0,0010)” rather than “(7fe0, 0010)”.

Values with VR AE with an incorrect value length are now handled gracefully (extra bytes are ignored with a warning).

A value of 0 for Number of Frames is now handled as 1 frame, with a user warning issued on reading the pixel data ( #1844 ).

The value for JPEGLossless has changed from 1.2.840.10008.1.2.4.70 to 1.2.840.10008.1.2.4.57 to match its UID keyword. Use JPEGLosslessSV1 instead for 1.2.840.10008.1.2.4.70.

The theoretical maximum number of instances supported by FileSet has been reduced to 1838265625 to ensure support for 32-bit systems ( #1743 ).

The characters used by generate_filename() when alphanumeric is True has been reduced to [0-9][A-I,K-Z].

get_testdata_file() and get_testdata_files() now raise ValueError if called with an absolute path or pattern.

generate_uid() has been changed to use a random suffix generated using randbelow() when entropy_srcs isn’t used, and the maximum allowed length of the prefix has been changed to 54 characters ( #1773 ).

DataElement.VM always returns 1 for SQ elements ( #1481 ).

DICOM dictionary updated to 2024c.

Concepts dictionaries updated to 2024c.

validate_file_meta() now checks to ensure required Type 1 elements aren’t empty.

implicit_vr and little_endian optional arguments added to Dataset.save_as() . In addition, this method will now raise an exception if the user tries to convert between little and big endian datasets. If this is something you need, use dcmwrite() instead.

Added the overwrite argument to Dataset.save_as() and dcmwrite() to allow raising a FileExistsError if trying to write to a file that already exists ( #2104 ).

implicit_vr , little_endian and force_encoding optional arguments added to dcmwrite() .

The priority used to decide which encoding to use with Dataset.save_as() and dcmwrite() has been changed to:

The set Transfer Syntax UID ,

The implicit_vr and little_endian arguments,

Dataset.is_implicit_VR and Dataset.is_little_endian ,

Dataset.original_encoding .

Datasets containing Command Set (0000,eeee) elements can no longer be written using Dataset.save_as() or dcmwrite() , use write_dataset() instead.

A dataset’s file_meta elements are no longer modified when writing.

DicomIO now requires a readable or writeable buffer during initialisation and DicomBytesIO directly inherits from it.

The pydicom.encoders module has been moved to pydicom.pixels.encoders , the original import path will be removed in v4.0.

Using GDCM v3.0.23 or lower to decode JPEG-LS datasets with a Bits Stored of 6 or 7 produces incorrect results, so attempting to do so now raises an exception. pyjpegls or pylibjpeg with pylibjpeg-libjpeg can be used instead ( #2008 ).

Using Pillow with JPEG 2000 encoded > 8-bit multi-sample data (such as RGB) now raises an exception as Pillow cannot decode such data correctly ( #2006 ).

An exception will now be raised if an ndarray is used to set Pixel Data ( #50 ).

Logging of errors when converting elements using Dataset.to_json_dict() have been made more verbose and now use logging.WARNING ( #1909 ).

Added FileDataset.buffer and changed FileDataset.filename to only be the filename the dataset was read from (if any) ( #1937 ).

Removals

The compat module has been removed.

The dicomdir module and DicomDir class have been removed and reading a DICOMDIR dataset now returns a normal FileDataset instance. For handling DICOM File-sets and DICOMDIR datasets use the FileSet class instead.

The read_file and write_file functions have been removed, use dcmread() and dcmwrite() instead.

The following UID constants have been removed:

JPEGBaseline (use JPEGBaseline8Bit instead)

JPEGExtended (use JPEGExtended12Bit instead)

JPEGLSLossy (use JPEGLSNearLossless instead)

JPEG2000MultiComponentLossless (use JPEG2000MCLossless instead)

JPEG2000MultiComponent (use JPEG2000MC instead)

The following UID lists have been removed:

JPEGLossyCompressedPixelTransferSyntaxes : use JPEGTransferSyntaxes

JPEGLSSupportedCompressedPixelTransferSyntaxes : use JPEGLSTransferSyntaxes

JPEG2000CompressedPixelTransferSyntaxes : use JPEG2000TransferSyntaxes

RLECompressedLosslessSyntaxes : use RLETransferSyntaxes

UncompressedPixelTransferSyntaxes : use UncompressedTransferSyntaxes

PILSupportedCompressedPixelTransferSyntaxes

The PersonNameUnicode class has been removed, use PersonName instead.

The DataElement.description attribute has been removed, use DataElement.name instead.

The pixel_data_handlers.rle_handler.rle_encode_frame function has been removed, use Dataset.compress() or RLELosslessEncoder instead.

The _storage_sopclass_uids module has been removed, import UIDs from the uid module instead.

The following properties have been removed:

Dataset.parent and Dataset.parent_seq

Sequence.parent and Sequence.parent_dataset

DataElement.parent

The overlay_data_handlers module has been removed, use the overlays module instead.

config.overlay_data_handlers has been removed.

Dataset.fix_meta_info() has been removed as encoding state now follows the transfer syntax instead of the other way around.

Enhancements

Added details of missing required tag information when adding a dataset to a File-set ( #1752 ).

The following UID constants have been added:

MPEG2MPMLF

MPEG2MPHLF

MPEG4HP41F

MPEG4HP41BDF

MPEG4HP422DF

MPEG4HP423DF

MPEG4HP42STEREOF

HTJ2KLossless

HTJ2KLosslessRPCL

HTJ2K

JPIPHTJ2KReferenced

JPIPHTJ2KReferencedDeflate

SMPTEST211020UncompressedProgressiveActiveVideo

SMPTEST211020UncompressedInterlacedActiveVideo

SMPTEST211030PCMDigitalAudio

Added convenience method add_new_private() to add a private tag.

Added the examples module to make it easier and less confusing for users to work with the example datasets used by the documentation.

Added the ability to set the corresponding dataset encoding for private transfer syntaxes to UID via the set_private_encoding() method.

Added the ability to register private transfer syntaxes with register_transfer_syntax() so they can be used when reading datasets with dcmread() .

Warning messages are also sent to the pydicom logger ( #1529 ).

Added the following to the encaps module:

parse_basic_offsets() for parsing the Basic Offset Table.

parse_fragments() for determining the number of encapsulated fragments and their byte offsets.

generate_fragments() for yielding encapsulated fragments.

generate_fragmented_frames() for yielding encapsulated frame fragments.

generate_frames() for yielding whole encapsulated frames.

get_frame() for returning the specific encapsulated frame at index without necessarily having to read the preceding frames into memory.

These new functions support reading encapsulated data from both bytes or any Python object with read() , seek() and tell() methods such as io.BytesIO , BinaryIO or mmap.mmap . They also support using the Extended Offset Table for determining frame boundaries.

Added the keep_deferred keyword argument to Dataset.get_item() to allow accessing the file offset and element length without having to read the element value. ( #1873 ).

Added the pixels module and a new more flexible backend for decoding pixel data via Decoder factory class instances. The new decoding backend adds support for the following:

Returning a view over the original pixel data buffer ( #746 ).

Retrieving specific frames ( #1263 , #1243 ).

Returning RGB pixel data by default for JPEG ( #1781 , #1133 and many others).

Returning excess frames for JPEG when there is no Basic or Extended Offset Table and the Number of Frames is incorrect ( #1666 ).

Returning excess frames for native encoding when the Number of Frames is incorrect ( #2035 )

Returning the decoded pixel data as either a NumPy ndarray or buffer-like object .

Iterating through either all or specific frames.

Added support for decoding HTJ2K transfer syntaxes ( #1848 ).

Added two functions for returning pixel data as a NumPy ndarray from a path to a dataset while minimizing memory-usage: pixel_array() and iter_pixels() .

Added two functions for compressing and decompressing datasets using the new decoding backend: compress() and decompress() .

Added support for the following transfer syntaxes to Dataset.compress() ( #1997 ):

JPEG-LS Lossless with JPEGLSLosslessEncoder

JPEG-LS Near Lossless with JPEGLSNearLosslessEncoder

JPEG 2000 Lossless with JPEG2000LosslessEncoder

JPEG 2000 with JPEG2000Encoder

See the JPEG-LS and JPEG 2000 encoding guides for more information.

Added Dataset.pixel_array_options() for controlling pixel data decoding when using Dataset.pixel_array with the new pixels backend.

Improve support for reading and resolving inline binary data with VR=UN from Json ( #2062 ).

get_j2k_parameters() now takes into account the JP2 header (if present, although it’s non-conformant for it to be) ( #2073 ).

Added support for NumPy v2.0 ( #2075 ).

Added pydicom.concepts_version attribute with the DICOM Standard version used to create the concepts dictionaries in pydicom.sr ( #1021 ).

Refactored the interface for the concepts in pydicom.sr to simplify the access types ( #1454 ).

Added the Dataset.set_pixel_data() method and set_pixel_data() function for automatically setting a dataset’s Pixel Data and related Image Pixel module elements using an ndarray ( #50 ).

Added typing support for Dataset element access using the types-pydicom package. ( #1485 ).

Added apply_presentation_lut() for applying a Presentation LUT to an ndarray ( #1265 ).

Added apply_icc_profile() and create_icc_transform() for applying ICC profiles to an ndarray ( #1244 ).

Added Dataset.update_raw_element() to make it easier to modify a RawDataElement ’s VR or value prior to conversion to a DataElement ( #1739 ).

Added support for using io.BufferedIOBase subclasses to set the value for elements with O* VRs such as OB and OW ( #1913 ).

Added encapsulate_buffer() and encapsulate_extended_buffer() for encapsulating buffered compressed Pixel Data via EncapsulatedBuffer instances.

Added elements with OB , OD , OF , OL , OW , OV VRs to the type validation checking when setting DataElement values ( #1414 ).

Added convert_raw_data_element() for converting raw element data to DataElement instances.

Added the hooks module which contains an interface for adding callback functions via the Hooks singleton, as well as default and alternative convenience callbacks for convert_raw_data_element() ( #1556 ).

Fixes

Fixed the GDCM and pylibjpeg handlers changing the Pixel Representation value to 0 when the J2K stream disagrees with the dataset and APPLY_J2K_CORRECTIONS is True ( #1689 ).

Fixed pydicom codify error when relative path did not exist.

Fixed the VR enum sometimes returning invalid values for Python 3.11+ ( #1874 ).

Fixed pixel data handler for Pillow 10.1 raising an AttributeError ( #1907 ).

Fixed a possible security issue with FileInstance instances being able to escape the temporary directory when being added to a FileSet ( #1922 ).

Fixed an AttributeError when running deepcopy() after Dataset.update ( #1816 ).

Fixed encapsulate_extended() not returning the correct values for odd-length frames ( #1968 ).

Fixed using the incorrect encoding when writing datasets converted between explicit and implicit VR when only the Transfer Syntax UID was changed ( #1943 ).

Fixed the jpeg_ls , pillow and rle pixel data handlers not working correctly when a frame is spread across multiple fragments ( #1774 ).

Added mitigation for a rare case where clearing the pixel data value prior to updating it may sometimes result in pixel_array returning the previous array instead of creating a new one ( #1983 ).

Fixed a KeyError when comparing codes with one of the codes having scheme_designator set to SRT but not being included in the SRT to SCT code mapping ( #1994 ).

Fixed JPEG-LS datasets with a Pixel Representation of 1 returning incorrect image data when Bits Stored is less than Bits Allocated ( #2009 ).

Fixed decoding failures for JPEG-LS datasets with Bits Allocated of 16 and Bits Stored <= 8 ( #2010 ).

Fixed the Pixel Data VR not being set correctly with Dataset.compress() ( #2013 ).

Fixed Dataset.decompress() not updating the Pixel Data element value until after saving ( #2024 ).

Fixed a rare issue with converting pixel data to an ndarray when Bits Stored is less than Bits Allocated and the unused bits haven’t been set to an appropriate value for correct interpretation of the data.

Fixed a RecursionError when using copy.deepcopy() with a dataset containing a private block ( #2025 ).

Fixed non-unique keywords for the concept codes in pydicom.sr ( #1388 ).

Fixed keywords using Python identifiers in pydicom.sr ( #1273 ).

Fixed being unable to write LUT Descriptor when the VR is SS and the first value is greater than 32767 ( #2081 ).

Fixed Deflated Explicit VR Little Endian datasets not working correctly with codify ( #1937 ).

Deprecations

Dataset.is_little_endian and Dataset.is_implicit_VR will be removed in v4.0.

Dataset.read_little_endian and Dataset.read_implicit_vr will be removed in v4.0, use Dataset.original_encoding instead.

Dataset.read_encoding will be removed in v4.0, use Dataset.original_character_set instead.

The write_like_original optional argument to Dataset.save_as and dcmwrite() will be removed in v4.0, use enforce_file_format instead.

The following encaps module functions will be removed in v4.0:

get_frame_offsets() , use parse_basic_offsets() instead.

generate_pixel_data_fragment() , use generate_fragments() instead.

generate_pixel_data_frame() , use generate_fragmented_frames() instead.

generate_pixel_data() , use generate_frames() instead.

decode_data_sequence() , use generate_fragments() instead.

defragment_data() , use generate_frames() instead.

read_item() , use generate_fragments() instead.

The pydicom.pixel_data_handlers module will be removed in v4.0. All pixel data processing will use the pydicom.pixels module instead starting with v3.0.

The following functions from pydicom.pixel_data_handlers.util have been moved to pydicom.pixels.processing :

apply_color_lut()

apply_modality_lut()

apply_rescale()

apply_voi_lut()

apply_voi()

apply_windowing()

convert_color_space()

The following functions from pydicom.pixel_data_handlers.util have been moved to pydicom.pixels.utils :

expand_ybr422()

get_expected_length()

get_image_pixel_ids()

get_j2k_parameters()

get_nr_frames()

pack_bits()

pixel_dtype()

reshape_pixel_array()

unpack_bits()

pydicom.pixel_data_handlers.util.dtype_corrected_for_endianness() will be removed in v4.0.

Dataset.convert_pixel_data() will be removed in v4.0, use Dataset.pixel_array_options() instead.

DataElement_from_raw() will be removed in v4.0, please use convert_raw_data_element() instead.

config.data_element_callback and config.data_element_callback_kwargs will be removed in v4.0, please use the hooks for convert_raw_data_element() instead.

The pydicom.utils.fixers submodule will be removed in v4.0, please use the alternative callbacks for convert_raw_data_element() in the hooks module instead.

Pydicom Internals

Repository folder structure refactored.

Renamed top level source folder to util .

New CI tools - dependabot , and pre-commit using black and ruff.

The major breaking changes with the version 3.0 release are:

• The value for ~pydicom.uid.JPEGLossless has changed to 1.2.840.10008.1.2.4.57.

• The encoding used when saving datasets defaults to the set Transfer Syntax UID.

• Dataset.pixel_array will convert YCbCr Pixel Data to RGB by default when possible.

• read_file and write_file have been removed.

Changes

• Removed support for Python <= 3.9.

• All tag formats changed to upper case, no space e.g. "(7FE0,0010)" rather than "(7fe0, 0010)".

• Values with VR AE with an incorrect value length are now handled gracefully (extra bytes are ignored with a warning).

• A value of 0 for Number of Frames is now handled as 1 frame, with a user warning issued on reading the pixel data (1844).

• The value for ~pydicom.uid.JPEGLossless has changed from 1.2.840.10008.1.2.4.70 to 1.2.840.10008.1.2.4.57 to match its UID keyword. Use ~pydicom.uid.JPEGLosslessSV1 instead for 1.2.840.10008.1.2.4.70.

• The theoretical maximum number of instances supported by ~pydicom.fileset.FileSet has been reduced to 1838265625 to ensure support for 32-bit systems (1743).

• The characters used by ~pydicom.fileset.generate_filename when alphanumeric is True has been reduced to [0-9][A-I,K-Z].

• ~pydicom.data.get_testdata_file and ~pydicom.data.get_testdata_files now raise ValueError if called with an absolute path or pattern.

• ~pydicom.uid.generate_uid has been changed to use a random suffix generated using ~secrets.randbelow when entropy_srcs isn't used, and the maximum allowed length of the prefix has been changed to 54 characters (1773).

• DataElement.VM always returns 1 for SQ elements (1481).

• DICOM dictionary updated to 2024c.

• Concepts dictionaries updated to 2024c.

• ~pydicom.dataset.validate_file_meta now checks to ensure required Type 1 elements aren't empty.

• implicit_vr and little_endian optional arguments added to Dataset.save_as(). In addition, this method will now raise an exception if the user tries to convert between little and big endian datasets. If this is something you need, use ~pydicom.filewriter.dcmwrite instead.

• Added the overwrite argument to Dataset.save_as() and ~pydicom.filewriter.dcmwrite to allow raising a FileExistsError if trying to write to a file that already exists (2104).

• implicit_vr, little_endian and force_encoding optional arguments added to ~pydicom.filewriter.dcmwrite.

• The priority used to decide which encoding to use with Dataset.save_as() and ~pydicom.filewriter.dcmwrite has been changed to:

  1. The set Transfer Syntax UID,

  2. The implicit_vr and little_endian arguments,

  3. Dataset.is_implicit_VR and Dataset.is_little_endian,

  4. Dataset.original_encoding.

• Datasets containing Command Set (0000,eeee) elements can no longer be written using Dataset.save_as() or ~pydicom.filewriter.dcmwrite, use ~pydicom.filewriter.write_dataset instead.

• A dataset's ~pydicom.dataset.FileDataset.file_meta elements are no longer modified when writing.

• ~pydicom.filebase.DicomIO now requires a readable or writeable buffer during initialisation and ~pydicom.filebase.DicomBytesIO directly inherits from it.

• The pydicom.encoders module has been moved to pydicom.pixels.encoders, the original import path will be removed in v4.0.

• Using GDCM v3.0.23 or lower to decode JPEG-LS datasets with a Bits Stored of 6 or 7 produces incorrect results, so attempting to do so now raises an exception. pyjpegls or pylibjpeg with pylibjpeg-libjpeg can be used instead (2008).

• Using Pillow with JPEG 2000 encoded > 8-bit multi-sample data (such as RGB) now raises an exception as Pillow cannot decode such data correctly (2006).

• An exception will now be raised if an ~numpy.ndarray is used to set Pixel Data (50).

• Logging of errors when converting elements using Dataset.to_json_dict() have been made more verbose and now use logging.WARNING (1909).

• Added FileDataset.buffer and changed FileDataset.filename to only be the filename the dataset was read from (if any) (1937).

Removals

• The compat module has been removed.

• The dicomdir module and DicomDir class have been removed and reading a DICOMDIR dataset now returns a normal ~pydicom.dataset.FileDataset instance. For handling DICOM File-sets and DICOMDIR datasets use the ~pydicom.fileset.FileSet class instead.

• The read_file and write_file functions have been removed, use ~pydicom.filereader.dcmread and ~pydicom.filewriter.dcmwrite instead.

• The following UID constants have been removed:

  • JPEGBaseline (use ~pydicom.uid.JPEGBaseline8Bit instead)

  • JPEGExtended (use ~pydicom.uid.JPEGExtended12Bit instead)

  • JPEGLSLossy (use ~pydicom.uid.JPEGLSNearLossless instead)

  • JPEG2000MultiComponentLossless (use ~pydicom.uid.JPEG2000MCLossless instead)

  • JPEG2000MultiComponent (use ~pydicom.uid.JPEG2000MC instead)

• The following UID lists have been removed:

  • JPEGLossyCompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEGTransferSyntaxes

  • JPEGLSSupportedCompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEGLSTransferSyntaxes

  • JPEG2000CompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEG2000TransferSyntaxes

  • RLECompressedLosslessSyntaxes: use ~pydicom.uid.RLETransferSyntaxes

  • UncompressedPixelTransferSyntaxes: use ~pydicom.uid.UncompressedTransferSyntaxes

  • PILSupportedCompressedPixelTransferSyntaxes

• The PersonNameUnicode class has been removed, use ~pydicom.valuerep.PersonName instead.

• The DataElement.description attribute has been removed, use DataElement.name instead.

• The pixel_data_handlers.rle_handler.rle_encode_frame function has been removed, use Dataset.compress() or ~pydicom.pixels.encoders.base.RLELosslessEncoder instead.

• The _storage_sopclass_uids module has been removed, import UIDs from the ~pydicom.uid module instead.

• The following properties have been removed:

  • Dataset.parent and Dataset.parent_seq

  • Sequence.parent and Sequence.parent_dataset

  • DataElement.parent

• The overlay_data_handlers module has been removed, use the ~pydicom.overlays module instead.

• config.overlay_data_handlers has been removed.

• Dataset.fix_meta_info() has been removed as encoding state now follows the transfer syntax instead of the other way around.

Enhancements

• Added details of missing required tag information when adding a dataset to a File-set (1752).

• The following UID constants have been added:

  • ~pydicom.uid.MPEG2MPMLF

  • ~pydicom.uid.MPEG2MPHLF

  • ~pydicom.uid.MPEG4HP41F

  • ~pydicom.uid.MPEG4HP41BDF

  • ~pydicom.uid.MPEG4HP422DF

  • ~pydicom.uid.MPEG4HP423DF

  • ~pydicom.uid.MPEG4HP42STEREOF

  • ~pydicom.uid.HTJ2KLossless

  • ~pydicom.uid.HTJ2KLosslessRPCL

  • ~pydicom.uid.HTJ2K

  • ~pydicom.uid.JPIPHTJ2KReferenced

  • ~pydicom.uid.JPIPHTJ2KReferencedDeflate

  • ~pydicom.uid.SMPTEST211020UncompressedProgressiveActiveVideo

  • ~pydicom.uid.SMPTEST211020UncompressedInterlacedActiveVideo

  • ~pydicom.uid.SMPTEST211030PCMDigitalAudio

• Added convenience method ~pydicom.dataset.Dataset.add_new_private to add a private tag.

• Added the examples module to make it easier and less confusing for users to work with the example datasets used by the documentation.

• Added the ability to set the corresponding dataset encoding for private transfer syntaxes to ~pydicom.uid.UID via the ~pydicom.uid.UID.set_private_encoding method.

• Added the ability to register private transfer syntaxes with ~pydicom.uid.register_transfer_syntax so they can be used when reading datasets with ~pydicom.filereader.dcmread.

• Warning messages are also sent to the pydicom logger (1529).

• Added the following to the ~pydicom.encaps module:

  • ~pydicom.encaps.parse_basic_offsets for parsing the Basic Offset Table.

  • ~pydicom.encaps.parse_fragments for determining the number of encapsulated fragments and their byte offsets.

  • ~pydicom.encaps.generate_fragments for yielding encapsulated fragments.

  • ~pydicom.encaps.generate_fragmented_frames for yielding encapsulated frame fragments.

  • ~pydicom.encaps.generate_frames for yielding whole encapsulated frames.

  • ~pydicom.encaps.get_frame for returning the specific encapsulated frame at index without necessarily having to read the preceding frames into memory.

  These new functions support reading encapsulated data from both bytes or any Python object with read(), seek() and tell() methods such as io.BytesIO, BinaryIO or mmap.mmap. They also support using the Extended Offset Table for determining frame boundaries.

• Added the keep_deferred keyword argument to Dataset.get_item() to allow accessing the file offset and element length without having to read the element value. (1873).

• Added the ~pydicom.pixels module and a new more flexible backend for decoding pixel data via ~pydicom.pixels.decoders.base.Decoder factory class instances. The new decoding backend adds support for the following:

  • Returning a view over the original pixel data buffer (746).

  • Retrieving specific frames (1263, 1243).

  • Returning RGB pixel data by default for JPEG (1781, 1133 and many others).

  • Returning excess frames for JPEG when there is no Basic or Extended Offset Table and the Number of Frames is incorrect (1666).

  • Returning excess frames for native encoding when the Number of Frames is incorrect (2035)

  • Returning the decoded pixel data as either a NumPy ~numpy.ndarray or buffer-like object.

  • Iterating through either all or specific frames.

• Added support for decoding HTJ2K transfer syntaxes (1848).

• Added two functions for returning pixel data as a NumPy ~numpy.ndarray from a path to a dataset while minimizing memory-usage: ~pydicom.pixels.pixel_array and ~pydicom.pixels.iter_pixels.

• Added two functions for compressing and decompressing datasets using the new decoding backend: ~pydicom.pixels.compress and ~pydicom.pixels.decompress.

• Added support for the following transfer syntaxes to Dataset.compress() (1997):

  • JPEG-LS Lossless with ~pydicom.pixels.encoders.JPEGLSLosslessEncoder

  • JPEG-LS Near Lossless with ~pydicom.pixels.encoders.JPEGLSNearLosslessEncoder

  • JPEG 2000 Lossless with ~pydicom.pixels.encoders.JPEG2000LosslessEncoder

  • JPEG 2000 with ~pydicom.pixels.encoders.JPEG2000Encoder

  See the JPEG-LS and JPEG 2000 encoding guides for more information.

• Added Dataset.pixel_array_options() for controlling pixel data decoding when using Dataset.pixel_array with the new ~pydicom.pixels backend.

• Improve support for reading and resolving inline binary data with VR=UN from Json (2062).

• ~pydicom.pixels.utils.get_j2k_parameters now takes into account the JP2 header (if present, although it's non-conformant for it to be) (2073).

• Added support for NumPy v2.0 (2075).

• Added pydicom.__concepts_version__ attribute with the DICOM Standard version used to create the concepts dictionaries in pydicom.sr (1021).

• Refactored the interface for the concepts in pydicom.sr to simplify the access types (1454).

• Added the Dataset.set_pixel_data() method and ~pydicom.pixels.set_pixel_data function for automatically setting a dataset's Pixel Data and related Image Pixel module elements using an ~numpy.ndarray (50).

• Added typing support for ~pydicom.dataset.Dataset element access using the types-pydicom package. (1485).

• Added ~pydicom.pixels.apply_presentation_lut for applying a Presentation LUT to an ~numpy.ndarray (1265).

• Added ~pydicom.pixels.apply_icc_profile and ~pydicom.pixels.create_icc_transform for applying ICC profiles to an ~numpy.ndarray (1244).

• Added Dataset.update_raw_element() to make it easier to modify a ~pydicom.dataelem.RawDataElement's VR or value prior to conversion to a ~pydicom.dataelem.DataElement (1739).

• Added support for using io.BufferedIOBase subclasses to set the value for elements with O* VRs such as OB and OW (1913).

• Added ~pydicom.encaps.encapsulate_buffer and ~pydicom.encaps.encapsulate_extended_buffer for encapsulating buffered compressed Pixel Data via ~pydicom.encaps.EncapsulatedBuffer instances.

• Added elements with OB, OD, OF, OL, OW, OV VRs to the type validation checking when setting ~pydicom.dataelem.DataElement values (1414).

• Added ~pydicom.dataelem.convert_raw_data_element for converting raw element data to ~pydicom.dataelem.DataElement instances.

• Added the ~pydicom.hooks module which contains an interface for adding callback functions via the ~pydicom.hooks.Hooks singleton, as well as default and alternative convenience callbacks for ~pydicom.dataelem.convert_raw_data_element (1556).

Fixes

• Fixed the GDCM and pylibjpeg handlers changing the Pixel Representation value to 0 when the J2K stream disagrees with the dataset and ~pydicom.config.APPLY_J2K_CORRECTIONS is True (1689).

• Fixed pydicom codify error when relative path did not exist.

• Fixed the VR enum sometimes returning invalid values for Python 3.11+ (1874).

• Fixed pixel data handler for Pillow 10.1 raising an AttributeError (1907).

• Fixed a possible security issue with ~pydicom.fileset.FileInstance instances being able to escape the temporary directory when being added to a ~pydicom.fileset.FileSet (1922).

• Fixed an AttributeError when running ~copy.deepcopy after Dataset.update (1816).

• Fixed ~pydicom.encaps.encapsulate_extended not returning the correct values for odd-length frames (1968).

• Fixed using the incorrect encoding when writing datasets converted between explicit and implicit VR when only the Transfer Syntax UID was changed (1943).

• Fixed the jpeg_ls, pillow and rle pixel data handlers not working correctly when a frame is spread across multiple fragments (1774).

• Added mitigation for a rare case where clearing the pixel data value prior to updating it may sometimes result in ~pydicom.dataset.Dataset.pixel_array returning the previous array instead of creating a new one (1983).

• Fixed a KeyError when comparing codes with one of the codes having scheme_designator set to SRT but not being included in the SRT to SCT code mapping (1994).

• Fixed JPEG-LS datasets with a Pixel Representation of 1 returning incorrect image data when Bits Stored is less than Bits Allocated (2009).

• Fixed decoding failures for JPEG-LS datasets with Bits Allocated of 16 and Bits Stored <= 8 (2010).

• Fixed the Pixel Data VR not being set correctly with Dataset.compress() (2013).

• Fixed Dataset.decompress() not updating the Pixel Data element value until after saving (2024).

• Fixed a rare issue with converting pixel data to an ~numpy.ndarray when Bits Stored is less than Bits Allocated and the unused bits haven't been set to an appropriate value for correct interpretation of the data.

• Fixed a RecursionError when using copy.deepcopy with a dataset containing a private block (2025).

• Fixed non-unique keywords for the concept codes in pydicom.sr (1388).

• Fixed keywords using Python identifiers in pydicom.sr (1273).

• Fixed being unable to write LUT Descriptor when the VR is SS and the first value is greater than 32767 (2081).

• Fixed Deflated Explicit VR Little Endian datasets not working correctly with codify (1937).

Deprecations

• Dataset.is_little_endian and Dataset.is_implicit_VR will be removed in v4.0.

• Dataset.read_little_endian and Dataset.read_implicit_vr will be removed in v4.0, use Dataset.original_encoding instead.

• Dataset.read_encoding will be removed in v4.0, use Dataset.original_character_set instead.

• The write_like_original optional argument to Dataset.save_as and ~pydicom.filewriter.dcmwrite will be removed in v4.0, use enforce_file_format instead.

• The following ~pydicom.encaps module functions will be removed in v4.0:

  • ~pydicom.encaps.get_frame_offsets, use ~pydicom.encaps.parse_basic_offsets instead.

  • ~pydicom.encaps.generate_pixel_data_fragment, use ~pydicom.encaps.generate_fragments instead.

  • ~pydicom.encaps.generate_pixel_data_frame, use ~pydicom.encaps.generate_fragmented_frames instead.

  • ~pydicom.encaps.generate_pixel_data, use ~pydicom.encaps.generate_frames instead.

  • ~pydicom.encaps.decode_data_sequence, use ~pydicom.encaps.generate_fragments instead.

  • ~pydicom.encaps.defragment_data, use ~pydicom.encaps.generate_frames instead.

  • ~pydicom.encaps.read_item, use ~pydicom.encaps.generate_fragments instead.

• The pydicom.pixel_data_handlers module will be removed in v4.0. All pixel data processing will use the pydicom.pixels module instead starting with v3.0.

  • The following functions from pydicom.pixel_data_handlers.util have been moved to pydicom.pixels.processing:

    • ~pydicom.pixels.processing.apply_color_lut

    • ~pydicom.pixels.processing.apply_modality_lut

    • ~pydicom.pixels.processing.apply_rescale

    • ~pydicom.pixels.processing.apply_voi_lut

    • ~pydicom.pixels.processing.apply_voi

    • ~pydicom.pixels.processing.apply_windowing

    • ~pydicom.pixels.processing.convert_color_space

  • The following functions from pydicom.pixel_data_handlers.util have been moved to pydicom.pixels.utils:

    • ~pydicom.pixels.utils.expand_ybr422

    • ~pydicom.pixels.utils.get_expected_length

    • ~pydicom.pixels.utils.get_image_pixel_ids

    • ~pydicom.pixels.utils.get_j2k_parameters

    • ~pydicom.pixels.utils.get_nr_frames

    • ~pydicom.pixels.utils.pack_bits

    • ~pydicom.pixels.utils.pixel_dtype

    • ~pydicom.pixels.utils.reshape_pixel_array

    • ~pydicom.pixels.utils.unpack_bits

  • pydicom.pixel_data_handlers.util.dtype_corrected_for_endianness will be removed in v4.0.

• Dataset.convert_pixel_data() will be removed in v4.0, use Dataset.pixel_array_options() instead.

• ~pydicom.dataelem.DataElement_from_raw will be removed in v4.0, please use ~pydicom.dataelem.convert_raw_data_element instead.

• config.data_element_callback and config.data_element_callback_kwargs will be removed in v4.0, please use the hooks for ~pydicom.dataelem.convert_raw_data_element instead.

• The pydicom.utils.fixers submodule will be removed in v4.0, please use the alternative callbacks for ~pydicom.dataelem.convert_raw_data_element in the ~pydicom.hooks module instead.

Pydicom Internals

• Repository folder structure refactored.

• Renamed top level source folder to util.

• New CI tools - dependabot, and pre-commit using black and ruff.

2.4.5

Fixes

• Backport of security fix for DICOMIR path traversal vulnerability (CVE-2026-32711)

2.4.4

Fixes

• Fixed broken documentation search (1969)

2.4.3

Fixes

• Fixed pydicom codify error when relative path did not exist (1867)

2.4.2

Fixes

• Handle ~pydicom.sequence.Sequence having None for parent ~pydicom.dataset.Dataset (1842)

• Fix deepcopy of Dataset and Sequence (#1814)

2.4.1

Fixes

• Fixed deepcopy of ~pydicom.dataset.Dataset and ~pydicom.sequence.Sequence (1814)

Various bug fixes and enhancements. See details below, or the release notes for a less detailed changelog.

Note: the tests folder is no longer included in the packaged builds installed using pip, etc.

What's Changed

• Do not use pytest.warns(None) by @mrbean-bremen in #1623
• Add alphabetic property to PersonName VR by @bernardopericacho in #1634
• Use a next-gen Docker convenience CircleCI image by @bernardopericacho in #1635
• Use sensible chunk size for test data download by @mrbean-bremen in #1636
• Fix length validation of DS values by @mrbean-bremen in #1633
• Prevent crash due to invalid private creator by @mrbean-bremen in #1639
• Add validation for numerical VR values by @mrbean-bremen in #1640
• json_key method for BaseTag by @sanjaymjoshi in #1648
• Fix source comment typo by @luzpaz in #1663
• Avoid multi-megabyte error message by @chris-remedy in #1683
• Codify Ensures distinct names by @darcymason in #1674
• Catch error in creating a dataelement in to_json_dict by @mrbean-bremen in #1694
• Fix reading of 1 byte Big Endian data with OW by @mrbean-bremen in #1687
• Add CI builds for Python 3.11 by @mrbean-bremen in #1659
• Handle invalid DICOMDIR dataset by @mrbean-bremen in #1707
• Skip jpeg-ls tests for Python 3.11 by @mrbean-bremen in #1708
• Add more information about pydicom purpose by @mrbean-bremen in #1709
• Add lint-action workflow by @mrbean-bremen in #1711
• IS float by @darcymason in #1720
• Pytest deprecations by @darcymason in #1730
• Correct waveform calculation. Closes #1667 by @MartinFLH in #1715
• Nested seq speed by @darcymason in #1734
• cut LUTData to expected size by @rgsoda in #1747
• Fix decoding of multibyte text with backslash by @ykszk in #1724
• Removed inactive gitter badge by @ZviBaratz in #1756
• [DOC] Minor fixes and suggestions by @ZviBaratz in #1761
• [DOC] File-set tutorial styling suggestions by @ZviBaratz in #1764
• Ensure AT DataElements are encoded properly by code_dataelem by @suever in #1768
• GitHub Actions: Upgrade to Python v3.11 production release by @cclauss in #1777
• GitHub Action to lint Python code with ruff by @cclauss in #1771
• small bugfix in example pydicomtree.py by @Grarie in #1787
• Exclude CharPyLS for Python 3.11 by @mrbean-bremen in #1791
• Switch build to pyproject.toml by @darcymason in #1792
• Use CharPyLS fork with newer cython version by @mrbean-bremen in #1794
• Use wheel packages to install pyjpegls by @mrbean-bremen in #1797
• Update DICOM and UID dicts to Dicom2023b by @darcymason in #1803

New Contributors

• @bernardopericacho made their first contribution in #1634
• @sanjaymjoshi made their first contribution in #1648
• @luzpaz made their first contribution in #1663
• @chris-remedy made their first contribution in #1683
• @MartinFLH made their first contribution in #1715
• @rgsoda made their first contribution in #1747
• @ykszk made their first contribution in #1724
• @ZviBaratz made their first contribution in #1756
• @suever made their first contribution in #1768
• @cclauss made their first contribution in #1777
• @Grarie made their first contribution in #1787

Full Changelog: v2.3.0...v2.4.0

Changes

Removed support for Python 3.6 (EOL since December 2021)

Enhancements

Added attribute alphabetic ( #1634 )

Added attribute json_key ( #1648 )

Added value validation for numerical VRs, add type validation for all validated VRs ( #1414 )

CLI commands now accept pydicom charset test files and CLI help shows Python Version ( #1674 )

Added support for Python 3.11 ( #1658 )

Added ISfloat to allow non-strict reading of existing files with float IS values ( #1661 )

Improved speed of creating and accessing highly nested structures ( #1728 , #1734 )

Switched to a pyproject.toml build process ( #1792 )

Updated DICOM and UID dicts to DICOM 2023b ( #1803 )

Fixes

Fixed length validation of DS values with maximum length without a leading zero ( #1632 )

Increased download speed with progress bar for test data ( #1611 )

Fixed crash due to invalid private creator ( #1638 )

Fixed extremely long BytesLengthException error messages ( #1683 )

In codify, ensure unique variable names for DICOM keywords repeated in sequences, and handle unicode characters correctly ( #1670 )

Fixed handling of some invalid values in to_json_dict() if suppress_invalid_tags is set to True ( #1693 )

Fixed reading of data with 8 bits allocated, encoded in Big Endian transfer syntax using VR OW ( #1680 )

Fixed crash if reading regular dataset that has the SOP Class of a DICOMDIR ( #1702 )

Fixed wrong waveform data calculation when as_raw=False and baseline!=0 ( #1667 )

Fixed reading LUTData to expected size ( #1747 )

Fixed handling of AT VRs when codifying data elements ( #1738 )

Pydicom Internals

In test suites, renamed ‘setup’ and ‘teardown’ methods, deprecated starting in pytest 7.2

Use own fork of CharPyLS to handle builds with Python 3.11 ( #1788 )

Changes

DataElement.description is deprecated and will be removed in v3.0, use DataElement.name instead

Updated the private dictionary

enforce_valid_values is deprecated in favor of reading_validation_mode

Added download parameter to get_testdata_file() to allow skipping downloading the file if missed locally ( #1617 )

Enhancements

Values are now validated for valid length, allowed character set and format on reading and writing. Depending on the value of reading_validation_mode and writing_validation_mode a warning is logged, an exception is raised, or the validation is skipped.

Added VR enum ( #1500 )

UIDs for all Storage SOP Classes have been added to the uid module ( #1498 )

Use rle_handler as last resort handler for decoding RLE encoded data as it is the slowest handler ( #1487 )

Added, enhanced, or removed a number of Mitra private dictionary entries ( #1588 )

Added support for unpacking bit-packed data without using NumPy to unpack_bits(:pr:1594() )

Added expand_ybr422() for expanding uncompressed YBR_FULL_422 data to YBR_FULL ( #1593 )

Replacement of UN VR with SQ VR for undefined length data elements (introduced in 2.2.2), can now be configured via infer_sq_for_un_vr

Updated dictionaries to DICOM 2022a

Fixes

Fixed odd-length OB values not being padded during write ( #1511 )

Fixed Hologic private dictionary entry (0019xx43)

Fixed Mitra global patient ID private dictionary entry ( #1588 )

Fixed compress() not setting the correct encoding for the rest of the dataset ( #1565 )

Fixed AttributeError on deep copy of FileDataset ( #1571 )

Fixed an exception during pixel decoding if using GDCM < 2.8.8 on Windows ( #1581 )

Fixed crashes on Windows and MacOS when using the GDCM plugin to compress into RLE Lossless ( #1581 )

Fixed dir(Dataset()) not returning class attributes ( #1599 )

Fixed bad DICOMDIR offsets when using FileSet.write() with a Directory Record Sequence using undefined length items ( #1596 )

Assigning a list of length one as tag value is now correctly handled as assigning the single value ( #1606 )

Fixed an exception with multiple deferred reads with file-like objects ( #1609 )

2.3.0

Changes

• DataElement.description is deprecated and will be removed in v3.0, use DataElement.name instead

• Updated the private dictionary

• ~pydicom.config.enforce_valid_values is deprecated in favor of ~pydicom.config.settings.reading_validation_mode

• Added download parameter to ~pydicom.data.get_testdata_file to allow skipping downloading the file if missed locally (1617)

Enhancements

• Values are now validated for valid length, allowed character set and format on reading and writing. Depending on the value of ~pydicom.config.settings.reading_validation_mode and ~pydicom.config.settings.writing_validation_mode a warning is logged, an exception is raised, or the validation is skipped.

• Added ~pydicom.valuerep.VR enum (1500)

• UIDs for all Storage SOP Classes have been added to the uid module (1498)

• Use rle_handler as last resort handler for decoding RLE encoded data as it is the slowest handler (1487)

• Added, enhanced, or removed a number of Mitra private dictionary entries (1588)

• Added support for unpacking bit-packed data without using NumPy to ~pydicom.pixel_data_handlers.utils.unpack_bits(1594)

• Added ~pydicom.pixel_data_handlers.util.expand_ybr422 for expanding uncompressed YBR_FULL_422 data to YBR_FULL (1593)

• Replacement of UN VR with SQ VR for undefined length data elements (introduced in 2.2.2), can now be configured via ~pydicom.config.settings.infer_sq_for_un_vr

• Updated dictionaries to DICOM 2022a

Fixes

• Fixed odd-length OB values not being padded during write (1511)

• Fixed Hologic private dictionary entry (0019xx43)

• Fixed Mitra global patient ID private dictionary entry (1588)

• Fixed ~pydicom.dataset.Dataset.compress not setting the correct encoding for the rest of the dataset (1565)

• Fixed AttributeError on deep copy of ~pydicom.dataset.FileDataset (1571)

• Fixed an exception during pixel decoding if using GDCM < 2.8.8 on Windows (1581)

• Fixed crashes on Windows and MacOS when using the GDCM plugin to compress into RLE Lossless (1581)

• Fixed dir(Dataset()) not returning class attributes (1599)

• Fixed bad DICOMDIR offsets when using FileSet.write() with a Directory Record Sequence using undefined length items (1596)

• Assigning a list of length one as tag value is now correctly handled as assigning the single value (1606)

• Fixed an exception with multiple deferred reads with file-like objects (1609)

Changes

Data elements with a VR of AT must now be set with values acceptable to Tag() , and are always stored as a BaseTag . Previously, any Python type could be set.

BaseTag.eq() returns False rather than raising an exception when the operand cannot be converted to BaseTag ( #1327 )

DA.str() , DT.str() and TM.str() return valid DICOM strings instead of the formatted date and time representations ( #1262 )

If comparing FileDataset instances, the file metadata is now ignored. This makes it possible to compare a FileDataset object with a Dataset object.

rle_encode_frame() is deprecated and will be removed in v3.0, use compress() or RLELosslessEncoder instead.

read_file() is deprecated and will be removed in v3.0, use dcmread() instead.

write_file() is deprecated and will be removed in v3.0, use dcmwrite() instead.

Data dictionaries updated to version 2021b of the DICOM Standard

Dataset no longer inherits from dict

Enhancements

Added a command-line interface for pydicom. Current subcommands are:

show : display all or part of a DICOM file

codify to produce Python code for writing files or sequence items from scratch.

Please see the Command-line Interface Guide for examples and details of all the options for each command.

A field containing an invalid number of bytes will result in a warning instead of an exception when convert_wrong_length_to_UN is set to True .

Private tags known via the private dictionary will now get the configured VR if read from a dataset instead of UN ( #1051 ).

While reading explicit VR, a switch to implicit VR will be silently attempted if the VR bytes are not valid VR characters, and config option assume_implicit_vr_switch is True (default)

New functionality to help with correct formatting of decimal strings ( DS )

Added is_valid_ds() to check whether a string is valid as a DICOM decimal string and format_number_as_ds() to format a given float or Decimal as a DS while retaining the highest possible level of precision

If enforce_valid_values is set to True , all DS objects created will be checked for the validity of their string representations.

Added optional auto_format parameter to the init methods of DSfloat and DSdecimal and the DS() factory function to allow explicitly requesting automatic formatting of the string representations of these objects when they are constructed.

Added methods to construct PersonName objects from individual components of names ( family_name , given_name , etc.). See from_named_components() and from_named_components_veterinary() .

Added support for downloading the large test files with the requests package in addition to urllib.request ( #1340 )

Ensured convert_color_space() uses 32-bit floats for calculation, added per_frame flag to allow frame-by-frame processing and improved the speed by ~20-60% ( #1348 )

Optimisations for RLE encoding using pydicom (~40% faster).

Added support for faster decoding (~4-5x) and encoding (~20x) of RLE Lossless Pixel Data via the pylibjpeg-rle plugin ( #1361 , #1372 ).

Added Dataset.compress() function for compressing uncompressed pixel data using a given encoding format as specified by a UID. Only RLE Lossless is currently supported ( #1372 )

Added encoders module and the following encoders:

RLELosslessEncoder with ‘pydicom’, ‘pylibjpeg’ and ‘gdcm’ plugins

Added read parameter to get_testdata_file() to allow reading and returning the corresponding dataset ( #1372 )

Handle decoded RLE segments with padding ( #1438 )

Add option to JSON functions to suppress exception and continue ( #1332 )

Allow searching FileSet s for a list of elements ( #1428 )

Added hash function to SR Code ( #1434 )

Fixes

Fixed pickling a Dataset instance with sequences after the sequence had been read ( #1278 )

Fixed JSON export of numeric values

Fixed handling of sequences of unknown length that switch to implicit encoding, and sequences with VR UN ( #1312 )

Do not load external data sources until needed - fixes problems with standard workflow if setuptools are not installed ( #1341 )

Fixed empty PN elements read from file being str rather than PersonName ( #1338 )

Fixed handling of JPEG (10918-1) images compressed using RGB colourspace rather than YBR with the Pillow pixel data handler ( #878 )

Allow to deepcopy a ~pydicom.dataset.FileDataset object ( #1147 )

Fixed elements with a VR of OL , OD and OV not being set correctly when an encoded backslash was part of the element value ( #1412 )

Fixed expansion of linear segments with floating point steps in segmented LUTs ( #1415 )

Fixed handling of code extensions with person name component delimiter ( #1449 )

Fixed bug decoding RBG jpg with APP14 marker due to change in Pillow ( #1444 )

Fixed decoding for FloatPixelData and DoubleFloatPixelData via pydicom.pixel_data_handlers.numpy_handler ( #1457 )

2.2.0

Changes

• Data elements with a VR of AT must now be set with values acceptable to ~pydicom.tag.Tag, and are always stored as a ~pydicom.tag.BaseTag. Previously, any Python type could be set.

• BaseTag.__eq__() returns False rather than raising an exception when the operand cannot be converted to ~pydicom.tag.BaseTag (1327)

• DA.__str__(), DT.__str__() and TM.__str__() return valid DICOM strings instead of the formatted date and time representations (1262)

• If comparing ~pydicom.dataset.FileDataset instances, the file metadata is now ignored. This makes it possible to compare a ~pydicom.dataset.FileDataset object with a ~pydicom.dataset.Dataset object.

• ~pydicom.pixel_data_handlers.rle_handler.rle_encode_frame is deprecated and will be removed in v3.0, use ~pydicom.dataset.Dataset.compress or ~pydicom.encoders.RLELosslessEncoder instead.

• ~pydicom.filereader.read_file is deprecated and will be removed in v3.0, use ~pydicom.filereader.dcmread instead.

• ~pydicom.filewriter.write_file is deprecated and will be removed in v3.0, use ~pydicom.filewriter.dcmwrite instead.

• Data dictionaries updated to version 2021b of the DICOM Standard

• ~pydicom.dataset.Dataset no longer inherits from dict

Enhancements

• Added a command-line interface for pydicom. Current subcommands are:

  • show: display all or part of a DICOM file

  • codify to produce Python code for writing files or sequence items from scratch.

  Please see the cli_guide for examples and details of all the options for each command.

• A field containing an invalid number of bytes will result in a warning instead of an exception when ~pydicom.config.convert_wrong_length_to_UN is set to True.

• Private tags known via the private dictionary will now get the configured VR if read from a dataset instead of UN (1051).

• While reading explicit VR, a switch to implicit VR will be silently attempted if the VR bytes are not valid VR characters, and config option ~pydicom.config.assume_implicit_vr_switch is True (default)

• New functionality to help with correct formatting of decimal strings (DS)

  • Added ~pydicom.valuerep.is_valid_ds to check whether a string is valid as a DICOM decimal string and ~pydicom.valuerep.format_number_as_ds to format a given float or Decimal as a DS while retaining the highest possible level of precision

  • If ~pydicom.config.enforce_valid_values is set to True, all DS objects created will be checked for the validity of their string representations.

  • Added optional auto_format parameter to the init methods of ~pydicom.valuerep.DSfloat and ~pydicom.valuerep.DSdecimal and the ~pydicom.valuerep.DS factory function to allow explicitly requesting automatic formatting of the string representations of these objects when they are constructed.

• Added methods to construct ~pydicom.valuerep.PersonName objects from individual components of names (family_name, given_name, etc.). See ~pydicom.valuerep.PersonName.from_named_components and ~pydicom.valuerep.PersonName.from_named_components_veterinary.

• Added support for downloading the large test files with the requests package in addition to urllib.request (1340)

• Ensured ~pydicom.pixel_data_handlers.util.convert_color_space uses 32-bit floats for calculation, added per_frame flag to allow frame-by-frame processing and improved the speed by ~20-60% (1348)

• Optimisations for RLE encoding using pydicom (~40% faster).

• Added support for faster decoding (~4-5x) and encoding (~20x) of RLE Lossless Pixel Data via the pylibjpeg-rle plugin (1361, 1372).

• Added Dataset.compress() function for compressing uncompressed pixel data using a given encoding format as specified by a UID. Only RLE Lossless is currently supported (1372)

• Added ~pydicom.encoders module and the following encoders:

  • ~pydicom.encoders.RLELosslessEncoder with 'pydicom', 'pylibjpeg' and 'gdcm' plugins

• Added read parameter to ~pydicom.data.get_testdata_file to allow reading and returning the corresponding dataset (1372)

• Handle decoded RLE segments with padding (1438)

• Add option to JSON functions to suppress exception and continue (1332)

• Allow searching ~pydicom.fileset.FileSet s for a list of elements (1428)

• Added hash function to SR ~pydicom.sr.Code (1434)

Fixes

• Fixed pickling a ~pydicom.dataset.Dataset instance with sequences after the sequence had been read (1278)

• Fixed JSON export of numeric values

• Fixed handling of sequences of unknown length that switch to implicit encoding, and sequences with VR UN (1312)

• Do not load external data sources until needed - fixes problems with standard workflow if setuptools are not installed (1341)

• Fixed empty PN elements read from file being str rather than ~pydicom.valuerep.PersonName (1338)

• Fixed handling of JPEG (10918-1) images compressed using RGB colourspace rather than YBR with the Pillow pixel data handler (878)

• Allow to deepcopy a ~pydicom.dataset.FileDataset object (1147)

• Fixed elements with a VR of OL, OD and OV not being set correctly when an encoded backslash was part of the element value (1412)

• Fixed expansion of linear segments with floating point steps in segmented LUTs (1415)

• Fixed handling of code extensions with person name component delimiter (1449)

• Fixed bug decoding RBG jpg with APP14 marker due to change in Pillow (1444)

• Fixed decoding for FloatPixelData and DoubleFloatPixelData via pydicom.pixel_data_handlers.numpy_handler (1457)

Fixes

Remove py.typed ( #1251 )

Fix ImportError with Python 3.6.0 ( #1253 )

Fix converting Sequences with Bulk Data when loading from JSON ( #1254 )

2.1.1

Fixes

• Remove py.typed (1251)

• Fix ImportError with Python 3.6.0 (1253)

• Fix converting Sequences with Bulk Data when loading from JSON (1254)

Enhancements

Large testing data is no longer distributed within the pydicom package with the aim to reduce the package download size. These test files will download on-the-fly whenever either the tests are run, or should the file(s) be requested via the data manager functions. For example:

To download all files and get their paths on disk you can run pydicom.data.get_testdata_files() .

To download an individual file and get its path on disk you can use pydicom.data.get_testdata_file() , e.g. for RG1_UNCI.dcm use pydicom.data.get_testdata_file("RG1_UNCI.dcm")

Added a new pixel data handler based on pylibjpeg which supports all (non-retired) JPEG transfer syntaxes ( #1127 )

Added apply_rescale() alias

Added apply_voi() and apply_windowing()

Added prefer_lut keyword parameter to apply_voi_lut() and handle empty VOI LUT module elements ( #1234 , #1237 )

Added ability to register external data sources for use with the functions in pydicom.data ( #1156 )

contains , next and iter implementations added to PersonName ( #1103 )

Added convenience constants for the MPEG transfer syntaxes to pydicom.uid ( #1155 )

Added support for decoding Waveform Data :

Added pydicom.waveforms module and generate_multiplex() and multiplex_array() functions.

Added Dataset.waveform_array() which returns an ndarray for the multiplex group at index within a Waveform Sequence element.

When JPEG 2000 image data is unsigned and the Pixel Representation is 1 the image data is converted to signed ( #1149 )

Added keyword property for the new UID keywords in version 2020d of the DICOM Standard

Added testing of the variable names used when setting Dataset attributes and INVALID_KEYWORD_BEHAVIOR config option to allow customizing the behavior when a camel case variable name is used that isn’t a known element keyword ( #1014 )

Added INVALID_KEY_BEHAVIOR config option to allow customizing the behavior when an invalid key is used with the Dataset in operator ( #1200 )

Implemented full support (loading, accessing, modifying, writing) of DICOM File-sets and their DICOMDIR files via the FileSet class ( #9 , #243 , #1093 )

Added AllTransferSyntaxes

Added option to turn on pydicom future breaking behavior to allow user code to check itself against the next major version release. Set environment variable “PYDICOM_FUTURE” to “True” or call future_behavior()

Added another signature to the bulk_data_uri_handler in from_json to allow for the communication of not just the URI but also the tag and VR to the handler. Previous handlers will work as expected, new signature handlers will get the additional information.

pack_bits() can now be used with 2D or 3D input arrays and will pad the packed data to even length by default.

Elements with the IS VR accept float strings that are convertible to integers without loss, e.g. “1.0” ( #1240 )

Added encapsulate_extended() function for use when an Extended Offset Table is required ( #1178 )

Changes

Dropped support for Python 3.5 (only Python 3.6+ supported)

Reading and adding unknown non-private tags now does not raise an exception per default, only when enforce_valid_values is set ( #1161 )

Data dictionaries updated to version 2020d of the DICOM Standard

Updated a handful of the SOP Class variable names in _storage_sopclass_uids to use the new UID keywords. Variables with Multiframe in them become MultiFrame , those with and in them become And , and DICOSQuadrupoleResonanceQRStorage becomes DICOSQuadrupoleResonanceStorage .

The following UID constants are deprecated and will be removed in v2.2:

JPEGBaseline : use JPEGBaseline8Bit

JPEGExtended : use JPEGExtended12Bit

JPEGLossless : use JPEGLosslessSV1

JPEGLSLossy : use JPEGLSNearLossless

JPEG2000MultiComponentLossless : use JPEG2000MCLossless

JPEG2000MultiComponent : use JPEG2000MC

In v3.0 the value for JPEGLossless will change from 1.2.840.10008.1.2.4.70 to 1.2.840.10008.1.2.4.57 to match its UID keyword

The following lists of UIDs are deprecated and will be removed in v2.2:

JPEGLossyCompressedPixelTransferSyntaxes : use JPEGTransferSyntaxes

JPEGLSSupportedCompressedPixelTransferSyntaxes : use JPEGLSTransferSyntaxes

JPEG2000CompressedPixelTransferSyntaxes : use JPEG2000TransferSyntaxes

RLECompressedLosslessSyntaxes : use RLETransferSyntaxes

UncompressedPixelTransferSyntaxes : use UncompressedTransferSyntaxes

PILSupportedCompressedPixelTransferSyntaxes

DicomDir and the dicomdir module are deprecated and will be removed in v3.0. Use FileSet instead ( #1211 )

pydicom.overlay_data_handlers is deprecated, use pydicom.overlays instead

Removed transfer syntax limitations when converting overlays to an ndarray ( #1181 )

The overlay_data_handlers config option is deprecated, the default handler will always be used.

Fixes

Dataset.copy() now works as expected ( #1146 )

Optimistically parse undefined length non-SQ data as if it’s encapsulated pixel data to avoid erroring out on embedded sequence delimiter ( #1140 )

Fixed get_testdata_file() and get_testdata_files() raising an exception if no network connection is available ( #1156 )

Fixed GDCM < v2.8.8 not returning the pixel array for datasets not read from a file-like ( #1153 )

Raise TypeError if dcmread() or dcmwrite() is called with wrong argument

Gracefully handle empty Specific Character Set ( #1190 )

Fixed empty ambiguous VR elements raising an exception ( #1193 )

Allow apply_voi_lut() to apply VOI lookup to an input float array

Fixed Dataset.setdefault() not adding working correctly when the default value is None and not adding private elements when enforce_valid_values is True ( #1215 )

2.1.0

Enhancements

• Large testing data is no longer distributed within the pydicom package with the aim to reduce the package download size. These test files will download on-the-fly whenever either the tests are run, or should the file(s) be requested via the data manager functions. For example:

  • To download all files and get their paths on disk you can run pydicom.data.get_testdata_files.

  • To download an individual file and get its path on disk you can use pydicom.data.get_testdata_file, e.g. for RG1_UNCI.dcm use pydicom.data.get_testdata_file("RG1_UNCI.dcm")

• Added a new pixel data handler based on pylibjpeg which supports all (non-retired) JPEG transfer syntaxes (1127)

• Added ~pydicom.pixel_data_handlers.apply_rescale alias

• Added ~pydicom.pixel_data_handlers.util.apply_voi and ~pydicom.pixel_data_handlers.util.apply_windowing

• Added prefer_lut keyword parameter to ~pydicom.pixel_data_handlers.util.apply_voi_lut and handle empty VOI LUT module elements (1234, 1237)

• Added ability to register external data sources for use with the functions in pydicom.data (1156)

• __contains__, __next__ and __iter__ implementations added to ~pydicom.valuerep.PersonName (1103)

• Added convenience constants for the MPEG transfer syntaxes to pydicom.uid (1155)

• Added support for decoding Waveform Data:

  • Added pydicom.waveforms module and ~pydicom.waveforms.numpy_handler.generate_multiplex and ~pydicom.waveforms.numpy_handler.multiplex_array functions.

  • Added Dataset.waveform_array() which returns an ~numpy.ndarray for the multiplex group at index within a Waveform Sequence element.

• When JPEG 2000 image data is unsigned and the Pixel Representation is 1 the image data is converted to signed (1149)

• Added ~pydicom.uid.UID.keyword property for the new UID keywords in version 2020d of the DICOM Standard

• Added testing of the variable names used when setting ~pydicom.dataset.Dataset attributes and ~pydicom.config.INVALID_KEYWORD_BEHAVIOR config option to allow customizing the behavior when a camel case variable name is used that isn't a known element keyword (1014)

• Added ~pydicom.config.INVALID_KEY_BEHAVIOR config option to allow customizing the behavior when an invalid key is used with the ~pydicom.dataset.Dataset in operator (1200)

• Implemented full support (loading, accessing, modifying, writing) of DICOM File-sets and their DICOMDIR files via the ~pydicom.fileset.FileSet class (9, 243, 1093)

• Added ~pydicom.uid.AllTransferSyntaxes

• Added option to turn on pydicom future breaking behavior to allow user code to check itself against the next major version release. Set environment variable "PYDICOM_FUTURE" to "True" or call ~pydicom.config.future_behavior

• Added another signature to the bulk_data_uri_handler in from_json to allow for the communication of not just the URI but also the tag and VR to the handler. Previous handlers will work as expected, new signature handlers will get the additional information.

• ~pydicom.pixel_data_handlers.numpy_handler.pack_bits can now be used with 2D or 3D input arrays and will pad the packed data to even length by default.

• Elements with the ~pydicom.valuerep.IS VR accept float strings that are convertible to integers without loss, e.g. "1.0" (1240)

• Added ~pydicom.encaps.encapsulate_extended function for use when an Extended Offset Table is required (1178)

Changes

• Dropped support for Python 3.5 (only Python 3.6+ supported)

• Reading and adding unknown non-private tags now does not raise an exception per default, only when ~pydicom.config.enforce_valid_values is set (1161)

• Data dictionaries updated to version 2020d of the DICOM Standard

• Updated a handful of the SOP Class variable names in _storage_sopclass_uids to use the new UID keywords. Variables with Multiframe in them become MultiFrame, those with and in them become And, and DICOSQuadrupoleResonanceQRStorage becomes DICOSQuadrupoleResonanceStorage.

• The following UID constants are deprecated and will be removed in v2.2:

  • JPEGBaseline: use ~pydicom.uid.JPEGBaseline8Bit

  • JPEGExtended: use ~pydicom.uid.JPEGExtended12Bit

  • JPEGLossless: use ~pydicom.uid.JPEGLosslessSV1

  • JPEGLSLossy: use ~pydicom.uid.JPEGLSNearLossless

  • JPEG2000MultiComponentLossless: use ~pydicom.uid.JPEG2000MCLossless

  • JPEG2000MultiComponent: use ~pydicom.uid.JPEG2000MC

• In v3.0 the value for JPEGLossless will change from 1.2.840.10008.1.2.4.70 to 1.2.840.10008.1.2.4.57 to match its UID keyword

• The following lists of UIDs are deprecated and will be removed in v2.2:

  • JPEGLossyCompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEGTransferSyntaxes

  • JPEGLSSupportedCompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEGLSTransferSyntaxes

  • JPEG2000CompressedPixelTransferSyntaxes: use ~pydicom.uid.JPEG2000TransferSyntaxes

  • RLECompressedLosslessSyntaxes: use ~pydicom.uid.RLETransferSyntaxes

  • UncompressedPixelTransferSyntaxes: use ~pydicom.uid.UncompressedTransferSyntaxes

  • PILSupportedCompressedPixelTransferSyntaxes

• ~pydicom.dicomdir.DicomDir and the dicomdir module are deprecated and will be removed in v3.0. Use ~pydicom.fileset.FileSet instead (1211)

• pydicom.overlay_data_handlers is deprecated, use pydicom.overlays instead

• Removed transfer syntax limitations when converting overlays to an ndarray (1181)

• The ~pydicom.config.overlay_data_handlers config option is deprecated, the default handler will always be used.

Fixes

• Dataset.copy() now works as expected (1146)

• Optimistically parse undefined length non-SQ data as if it's encapsulated pixel data to avoid erroring out on embedded sequence delimiter (1140)

• Fixed ~pydicom.data.get_testdata_file and ~pydicom.data.get_testdata_files raising an exception if no network connection is available (1156)

• Fixed GDCM < v2.8.8 not returning the pixel array for datasets not read from a file-like (1153)

• Raise TypeError if ~pydicom.filereader.dcmread or ~pydicom.filewriter.dcmwrite is called with wrong argument

• Gracefully handle empty Specific Character Set (1190)

• Fixed empty ambiguous VR elements raising an exception (1193)

• Allow ~pydicom.pixel_data_handlers.util.apply_voi_lut to apply VOI lookup to an input float array

• Fixed Dataset.setdefault() not adding working correctly when the default value is None and not adding private elements when ~pydicom.config.enforce_valid_values is True (1215)

Changelog

Dropped support for Python 2 (only Python 3.5+ supported)

Changes to Dataset.file_meta

file_meta now shown by default in dataset str or repr output; pydicom.config.show_file_meta can be set False to restore previous behavior

new FileMetaDataset class that accepts only group 2 data elements

Deprecation warning given unless Dataset.file_meta set with a FileMetaDataset object (in pydicom 3, it will be required)

Old PersonName class removed; PersonName3 renamed to PersonName . Classes PersonNameUnicode and PersonName3 are aliased to PersonName but are deprecated and will be removed in version 2.1

dataelem.isMultiValue (previously deprecated) has been removed. Use dataelem.DataElement.VM instead.

Enhancements

Allow PathLike objects for filename argument in dcmread , dcmwrite and Dataset.save_as ( #1047 )

Deflate post-file meta information data when writing a dataset with the Deflated Explicit VR Little Endian transfer syntax UID ( #1086 )

Added config.replace_un_with_known_vr to be able to switch off automatic VR conversion for known tags with VR “UN” (see #1067 )

Added config.use_DS_numpy and config.use_IS_numpy to have multi-valued data elements with VR of DS or IS return a numpy array ( #623 ) (much faster for bigger arrays). Both default to False to preserve previous behavior

Fixes

Fixed reading of datasets with an empty Specific Character Set tag (regression, #1038 )

Fixed failure to parse dataset with an empty LUT Descriptor or Red/Green/Blue Palette Color LUT Descriptor element. ( #1049 )

Made Dataset.save_as a wrapper for dcmwrite ( #1042 ) rather than having different checks in each

Removed 1.2.840.10008.1.2.4.70 - JPEG Lossless (Process 14, SV1) from the Pillow pixel data handler as Pillow doesn’t support JPEG Lossless. ( #1053 )

Fixed error when writing elements with a VR of OF ( #1075 )

Fixed improper conversion when reading elements with a VR of OF ( #1075 )

Fixed apply_voi_lut() and apply_modality_lut() not handling (0028,3006) LUT Data with a VR of OW ( #1073 )

Fixed access to private creator tag in raw datasets ( #1078 )

Fixed description of newly added known private tag ( #1082 )

Fixed update of private blocks after deleting private creator ( #1097 )

Fixed bug in updating pydicom.config.use_DS_Decimal flag in DS_decimal()

Enhancements

UID.str no longer returns the UID name (when known). The UID name is still available using the UID.name property.

Dataset equality now only compares the dataset’s DataElements ( #464 )

the codify script now supports VRs OD and OL, and works in Python 3 ( #498 ); documentation has been added for codify

the performance for reading and writing datasets has been improved to be better than in pydicom 0.9.9 ( #605 , #512 )

added support for bit-packed pixel data ( #292 )

updated DICOM dictionary for 2018b edition

added full API documentation to pydicom documentation ( #649 )

Fixes

UID should behave as expected for a python str subclass ( #256 )

group length elements in groups above 0x0006 removed on writing ( #32 )

fixed write_PN raising a TypeError when called with a non-iterable encoding parameter ( #489 )

fixed padding for some odd-sized image data ( #599 )

removed unneeded warning for incorrect date string length ( #597 )

fixed Dataset not slicing correctly when an (0xFFFF,0xFFFF) element is present ( #92 )

use correct VR for unknown private tags and private creators ( #620 )

fixed crash on reading RGB data with implicit VR ( #620 )

parent encoding was not used in sequences without own encoding ( #625 )

fixed error handling for values too large to fit in VR IS ( #640 )

Other

A deprecation warning has been added for UID.eq and UID.ne when comparing UID == [UID name] and UID != [UID name] . Starting in v1.2, UID equality and inequality comparisons will return False when performing the equivalent of UID == [UID name] and UID != [UID name] , respectively. E.g. UID(‘1.2.840.10008.1.1’) == ‘Verification SOP Class’ will return False. Use UID.name == [UID name] instead.