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
-------

.. py:class:: DicomManagerError
   :bases: Exception

   Base exception for DicomManager errors.


.. py:class:: DicomDatabaseNotAvailable
   :bases: DicomManagerError

   Raised when DICOM database is not initialized.


.. py:class:: HighdicomNotAvailable
   :bases: DicomManagerError

   Raised when highdicom is not installed.


.. py: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:**

   .. py:method:: __init__()

      Initialize DICOM manager.

   .. py:method:: database()

      Get Slicer DICOM database.

   .. py:method:: ensure_database_initialized()

      Ensure DICOM database is available and initialized.

   .. py:method:: generate_uid()

      Generate a valid DICOM UID.

   .. py:method:: create_synthetic_dicom()

      Create synthetic DICOM series from a non-DICOM volume.

   .. py:method:: export_segmentation_as_dicom_seg()

      Export segmentation as DICOM SEG with LABELMAP encoding.

   .. py:method:: load_segmentation_by_uid()

      Load DICOM SEG from database by SeriesInstanceUID.

   .. py:method:: get_segmentations_for_volume()

      Find all DICOM SEG series that reference a volume.

   .. py:method:: get_series_description()

      Get SeriesDescription for a series.


Functions
---------

.. py:function:: database()

   Get Slicer DICOM database.
   
   Returns:
       ctkDICOMDatabase instance.
   
   Raises:
       DicomDatabaseNotAvailable: If database is not initialized.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: 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.

.. py:function:: get_series_description()

   Get SeriesDescription for a series.
   
   Args:
       series_uid: SeriesInstanceUID.
   
   Returns:
       SeriesDescription string, or empty string if not found.