v0.28.0

What's Changed

This is a significant release with new features belonging to three major themes (as well as a large number of smaller fixes):

1. Revamp of Legacy Converted Enhanced Images (#388 and #426). Legacy Converted Enhanced Images have been implemented in the library for a long time, but had many limitations and some known issues. Building on work done years ago by @afshinmessiah, this release contains a full re-implementation that resolves all the known issues and adds many new features, including much better handling of metadata, transcoding to new transfer syntaxes, monochrome1 to monochrome2 conversion, spatial sorting and dimension indices, correct handling of private tags, mapping of Body Part Examined to Anatomic Region Sequence, and more.
2. Revamp of Parametric Maps (#372). Parametric Maps have also been implemented for a while, but have always been looked over for new features relative to Segmentations. This release merges a significant amount of the implementations of the two classes onto the common _Image base class, meaning that Parametric Maps (and potentially other IODs in the future) can benefit from the features implemented for segmentations such as automatic tiling, construction from Volumes, creation of pyramids, support for TILED_FULL and TILED_SPARSE, etc
3. Conversion of highdicom Volumes to objects from other libraries (#387, #394, #411). This stream of work has been led by @mccle. First, we have added a standardised way to handle optional dependencies in highdicom. Using this, we have added methods on the Volume class to convert to and from ITK Images, SimpleITK images, and nibabel, allowing highdicom to integrate with a far wider range of image processing pipelines and interact with files from other formats, both as a reader (allowing you to for example read a DICOM segmentation or parametric map and convert it to an ITK/SITK image) and a writer (making it easier to store an ITK/SITK image in the DICOM objects supported by highdicom)

Features

• Feature/optional dependencies by @mccle in #387
• Feature/itk volume conversions by @mccle in #394
• Add family and manufacturer to Algorithm Identification template by @CPBridge in #414
• Legacy conversion revamp by @CPBridge in #388
• Parametric Map Revamp by @CPBridge in #372
• Specific character set by @CPBridge in #423
• Add new "get pixels by source" methods by @CPBridge in #426
• Add tolerance parameter to orientation by @CPBridge in #405
• Add nibabel volume conversions and tests by @mccle in #411

Bug Fixes

• Tolerate missing ReferencedInstanceSequence by @CPBridge in #380
• Avoid division by zero in volume normalization by @CPBridge in #381
• Increase tolerance used to determine a matrix is orthogonal by @CPBridge in #382
• Fix time-of-day-dependent failure in series_time validation by @yarikoptic in #395
• Remove algorithm identification from background class in labelmap segmentations by @CPBridge in #413
• Swap code used for source images in measurement groups by @CPBridge in #412
• Volume dtype restriction by @mccle in #410
• Remove the content date and content time attributes from presentation state IODs by @CPBridge in #417
• Stricter spatial checks by @CPBridge in #427
• Disallow segmented LUT in presentation states by @CPBridge in #424

Tooling and Code Quality

• PEP 639 compliance by @DimitriPapadopoulos in #378
• Add support for python 3.14 by @CPBridge in #379
• PEP 735 compliance: dependency groups by @DimitriPapadopoulos in #397
• Fix readthedocs build errors by @CPBridge in #402
• Move .readthedocs.yaml to use dependency groups by @CPBridge in #403
• Dependabot actions by @fedorov in #420
• CI: Bump the github-actions group with 2 updates by @dependabot[bot] in #421
• Add windows and macos github actions tests by @mccle in #428
• CI: Bump pytest from 8.3.5 to 9.0.3 in #429

Documentation

• Fix documentation typos and grammar errors by @DimitriPapadopoulos in #392
• Update acknowledgments by @CPBridge in #390
• Remove SOPClass "copy" methods from docs, add notes by @CPBridge in #385
• Add .mailmap to consolidate author identities by @yarikoptic in #401
• Add doc pages on context groups and dcmterms link by @CPBridge in #408
• Update funding information in README by @fedorov in #416
• Clarify docstings of get_volume_positions and get_series_volume_positions by @CPBridge in #398

New Contributors

• @mccle made their first contribution in #387
• @dependabot[bot] made their first contribution in #421

Also I wish to thank @afshinmessiah for his important contributions to the legacy converted enhanced image implementation and the APOLLO 5 project for funding much of the work that led to this release.

Full Changelog: v0.27.0...v0.28.0

v0.27.0

What's Changed

• Add color conversions and add RecommendedCIELabColor to AnnotationGroup by @CPBridge in #374
• Further date control by @CPBridge in #376

Full Changelog: v0.26.1...v0.27.0

v0.26.1

Critical bug fix release

What's Changed

• Fix tiled segmentation volume origin bug by @CPBridge in #368

Full Changelog: v0.26.0...v0.26.1

v0.26.0

New Features

• Usability improvements for working with volumes and segmentations. Includes new match_orientation method on a Volume, new from_reference_convention parameter to Volume constructors, and new highdicom.spatial.convert_affine_to_convention function, and various docs improvements. By @CPBridge in #367
• Improve logic to match segmentation frames to source images. Allows users to construct segmentations from Volumes without losing items in the "Derivation Image Sequence". Also allows for segmentations with multiple derivation images per frame (for construction and parsing). By @CPBridge in #361
• Improvements to spatial calculations, including control over the tolerance parameter used to determine orthogonality, and logging of reasons for determining a set of positions is not a volume. By @CPBridge in #357
• Add further description of VOLUME pixel origin interpretation and new checks against obvious mistakes by @CPBridge in #358
• Support for the Contributing Equipment Sequence by @CPBridge in #356
• Add support for creating multiframe images with Extended Offset Tables by @CPBridge in #354

Bug Fixes

• Fix ability to read from filelikes with a name property, add docs for reading from S3 by @CPBridge in #336
• Allow tiled full images with no dimension index by @CPBridge in #339
• Fix relationship type of geometric purpose by @CPBridge in #343
• Parametric map fixes by @CPBridge in #346
• Fix spacing issue when using downsample factors for pyramid by @CPBridge in #349
• Control numpy output arrays to improve efficiency by @CPBridge in #350
• Allow dimension indices to be in the shared functional groups sequence by @CPBridge in #345
• added conda recipe to installation intructions by @sarthakpati in #362
• Fix parsing TID1500 when template identifiers are missing by @CPBridge in #360
• Simply decode_frame to use pydicom decoder directly by @CPBridge in #353

Tooling

• Set COVERAGE_CORE to speed up tests on 3.12 by @CPBridge in #340

Documentation

• Quickstart docs improvements by @CPBridge in #341

New Contributors

• @sarthakpati made their first contribution in #362

Full Changelog: v0.25.1...v0.26.0

v0.25.1

Patch release with a few bug fixes and documentation updates.

What's Changed

• Disallow measurement report with no measurement groups by @CPBridge in #325
• Fix spatial transformer from_images docstrings by @CPBridge in #326
• Enforce series description length by @CPBridge in #328
• Correctly format decimal string for spacing between slices by @CPBridge in #332
• add IDC acknowledgments by @fedorov in #331
• Allow reading from bytes objects by @CPBridge in #333
• Add docs section on working with remote filesystems by @CPBridge in #334

Full Changelog: v0.25.0...v0.25.1

v0.25.0

New Features

• Add get_frames and get_stored_frames methods by @CPBridge in #320

Bug Fixes

• Critical bug fixes from the 0.24.0 release, including the implementation of the Volume.match_geometry(), Volume.random_permute_spatial_axes() and Volume.random_flip_spatial() methods, and greatly improve test coverage of the volume class by @CPBridge in #319
• Enforce monochrome 2 for input files to legacy conversion by @CPBridge in #321

Documentation

• New sections in the user guide on Images, Volumes, and Pixel Transforms
• Add channel section to volume user guide by @CPBridge in #322

Full Changelog: v0.24.0...v0.25.0

v0.24.0

This is a significant release with several important new features added to the library.
The user guide will be updated soon with explanations of the new functionality.

Features

• Update internal DICOM standard information to 2024c
• Add support for the new LABELMAP segmentation type, introduced in DICOM 2024c. Labelmap segmentations store non-overlapping segments as an array in which pixel value indicates membership of a segment. This can be used simply by setting the segmentation_type parameter of the highdicom.seg.Segmentation constructor to "LABELMAP". Parsing of Labelmap segmentations is also supported. By @CPBridge in #234
• Add implementations of pixel transformations in new highdicom.pixels module and elsewhere, including real world value map, modality LUT, VOI LUT, presentation LUT, and Palette Color LUT.
• Add new general highdicom.Image class for reading frames from general DICOM images, and creating Volumes from general images. Methods on this class allow for reading frames with the above pixel transformations configurably applied.
• Add new highdicom.Volume class, representing an array of pixels in 3D space by @CPBridge in #277
• Several new functions in highdicom.spatial related to 3D volumes and affine matrices.
• Automatically set the DimensionOrganizationType attribute of a segmentation to 3D if the conditions are met.
• Add magic methods to allow segmentation objects to be pickled and unpickled
• Use pyupgrade to update all type hints to 3.10+ style
• Add ability to add spatial coordinates to a measurement by @Fedalto in #307
• Add support for python 3.13 by @CPBridge in #312

Full Changelog: v0.23.1...v0.24.0

v0.23.1

Patch release with a few minor bug fixes

Bug Fixes

• Update docs to reflect python 3.10 dependency by @CPBridge in #308
• Allow searching SRs using LongCodeValue and URNCodeValue. Fix for #309 by @rhaxton in #310
• Fix for BOT construction with pydicom 3, by @CPBridge in #314
• Fix SR if SpacingBetweenSlices is not set, by @Fedalto in #315

New Contributors

• @rhaxton made their first contribution in #310

Full Changelog: v0.23.0...v0.23.1

v0.23.0

Dependencies

• Highdicom now depends upon pydicom > 3.0.1. #301
• Highdicom now requires python > 3.10. This was necessitated by a similar move from pydicom. #301
• Remove references to numpy.float_ to allow working with numpy>2

Tooling/Repo

• We have adopted the contributor covenant. #271
• Various style improvements #286 #287 #289 #290 #291 #292
• We have moved to pyproject.toml metadata. #293
• Improve automated checks to enforce repo review rules #296

Features

• Further checks on graphic data for SRs #276
• Additional checks for microscopy bulk annotation coordinate types #281
• Further improvements in segmentation creation efficiency #285
• Allow creation of pyramid segmentations with floating point arrays, or with multiple segments #297
• Add options allowing to infer the subject context from an image #298
• Use pydicom 3 features to enable additional transfer syntaxes in compression.
• Add methods to get a list of images used as evidence within an SR #303
• Add a further_source_images option to the segmentation constructor #304

Fixes

• Minor fixes for microscopy bulk annotation graphic data #278
• Remove the JP2 wrapper from JPEG 2000 encoding

Docs

• Added a gitflow section to the developer guide. #272

v0.22.0

Probably left this one far too long...

New Features

• New features for parsing existing Microscopy Bulk Annotations: annread function and annotation_coordinate_type property (#230)
• Multiprocessing for frame encoding in segmentation construction (#245)
• A major set of improvements for working with tiled segmentations including ability to pass in total pixel matrices to the segmentation constructor, the ability to create and read TILED_FULL segmentations, and the ability to construct segmentation total pixel matrices from tiled images (#248)
• New function to create multiresolution segmentation pyramids (#253)

Bug fixes

• Allow duplicate entries in the ReferencedSeriesSequence of a segmentation image (#229)
• Remove plane orientation from the shared functional groups in the case of segs using the slide coordinate system (#236), a DICOM compliance issue
• Exclude incompatible pydicom 2.4.0 in setup.py (#238)
• Fixes to various value representations (#239)
• Fix return type of highdicom.seg.DimensionIndexSequence.get_plane_positions_of_image (#240)
• Correctly account for chrominance subsampling of natively encoded YBR_FULL_422 images in the ImageFileReader (#242)
• Work around pillow 10.0.0 breaking changes (#244)
• Specimen description and preparation fixes within microscopy related content items (#246)
• A number of style improvements (#257 #258 #259 #261 #262 #263 #264 #265 #268)

Performance improvements

• Significant improvements to segmentation creation efficiency (#227)

Documentation and tests

• Add codespell tool to check for spelling errors in the docs (#237)
• Fix documentation links (#250)
• Fix the readthedoc config (#256)
• Fix to an incorrectly written frame encoding test (#270)
• Use latest version of github actions (#266)

New contributors

Thanks to @yarikoptic @thomas-albrecht @elitalien and @DimitriPapadopoulos for their first contributions to highdicom!