feat: Add CD/DVD DICOMDIR support for German MRI CDs

[Liohtml]

Problem

In Germany (and many other countries), MRI results are almost always delivered on CD/DVD. These discs follow the DICOM standard structure:

CD-ROM (D:\)
├── DICOMDIR              ← Standard index file (lists all studies/series/images)
├── DICOM/
│   ├── IM000001.dcm
│   ├── IM000002.dcm
│   └── ...
└── viewer.exe            ← Bundled Windows-only viewer (usually useless)

Currently, LocalProvider scans directories recursively for DICOM files, which works but:

1. Misses the DICOMDIR - a structured index that gives instant access to the patient/study/series hierarchy
2. Is slow on CDs - optical drives are slow; scanning hundreds of files takes minutes
3. Doesn't detect CD drives - users have to manually find the mount path

Proposed Solution

Enhance LocalProvider (not a new provider) to auto-detect and parse DICOMDIR files.

Implementation Plan

1. Add DICOMDIR detection to LocalProvider._load_directory()

# src/medcheck/providers/local.py

def _load_directory(self, root: Path) -> list[DicomSeries]:
    # Check for DICOMDIR first (standard on CDs)
    dicomdir_path = root / "DICOMDIR"
    if dicomdir_path.exists():
        return self._load_from_dicomdir(dicomdir_path)
    
    # Fallback: recursive scan (existing behavior)
    return self._scan_directory(root)

2. Implement DICOMDIR parsing

def _load_from_dicomdir(self, dicomdir_path: Path) -> list[DicomSeries]:
    """Load DICOM data using DICOMDIR index (standard on CDs)."""
    from rich.console import Console
    console = Console()
    console.print("[blue]DICOMDIR found - using structured index[/blue]")
    
    ds = pydicom.dcmread(str(dicomdir_path))
    root = dicomdir_path.parent
    
    series_map: dict[str, list[Any]] = {}
    series_meta: dict[str, dict[str, Any]] = {}
    
    for patient_record in ds.patient_records:
        for study_record in patient_record.children:
            for series_record in study_record.children:
                series_desc = getattr(series_record, "SeriesDescription", 
                                      f"series_{getattr(series_record, 'SeriesNumber', 0)}")
                series_num = getattr(series_record, "SeriesNumber", 0)
                
                for image_record in series_record.children:
                    # DICOMDIR stores relative file paths
                    file_parts = image_record.ReferencedFileID
                    if isinstance(file_parts, str):
                        file_parts = [file_parts]
                    
                    dcm_path = root / Path(*file_parts)
                    if dcm_path.exists():
                        try:
                            dcm = pydicom.dcmread(str(dcm_path), force=True)
                            if hasattr(dcm, "PixelData"):
                                if series_desc not in series_map:
                                    series_map[series_desc] = []
                                    series_meta[series_desc] = {
                                        "series_number": series_num,
                                        "modality": getattr(series_record, "Modality", ""),
                                    }
                                series_map[series_desc].append(dcm)
                        except Exception:
                            continue
    
    result: list[DicomSeries] = []
    for desc, datasets in series_map.items():
        meta = series_meta.get(desc, {})
        result.append(DicomSeries(
            description=desc,
            series_number=meta.get("series_number", 0),
            modality=meta.get("modality", ""),
            slices=datasets,
            metadata=meta,
        ))
    
    console.print(f"[green]Loaded {len(result)} series from DICOMDIR[/green]")
    return sorted(result, key=lambda s: s.series_number)

3. Rename existing scan to _scan_directory()

def _scan_directory(self, root: Path) -> list[DicomSeries]:
    """Fallback: recursively scan directory for DICOM files."""
    # ... existing _load_directory code ...

4. Add tests

# tests/unit/test_providers/test_local_dicomdir.py

def test_load_from_dicomdir(tmp_path: Path):
    """Test that DICOMDIR is auto-detected and parsed."""
    # Create a minimal DICOMDIR structure
    dicom_dir = tmp_path / "DICOM"
    dicom_dir.mkdir()
    
    # Create test DICOM files
    _create_test_dicom(dicom_dir / "IM000001.dcm", "pd_sag", 1)
    _create_test_dicom(dicom_dir / "IM000002.dcm", "pd_sag", 1)
    
    # Create DICOMDIR (pydicom can generate these)
    # ... or use a fixture file
    
    provider = LocalProvider()
    result = provider.fetch(str(tmp_path), {})
    assert len(result) >= 1


def test_fallback_without_dicomdir(tmp_path: Path):
    """Test that directories without DICOMDIR still work (existing behavior)."""
    _create_test_dicom(tmp_path / "slice.dcm", "test", 1)
    provider = LocalProvider()
    result = provider.fetch(str(tmp_path), {})
    assert len(result) >= 1


def test_cd_drive_detection():
    """Test CD/DVD drive path detection (platform-specific)."""
    # Windows: D:\, E:\
    # Linux: /media/cdrom, /mnt/cdrom
    # This test verifies the detection logic, not actual hardware
    pass

Files to modify

File	Change
src/medcheck/providers/local.py	Add _load_from_dicomdir(), refactor _load_directory()
tests/unit/test_providers/test_local.py	Add DICOMDIR tests
docs/quickstart.md	Add "From CD" usage example
README.md	Update data sources table

CLI usage after implementation

# Point directly at CD drive
medcheck analyze --source D:\

# Or mount point on Linux
medcheck analyze --source /media/cdrom

# Also works with copied CD contents
medcheck analyze --source ./copied-from-cd/

Nice-to-have (follow-up issues)

• Auto-detect CD/DVD drives on the system
• "Copy to local" option for faster re-analysis (--copy-local ./cache/)
• Progress bar when reading from slow optical drives
• Multi-study picker if CD contains multiple examinations
• Web UI: "Read from CD" button

Context

This is a high-value feature for the German/European market where CD delivery is standard practice. Many patients receive CDs but have no way to analyze them beyond the bundled Windows viewer.

References

• pydicom DICOMDIR tutorial
• DICOM Part 10: Media Storage
• pydicom.filereader.dcmread() natively supports DICOMDIR files

[Liohtml]

Assessment

Value: High. German MRI CDs are the dominant distribution method in the German healthcare system — patients routinely bring physical CDs to appointments. Without DICOMDIR support, LocalProvider does a brute-force recursive scan even on CDs with a structured index, which is slow and misses the explicit study/series hierarchy.

Complexity: Medium. pydicom has native DICOMDIR support. The architecture is clean for this addition — it's a new code path inside LocalProvider, no structural changes needed.

Implementation assessment: The approach described in the issue (checking for DICOMDIR file at root, using DicomDir to extract ReferencedFileID paths) is correct. A few things to nail:

1. ReferencedFileID is tricky. Depending on pydicom version and how the CD was mastered, it can be a string or a pydicom.sequence.Sequence. Some German CD-writing software uses backslash separators (Windows paths). Test with:

# Handle both string and sequence ReferencedFileID
ref = file_record.ReferencedFileID
if isinstance(ref, str):
    parts = ref.replace("\\", "/").split("/")
else:
    parts = list(ref)  # sequence of strings
file_path = cd_root / Path(*parts)

2. DICOMDIR entries include non-IMAGE records (patient, study, series, image levels). Only descend to DirectoryRecordSequence entries with DirectoryRecordType == "IMAGE".

3. Fallback to recursive scan if the DICOMDIR file exists but is malformed or pydicom can't parse it — don't fail hard on a corrupt DICOMDIR.

My suggested implementation sketch:

def _load_directory(self, path: Path) -> list[Path]:
    dicomdir = path / "DICOMDIR"
    if dicomdir.exists():
        try:
            return self._load_from_dicomdir(path, dicomdir)
        except Exception as e:
            logger.warning("DICOMDIR parse failed (%s), falling back to scan", e)
    return self._scan_directory(path)

def _load_from_dicomdir(self, root: Path, dicomdir_path: Path) -> list[Path]:
    ds = pydicom.dcmread(str(dicomdir_path))
    paths = []
    for record in ds.DirectoryRecordSequence:
        if getattr(record, "DirectoryRecordType", "") == "IMAGE":
            ref = record.ReferencedFileID
            parts = ref if not isinstance(ref, str) else ref.replace("\\", "/").split("/")
            paths.append(root / Path(*parts))
    return paths

Tests needed: Add a fixture that creates a minimal in-memory DICOMDIR structure (pydicom supports constructing one programmatically), and test the fallback path with a malformed DICOMDIR.

Effort: 2-3 hours including tests.

[Liohtml]

Assessment

Value: High — this is a real-world blocker for a significant portion of the target audience. In Germany (the primary market, given this project), virtually all outpatient MRI results arrive on CD. Without DICOMDIR support, the tool can't process the most common delivery format.

Complexity: Moderate — pydicom already handles DICOMDIR. The work is integrating it cleanly into the provider system.

Fits architecture: Yes. Adding a DicomdirProvider (or extending LocalProvider) is exactly how the plugin/provider pattern is designed to be used.

My take

This should be a high priority, not a "good first issue." It's a fundamental capability gap. The current LocalProvider expects either a flat folder of .dcm files or a ZIP — real-world CD images don't look like that. They have a DICOMDIR index at the root, and the actual DICOM files are at paths like DICOM/ST000001/SE000001/IM000001.

Implementation approach

pydicom's DicomDir class parses the DICOMDIR file directly. The integration is straighforward:

# src/medcheck/providers/dicomdir.py
import pydicom
from pathlib import Path

class DicomdirProvider(DataProvider):
    name = "dicomdir"

    def detect(self, target: str) -> bool:
        p = Path(target)
        return (p / "DICOMDIR").exists() or p.name == "DICOMDIR"

    def fetch(self, target: str, credentials: dict) -> list[DicomSeries]:
        p = Path(target)
        dicomdir_path = p / "DICOMDIR" if p.is_dir() else p
        root = dicomdir_path.parent

        ds = pydicom.dcmread(str(dicomdir_path))
        series_map: dict[str, list] = {}

        for patient in ds.patient_records:
            for study in patient.children:
                for series in study.children:
                    series_id = series.SeriesInstanceUID
                    series_map[series_id] = []
                    for image in series.children:
                        # ReferencedFileID may be a list or backslash-joined path
                        ref = image.ReferencedFileID
                        if isinstance(ref, list):
                            rel = Path(*ref)
                        else:
                            rel = Path(*ref.split("\\"))
                        dcm = pydicom.dcmread(str(root / rel))
                        series_map[series_id].append(dcm)

        return [DicomSeries(...) for ...]

Then register it in IngestStep.run() alongside LocalProvider and EasyRadiologyProvider, and add a detect() check to ProviderRegistry.detect().

Edge cases to watch:

• Windows CD images use backslash separators in ReferencedFileID (cross-platform path joining needed)
• Some CDs have a mangled or missing DICOMDIR — fall back to recursive .dcm scan
• Compressed DICOM transfer syntaxes (JPEG 2000, RLE) need pydicom with the right decoder

Effort estimate

2-4 hours for a solid implementation with tests. A minimal proof-of-concept is 1 hour.

[Liohtml]

⚠️ API update for implementers: use pydicom.fileset.FileSet, not DicomDir

Heads-up before anyone starts on this: the approach in the earlier comments
(pydicom.dcmread(...) → DicomDir, ds.patient_records, read_dicomdir()) uses
the legacy DICOMDIR API that was removed in pydicom 3.0. This repo already
depends on pydicom>=3.0.0 (see pyproject.toml), so that code path would raise
on import/attribute access. The modern, supported equivalent is the FileSet
API.

Correct current approach:

from pydicom import dcmread
from pydicom.fileset import FileSet

def _load_from_dicomdir(root: Path) -> list:
    # The DICOMDIR file is itself a normal DICOM dataset.
    fs = FileSet(dcmread(str(root / "DICOMDIR")))
    datasets = []
    for instance in fs:                 # iterates image instances; or fs.find(...)
        datasets.append(instance.load())  # returns a FileDataset
    return datasets

Notes that still apply (and are worth keeping from the earlier write-ups):

• FileSet resolves file references relative to the DICOMDIR's own location, so
  the manual ReferencedFileID backslash-splitting / Path(*parts) juggling is no
  longer needed — instance.load() handles path resolution across OSes. You only
  need find()/find_values() to browse the index cheaply (e.g.
  fs.find_values("SeriesDescription")) before loading pixels.
• Fallback to a recursive scan if the DICOMDIR is missing/corrupt (German
  clinic CDs do occasionally ship a broken index) — FileSet(...) will raise on an
  invalid DICOMDIR, so wrap it and fall back to the existing _scan_directory().
• Compressed transfer syntaxes (JPEG 2000 / JPEG-LS / RLE) are common on CDs;
  reading pixel_array needs a decoder — install pylibjpeg (with its plugins)
  and/or python-gdcm. Worth adding as an optional dicom/cd extra.

Implementation-wise this slots cleanly into LocalProvider (prefer DICOMDIR, fall
back to recursive scan) rather than a separate provider, since detection is just
"is there a DICOMDIR at the target root?".

Ref: pydicom FileSet tutorial — https://pydicom.github.io/pydicom/stable/tutorials/filesets.html ; image-data handlers — https://pydicom.github.io/pydicom/stable/guides/user/image_data_handlers.html

---

Generated by Claude Code