Dev

[alexanderjaus]

Summary

• GPU-accelerated Voronoi preprocessing and CC-Dice added, with tooling to validate CPU/GPU parity across large datasets.
• Documentation updated with GPU requirements, installation, usage, and parity notes.
• No breaking changes; CPU remains default and fully supported.

What’s Included

• New modules:
  • CCMetrics: CC_base_gpu.py, space_separation_on_gpu.py (CuPy + CUDA 12.x).
• CLI and tools:
  • cc-metrics-gpu.py: runs CC-metrics with GPU + CPU side-by-side (clearly labeled).
  • compare_ccdice_cpu_gpu.py: iterates volumes, computes CPU/GPU CC‑Dice, aggregates, and logs mismatches.
  • analyze_debug_mismatches.py: inspects saved Voronoi maps to localize discrepancies.
• Tests:
  • GPU parity tests (single and multi-case) with skip when CUDA/CuPy unavailable.
• Packaging:
  • Extras: gpu/all including cupy-cuda12x in pyproject.toml.
• Docs:
  • README adds GPU install, requirements, example usage, and parity discussion.

Why This Change

• Speed up large-scale evaluations with GPU-accelerated Voronoi while maintaining CPU correctness.
• Provide transparent, automated validation of CPU↔GPU consistency.

Behavior & Compatibility

• Default path: CPU metrics; GPU is optional.
• Parity: Minor numerical differences can occur due to EDT tie-breaking on background voxels (SciPy vs CuPy). In our checks on 441 volumes:
  • Patient-wise mean diff ~1e-5; per-component mean diff ~5e-5.
  • Rare worst-case patient diff ~3.5e-3.
• For exact reproducibility: prefer CPU path or force a shared Voronoi backend.

Performance Notes

• GPU path uses single-EDT Voronoi on GPU; reduces wall time on large volumes.
• Caching remains off by default; fast path recommended.

Install & Usage

• Requirements: NVIDIA GPU, CUDA 12.x, CUDA-enabled PyTorch, matching CuPy.
• Install: pip install "CCMetrics[gpu]" or pip install -e .[gpu].
• Use:
  • Python: from CCMetrics import CCDiceMetricGPU
  • CLI: python cc-metrics-gpu.py <gt_dir> <pred_dir> --metrics dice

Review Guidance

• Verify space_separation_on_gpu.py logic parity with CPU space_separation.py.
• Confirm dtype/device conversions in CC_base_gpu.py are consistent and zero‑copy where intended.
• Check that cc-metrics-gpu.py outputs are clearly separated (dice_cpu vs dice_gpu) and shape checks prevent skew.
• Skips and tolerance in tests reflect intended parity guarantees.

Checklist

• CPU/GPU unit tests pass (GPU tests skip when unavailable)
• README updated with GPU section
• Pre-commit checks (Black/isort) pass
• No API breaks; CPU path unchanged