DOCSEARCHbyAlgolia
Submit Docs

highdicom

repository·master·Indexed 42 days ago

https://github.com/imagingdatacommons/highdicom

A pure Python library built on pydicom providing high-level APIs for machine learning and computer vision workflows involving DICOM data. It specializes in frame selection, pixel transforms, and the standardized encoding of annotations, segmentations, and structured reports. Version 0.28.1.

Tokens
98.8K
Snippets
203
Records
273
Agent score
53%

What's inside highdicom

  1. Overview of highdicom capabilities

    master

    What is highdicom?

    highdicom is a pure Python package built on top of pydicom designed to provide a high-level API for DICOM operations specifically tailored for machine learning, computer vision, and computational analysis.

    Core Functionalities

    1. Reading and Formatting DICOM Images

    Allows reading a wide variety of modalities (radiology, pathology, etc.) and selecting/formatting frames for analysis. Unlike pydicom, highdicom handles:

    • Spatial arrangements of frames.
    • Application of pixel transforms.

    2. Storing Derived Information

    Enables storing information from computational analyses or human annotations into derived DICOM objects, including:

    • Annotations and Segmentation images
    • Parametric Map images
    • Structured Reports (numerical results, qualitative evaluations, or vector graphic annotations)
    • Secondary Capture images
    • Key Object Selection documents
    • Legacy Converted Enhanced CT/PET/MR images (e.g., single frame to multi-frame conversion)
    • Softcopy Presentation State instances (Grayscale, Color, and Pseudo-Color)

    3. Reading Derived DICOM Files

    Provides tools to read existing derived DICOM files and filter or access the specific information contained within them.

  2. Overview of the highdicom package capabilities

    master

    highdicom is a pure Python package built on top of pydicom designed for high-level DICOM operations common in machine learning and computer vision. It facilitates three primary workflows:

    1. Reading and Formatting: Reading diverse DICOM modalities (radiology, pathology, etc.) and selecting/formatting frames for analysis. It handles spatial arrangements and pixel transforms that are not natively managed by pydicom.
    2. Storing Derived Information: Creating derived DICOM objects to store computational analysis or human annotations. Supported types include:
      • Annotations
      • Parametric Map images
      • Segmentation images
      • Structured Reports (numerical results, qualitative evaluations, vector graphics)
      • Secondary Capture images
      • Key Object Selection documents
      • Legacy Converted Enhanced CT/PET/MR images
      • Softcopy Presentation State instances (Grayscale, Color, and Pseudo-Color)
    3. Reading Derived Files: Accessing and filtering information within existing derived DICOM files.

  3. What is highdicom and what are its goals?

    master

    highdicom is a Python package designed to abstract the complexity of the DICOM standard. It allows developers of image analysis applications to focus on algorithms and data analysis instead of low-level data encoding.

    Key features include:

    • A high-level, intuitive API for creating high-quality DICOM objects and accessing information in existing objects.
    • Compatibility with digital pathology (Slide Microscopy/SM) and radiology (Computed Tomography/CT and Magnetic Resonance/MR) imaging modalities.
    • Built-in DICOM validation that automatically checks for compliance with the standard during object construction.

  4. Use the highdicom.sr sub-package for Structured Reports

    master

    Highdicom provides support for creating and handling Structured Report (SR) DICOM files through the highdicom.sr sub-package. Structured reports are used to store information derived from medical images in a structured, computer-readable format.

    Detailed guidance for specific SR types and parsing is available in the following specialized sections:

    • General SRs: Core concepts and usage for general structured reports.
    • TID 1500: Implementation and usage of the DICOM Standard Template for Anatomical Structures (TID 1500).
    • TID 1500 Parsing: How to parse existing TID 1500 structured reports.

  5. Explore the highdicom package modules

    master

    The highdicom package is organized into several specialized modules and subpackages for handling different aspects of High-DICOM data. Use the following modules to access core functionality:

    Core Modules

    • highdicom.color: Handling color-related data.
    • highdicom.frame: Managing frame-specific information.
    • highdicom.io: Input/Output operations for DICOM files.
    • highdicom.spatial: Spatial coordinate and geometry management.
    • highdicom.valuerep: Implementation of DICOM Value Representations.
    • highdicom.utils: General utility functions.
    • highdicom.pixels: Pixel data manipulation and access.

    Specialized Subpackages

    • highdicom.ann: Anatomical annotations.
    • highdicom.ko: Key Object annotations.
    • highdicom.pm: Presentation Mark annotations.
    • highdicom.pr: Presentation State annotations.
    • highdicom.seg: Segmentation objects (includes highdicom.seg.utils).
    • highdicom.sr: Structured Reports (includes highdicom.sr.utils).
    • highdicom.sc: Softcopy Presentation (includes highdicom.sc).
    • highdicom.legacy: Support for older or deprecated High-DICOM implementations.

  7. What is a highdicom.Volume?

    master

    A highdicom.Volume is a class used to work with regularly-sampled volumetric arrays (like CT, MRI, or PET data). Unlike other classes in the library, a Volume is not a DICOM object itself; it is a container for a voxel array and an affine matrix. This allows you to derive results (like segmentations) and store them in new DICOM files with correct spatial metadata without manually handling coordinate transformations.

    A Volume consists of:

    1. An array of voxels (3 or more dimensions).
    2. An affine matrix describing the array's position in 3D space within a frame-of-reference coordinate system (e.g., PATIENT or SLIDE).

  8. Overview of Structured Reports (SR) in Highdicom

    master

    Structured reports (SR) are DICOM files that document information derived from medical images in a structured, computer-readable format. In Highdicom, SR functionality is provided by the highdicom.sr sub-package.

    At the core of an SR are Content Items. Each content item is a collection of DICOM attributes (a pydicom.Dataset) representing a single piece of information. Every content item consists of:

    • A name: A coded concept describing the information being conveyed.
    • A value: The actual information of interest (the type of which determines the content item class).

    Content items can be nested in a tree structure using ContentSequence to create complex, hierarchical reports.

  9. How Per-Frame Derivation Image Sequences work

    master

    In a highdicom.seg.Segmentation object, the Per Frame Functional Groups Sequence attribute contains metadata for each frame. A key component is the Derivation Image Sequence, which specifies which frames of the source image/series were used to derive a specific segmentation frame.

    Populating this sequence is important for:

    1. Accessing segmentation frames by source frame SOP Instance UID (using get_pixels_by_source_instance) or frame number (using get_pixels_by_source_frame).
    2. Ensuring compatibility with viewers that require explicit geometrical relationships to source images.

    highdicom attempts to automatically populate this sequence based on the pixel_array provided:

    • Pixel-for-pixel alignment: If orientation, spacing, and positions match, Derivation Image Sequence is populated and Spatial Locations Preserved is set to indicate alignment.
    • Geometric correspondence without pixel alignment: If frames relate via in-plane rotations, flips, or scaling, Derivation Image Sequence is populated but Spatial Locations Preserved is set to 'NO'.
    • No correspondence: If there is out-of-plane rotation or scaling, the Derivation Image Sequence remains empty.

    If you use a highdicom.Volume as input and need the sequence populated, ensure you match the geometry before passing it to the constructor.

  10. Convert pydicom datasets to highdicom types

    master

    Highdicom is built on top of pydicom. While highdicom types are derived from pydicom.dataset.Dataset or pydicom.sequence.Sequence and remain interoperable with them, you can use specific constructors to convert existing pydicom objects into highdicom types. This enables the use of highdicom's convenient access APIs on standard datasets.

    Use the following methods for eager type conversion:

    • from_dataset()
    • from_sequence()

    These methods convert the target dataset and all nested datasets within it into their corresponding highdicom types where applicable.

  11. Understand the relationship between Highdicom and Pydicom

    master

    The highdicom library is built on top of pydicom. While pydicom provides the fundamental pydicom.Dataset class for reading, writing, and manipulating DICOM attributes and pixel data, it is a general-purpose tool that does not implement IOD-specific (Information Object Definition) logic.

    highdicom specializes this by defining subclasses of pydicom.Dataset for specific DICOM IODs. This allows for easier and more correct creation of complex DICOM objects (like Segmentations or Structured Reports) by enforcing standard-required attributes and relationships through specialized constructors and methods.

  12. How pixel transforms are applied by default

    master

    Highdicom follows specific default behaviors for different image types to balance accuracy and usability:

    • Monochrome images: The Real World Value Map is applied if present. If not present, the Modality LUT and Presentation LUT are applied if present. The VOI transform is never applied by default.
    • Color images: The ICC profile is applied if present.
    • Palette Color images: The Palette Color LUT is applied (expected to be present), followed by the ICC profile if present.