v0.21.0

New features

• The implementation of methods for constructing segmentation pixels arrays from a highdicom.seg.Segmentation object (highdicom.seg.Segmentation.get_pixels_by_source_instance(), highdicom.seg.Segmentation.get_pixels_by_source_frame(), and highdicom.seg.Segmentation.get_pixels_by_dimension_index_values()) have been considerably refactored with a general focus on improving the usability for large segmentation objects (#208). These changes are compatible with existing code except that in some cases the methods may return numpy arrays with a smaller unsigned integer data type than they previously did. User code should see significant speed-ups without any changes. The new versions have several improvements:
  • Improvements in computational efficiency due to a redesign of the way the frame look-up table is stored under the hood. Now an in-memory sqlite database is used through the Python standard library sqlite3 module. This allows for considerably faster and more flexible querying.
  • Significant improvements in memory efficiency for the case where combine_segments=True. Previously the memory usage scaled as O(n) in the number of segments, now it is constant (O(1)).
  • When combining segments, the methods now automatically determine and return an appropriate unsigned integer datatype to return the smallest array that can represent all segments. This has been observed to reduce both the memory usage and improve speed (largely due to the reducing the need to allocate memory for unnecessarily large numpy arrays)
  • There is a new parameter, dtype, that allows the user to choose the data type of the output array (overriding the automatically determined default).
  • There is a further new boolean parameter skip_overlap_checks, which allows the user to specify that the check for overlapping segments in the case where combine_segments=True is skipped. This makes a significant difference to runtime. If this is done and two segments do overlap, the segment with the highest output segmentation number will be placed into the output array preferentially. The default behaviour matches the previous behaviour in that checks for overlapping segments are performed, and an error is raised if any two segments overlaps.
  • The user guide is updated to the preferred way of accessing pixel data using the above methods.
• There is now an optional parameter in from_dataset() methods called copy. By default, this parameter is True, meaning that a full deepcopy of the original dataset is made before conversion to the highdicom class, which matches the previous behaviour. This is the "safest" option that prevents potentially unwanted behaviour downstream if the user tries to re-use the original dataset. However if the user chooses to set this parameter to False, then the deepcopy is skipped and the original dataset is updated in place. This can give a very significant speed-up when the segmentation object are large. Additionally this is used in the segread and srread functions to give a significant speed up as it is never necessary to deepcopy the temporary object read from file (#207).
• Added a new function highdicom.sr.srread(), similar to the existing highdicom.seg.segread(), to read a dataset representing a supported Structured Report SOP Class from a file and convert it to the appropriate highdicom class automatically (#215).
• Users may now pass a single-element Sequence to the content parameter of the __init__ methods of Structured Report SOP classes, as alternative to passing a pydicom.Dataset. This is more intuitive for users that have constructed a highdicom.sr.MeasuremenrtReport class and wish to use it as the content of a new Structured Report (#216).

Enhancements

• The library's repository was moved to the ImagingDataCommons organization on GitHub, and all URLs were updated (#212).
• The library's Github Actions now run the tests using Python 3.11 in addition to older versions (#217) to ensure that highdicom supports the latest Python version.

Bug fixes

• A minor tweak to the routine for segmentation construction that avoids creating a copy of large portions of the input array just to find the unique values (#221).
• A bug, resulting in the ReferencedImageSequence of a highdicom.ann.MicroscopyBulkSimpleAnnotations always being empty, was resolved (#220).
• A mistake in the docstrings of the PixelToReferenceTransformer, ReferenceToPixelTransformer, and ImageToReferenceTransformer classes was fixed (#209).
• A bug that resulted in GSPS creation failing when the referenced images have multiple values for WindowWidth, WindowCenter and/or WindowCenterWidthExplanation was fixed (#211).

v0.20.0

v0.20.0

New features

• Move pylibjpeg and related dependencies (pylibjpeg-libjpeg and pylibjpeg-openjpeg) from requirements to optional requirements. This means that the default installation is compatible with highdicom's MIT license. There are now some transfer syntaxes that are not supported with the default installation. Users can install highdicom with the optional dependencies by specifying highdicom[libjpeg] as their installation target. Update github test runners to support both the cases where the optional requirements are installed and are not installed (#201).

Enhancements

• Add citation file to allow citing the package (#204).

Bug fixes

• Use a deepcopy for CodedConcept.from_dataset() to avoid issues with optional attributes of the sequence getting lost (#205).
• When the omit_empty_frames option is used for a Segmentation and an empty segmentation mask is passed (i.e. a mask with all zeros), the constructor will issue a UserWarning and ignore the omit_empty_frames option (#181).

0.19.0

New features

• Implementation of TID 1601 Image Library Entry (#83)

Enhancements

• Allow annotations to reference multiple multi-frame images (#193)
• Remove module level imports of module data to improve test coverage reporting (#196)

Bug fixes

• Fix namespace of segmentation usage example (#195)

0.18.4

Enhancements

• Improve efficiency of plane position computation (#191)

Bug fixes

• Fix decoding of graphic data in annotations group (#192)

0.18.3

Bug fixes

• Do exact comparison when checking coordinates of graphics data in constructor of ann.AnnotationGroup (#169)
• Fix example for use of io.ImageFileReader (#185)

Enhancement

• Don't fail upon construction of io.ImageFileReader if color image lacks ICC Profile (#189)

0.18.2

Enhancements

• Allow segmentation of images without a frame of reference UID (#183)
• Allow passing of additional attributes of equipment module (#182)

0.18.1

Bug fixes

• Fix references of source images and inclusion of palette color lut attributes in Advanced Blending Presentation State (#179)

0.18.0

New features

• Implement Softcopy Presentation State IODs (#139)
• Add method to construct UID from an existing UUID (#176)

Bug fixes

• Ensure values of data elements with binary VRs are encoded/decoded correctly (#173)

Breaking changes

• Deprecation of big endian transfer syntaxes (#173 see section in release notes)

0.17.0

Enhancements

• Support referencing of source images in SR template TID 1501 (#169)

Bug fixes

• Fix typo in error message (#175)

0.16.0

New features

• Implement decoding API for SpecimenDescription and related classes such as SpecimenPreparationStep and friends (#161)

Enhancements

• Run tests on examples included in docstrings (#165)

Bug fixes

• Fix computation of tile positions for TILED_FULL images that contain multiple optical paths (#161)

Breaking changes

• Derive SpecimenPreparationStep from pydicom.Dataset instead of pydicom.Sequence (#161, see section in release notes for further details).