DicomManager

DICOM database management for optimization results.

Provides functionality to: - Create synthetic DICOM series from non-DICOM volumes (SampleData) - Export segmentations as DICOM SEG with LABELMAP encoding (Supplement 243) - Query DICOM database for segmentation relationships - Load segmentations from DICOM database

Uses highdicom for DICOM SEG creation with: - LABELMAP encoding for efficient multi-segment storage - Lossless compression (JPEG2000, JPEGLS, RLE) - Full segment metadata (names, colors, terminology)

See ADR-017 for design rationale.

Classes

class DicomManager

Manage DICOM database operations for optimization results.

This class provides a high-level interface for: - Converting SampleData volumes to synthetic DICOM - Exporting segmentations as DICOM SEG with LABELMAP encoding - Loading segmentations from DICOM database

Uses highdicom for DICOM SEG creation (not QuantitativeReporting/dcmqi) to support LABELMAP encoding (DICOM Supplement 243) and compression.

Usage:

manager = DicomManager()

# Create synthetic DICOM from SampleData volume volume_series_uid = manager.create_synthetic_dicom(

volume_node=volume_node, patient_id=”AdaptiveBrush_Test”, study_description=”Optimization Run”, output_dir=Path(“output/dicom/volume”)

)

# Export segmentation as DICOM SEG with LABELMAP encoding seg_series_uid = manager.export_segmentation_as_dicom_seg(

segmentation_node=seg_node, reference_volume_node=volume_node, series_description=”trial_001_watershed”, output_dir=Path(“output/dicom/segmentations”), compression=”JPEG2000Lossless” # or “JPEGLSLossless”, “RLELossless”

)

# Load segmentation from DICOM database seg_node = manager.load_segmentation_by_uid(seg_series_uid)

Methods:

__init__()

Initialize DICOM manager.

database()

Get Slicer DICOM database.

ensure_database_initialized()

Ensure DICOM database is available and initialized.

generate_uid()

Generate a valid DICOM UID.

create_synthetic_dicom()

Create synthetic DICOM series from a non-DICOM volume.

export_segmentation_as_dicom_seg()

Export segmentation as DICOM SEG with LABELMAP encoding.

load_segmentation_by_uid()

Load DICOM SEG from database by SeriesInstanceUID.

get_segmentations_for_volume()

Find all DICOM SEG series that reference a volume.

get_series_description()

Get SeriesDescription for a series.

Functions

database()

Get Slicer DICOM database.

Returns:

ctkDICOMDatabase instance.

Raises:

DicomDatabaseNotAvailable: If database is not initialized.

ensure_database_initialized()

Ensure DICOM database is available and initialized.

If database is not open, attempts to open/create a default one.

Returns:

True if database is ready, False otherwise.

generate_uid()

Generate a valid DICOM UID.

Uses UUID-based generation with the 2.25 prefix for universally unique identifiers.

Returns:

A valid DICOM UID string.

create_synthetic_dicom()

Create synthetic DICOM series from a non-DICOM volume.

Converts a volume node (e.g., from SampleData) to DICOM format, saves to disk, and imports into the DICOM database.

Uses Slicer’s DICOMScalarVolumePlugin for volume export.

Args:

volume_node: vtkMRMLScalarVolumeNode to convert. patient_id: DICOM PatientID tag value. study_description: DICOM StudyDescription tag value. output_dir: Directory to save DICOM files. patient_name: DICOM PatientName (defaults to patient_id). study_date: DICOM StudyDate (defaults to today). series_description: DICOM SeriesDescription (defaults to volume name).

Returns:

SeriesInstanceUID of the created DICOM series.

Raises:

DicomManagerError: If export fails.

export_segmentation_as_dicom_seg()

Export segmentation as DICOM SEG with LABELMAP encoding.

Uses highdicom for efficient multi-segment storage with: - LABELMAP encoding (DICOM Supplement 243) - Optional lossless compression (requires additional packages) - Full segment metadata

Args:

segmentation_node: vtkMRMLSegmentationNode to export. reference_volume_node: Reference volume (must have DICOM attributes). series_description: DICOM SeriesDescription for the SEG. output_dir: Directory to save DICOM SEG file. compression: Compression type - “ExplicitVRLittleEndian” (default, no compression),

“JPEG2000Lossless” (requires pylibjpeg+pylibjpeg-openjpeg), “JPEGLSLossless” (requires pylibjpeg+pylibjpeg-libjpeg), “RLELossless” (requires pylibjpeg).

segment_metadata: Optional metadata to include (algorithm params, etc.).

Returns:

SeriesInstanceUID of the created DICOM SEG.

Raises:

HighdicomNotAvailable: If highdicom cannot be installed. DicomManagerError: If export fails.

load_segmentation_by_uid()

Load DICOM SEG from database by SeriesInstanceUID.

Args:

series_uid: SeriesInstanceUID of the DICOM SEG.

Returns:

vtkMRMLSegmentationNode loaded from database.

Raises:

DicomManagerError: If loading fails.

get_segmentations_for_volume()

Find all DICOM SEG series that reference a volume.

Args:

volume_series_uid: SeriesInstanceUID of the reference volume.

Returns:

List of SeriesInstanceUIDs for DICOM SEG that reference this volume.

get_series_description()

Get SeriesDescription for a series.

Args:

series_uid: SeriesInstanceUID.

Returns:

SeriesDescription string, or empty string if not found.