GoldStandardManager
===================

Gold standard segmentation management.

Provides functionality to save, load, and compare gold standard segmentations
for regression testing and optimization workflows.

Storage format:
- gold.seg.nrrd: Canonical format (git-tracked, small)
- metadata.json: Statistics + creation info (git-tracked)
- .dicom_cache/: Generated on-demand for CSE compatibility (git-ignored)

Classes
-------

.. py:class:: GoldStandardManager

   Manage gold standard segmentations for regression testing.
   
   Gold standards are saved in the GoldStandards/ directory with:
   - gold.seg.nrrd: Canonical segmentation format (git-tracked)
   - metadata.json: Creation info, parameters, statistics
   - reference_screenshots/: Visual references
   
   DICOM SEG files are generated on-demand in .dicom_cache/ for
   CrossSegmentationExplorer compatibility.
   
   Usage:
       manager = GoldStandardManager()
   
       # Save a gold standard
       manager.save_as_gold(
           segmentation_node=seg_node,
           volume_node=vol_node,
           segment_id="Tumor",
           name="MRBrainTumor1_tumor",
           click_locations=[{"ras": [5.6, -29.5, 28.4], ...}],
           description="Tumor segmentation using watershed"
       )
   
       # Load a gold standard
       gold_seg, metadata = manager.load_gold("MRBrainTumor1_tumor")
   
       # List available gold standards
       standards = manager.list_gold_standards()

   **Methods:**

   .. py:method:: __init__()

      Initialize gold standard manager.

   .. py:method:: save_as_gold()

      Save current segmentation as new gold standard (.seg.nrrd format).

   .. py:method:: load_gold()

      Load gold standard segmentation and metadata.

   .. py:method:: get_dicom_seg_path()

      Get DICOM SEG path, generating if needed.

   .. py:method:: list_gold_standards()

      List all available gold standards with metadata.

   .. py:method:: gold_exists()

      Check if a gold standard exists.

   .. py:method:: get_gold_path()

      Get path to a gold standard directory.

   .. py:method:: update_metadata()

      Update metadata for an existing gold standard.

   .. py:method:: update_statistics()

      Recompute and update statistics for a gold standard.

   .. py:method:: delete_gold()

      Delete a gold standard.

   .. py:method:: save_reference_screenshot()

      Save a reference screenshot for a gold standard.

   .. py:method:: compare_statistics()

      Compare trial statistics against gold standard.

   .. py:method:: format_statistics()

      Format statistics as human-readable string.

   .. py:method:: format_comparison()

      Format comparison as human-readable string.


Functions
---------

.. py:function:: save_as_gold()

   Save current segmentation as new gold standard (.seg.nrrd format).
   
   Automatically computes and saves statistics for change detection.
   
   Args:
       segmentation_node: Segmentation MRML node to save.
       volume_node: Volume node providing geometry.
       segment_id: Segment ID within the segmentation.
       name: Name for the gold standard (used as directory name).
       click_locations: List of click locations with parameters.
           Format: [{"ras": [R, A, S], "ijk": [I, J, K], "params": {...}}, ...]
       description: Human-readable description of this gold standard.
       algorithm: Algorithm used to create the segmentation.
       parameters: Algorithm parameters used.
   
   Returns:
       Path to the gold standard directory.

.. py:function:: load_gold()

   Load gold standard segmentation and metadata.
   
   Args:
       name: Name of the gold standard to load.
       volume_node: Reference volume for verification (optional but recommended).
       verify: If True (default), verify checksum matches metadata.
   
   Returns:
       Tuple of (segmentation_node, metadata_dict).
   
   Raises:
       FileNotFoundError: If gold standard does not exist.
       ValueError: If verification fails (checksum mismatch).

.. py:function:: get_dicom_seg_path()

   Get DICOM SEG path, generating if needed.
   
   Used for CrossSegmentationExplorer compatibility.
   
   Args:
       name: Name of the gold standard.
       volume_node: Reference volume (required if cache needs generation).
   
   Returns:
       Path to DICOM SEG file.
   
   Raises:
       FileNotFoundError: If gold standard does not exist.
       ValueError: If volume_node required but not provided.

.. py:function:: list_gold_standards()

   List all available gold standards with metadata.
   
   Returns:
       List of metadata dictionaries, each with added "name" field.

.. py:function:: gold_exists()

   Check if a gold standard exists.
   
   Args:
       name: Name of the gold standard.
   
   Returns:
       True if exists, False otherwise.

.. py:function:: get_gold_path()

   Get path to a gold standard directory.
   
   Args:
       name: Name of the gold standard.
   
   Returns:
       Path to the gold standard directory.

.. py:function:: update_metadata()

   Update metadata for an existing gold standard.
   
   Args:
       name: Name of the gold standard.
       updates: Dictionary of metadata fields to update.

.. py:function:: update_statistics()

   Recompute and update statistics for a gold standard.
   
   Useful after modifying a gold standard segmentation.
   
   Args:
       name: Name of the gold standard.
       segmentation_node: Current segmentation node.
       volume_node: Reference volume node.
   
   Returns:
       The computed statistics dictionary.

.. py:function:: delete_gold()

   Delete a gold standard.
   
   Args:
       name: Name of the gold standard to delete.

.. py:function:: save_reference_screenshot()

   Save a reference screenshot for a gold standard.
   
   Args:
       name: Name of the gold standard.
       screenshot_path: Path to the screenshot file.
       description: Description of what the screenshot shows.
   
   Returns:
       Path to the saved screenshot.

.. py:function:: compare_statistics()

   Compare trial statistics against gold standard.
   
   Args:
       gold_stats: Statistics from gold standard metadata.
       trial_stats: Statistics computed for a trial.
   
   Returns:
       Comparison metrics.

.. py:function:: format_statistics()

   Format statistics as human-readable string.
   
   Args:
       stats: Statistics dictionary.
   
   Returns:
       Formatted multi-line string.

.. py:function:: format_comparison()

   Format comparison as human-readable string.
   
   Args:
       comparison: Comparison dictionary from compare_statistics().
   
   Returns:
       Formatted multi-line string.