Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,46 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/BS.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0000.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0001.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0002.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0003.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0004.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0005.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0006.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0007.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0008.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0009.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0010.dcm filter=lfs diff=lfs merge=lfs -text
+data/bifurcation/FILE0011.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0000.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0001.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0002.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0003.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0004.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0005.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0006.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0007.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0008.dcm filter=lfs diff=lfs merge=lfs -text
+data/paul/FILE0009.dcm filter=lfs diff=lfs merge=lfs -text
+docs/memo_assets/lumen_finetune_dynamics.png filter=lfs diff=lfs merge=lfs -text
+docs/memo_assets/multitask_pipeline_diagram.png filter=lfs diff=lfs merge=lfs -text
+docs/memo_assets/multitask_training_dynamics.png filter=lfs diff=lfs merge=lfs -text
+docs/memo_assets/standalone_reliability_diagram.png filter=lfs diff=lfs merge=lfs -text
+docs/memo_assets/standalone_threshold_sweep.png filter=lfs diff=lfs merge=lfs -text
+docs/multitask_finetuning_comprehensive_memo.pdf filter=lfs diff=lfs merge=lfs -text
+models/deepIVUS/variables/variables.data-00001-of-00002 filter=lfs diff=lfs merge=lfs -text
+models/multitask/checkpoints/ckpt-13.data-00000-of-00001 filter=lfs diff=lfs merge=lfs -text
+models/multitask/lumen_multitask_base/variables/variables.data-00000-of-00001 filter=lfs diff=lfs merge=lfs -text
+models/standalone/bifurcation/best_bifurcation_classifier.keras filter=lfs diff=lfs merge=lfs -text
+models/standalone/lumen/variables/variables.data-00000-of-00001 filter=lfs diff=lfs merge=lfs -text
+output/20260223_232201/FILE0005_overlay.mp4 filter=lfs diff=lfs merge=lfs -text
+output/20260223_232201/FILE0005_overlay_bifurcation.mp4 filter=lfs diff=lfs merge=lfs -text
+output/augment_preview/augment_preview_4x4.png filter=lfs diff=lfs merge=lfs -text
+output/augment_preview/frame_bank_FILE0001_frame0_aug4x4.png filter=lfs diff=lfs merge=lfs -text
+output/data_scale_vs_accuracy_projected_points.png filter=lfs diff=lfs merge=lfs -text
+output/roboflow_inference/roboflow_4x4_lumen_bifurcation_grid.png filter=lfs diff=lfs merge=lfs -text
+output/tensorboard/multitask_20260220_044431/augment_preview_4x4.png filter=lfs diff=lfs merge=lfs -text
+output/three_stage_bifurcation_frame_FILE00005.png filter=lfs diff=lfs merge=lfs -text
+output/training_outputs/single_inference/FILE0005_overlay.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+build
+DeepIVUS.egg-info

DeepIVUS.py

@@ -0,0 +1,11 @@
+"""Compatibility entrypoint for the DeepIVUS CLI.
+
+Implementation has been moved into the ``deepivus`` package to keep modules
+small and easier to maintain.
+"""
+
+from deepivus.cli import cli
+
+
+if __name__ == "__main__":
+    cli()

README.md

@@ -0,0 +1,138 @@
+# IVUS-Segmentation
+
+DeepIVUS pipeline for lumen segmentation and bifurcation frame classification on IVUS DICOMs.
+
+## What This Repo Contains
+
+- Runtime package: `deepivus/`
+  - CLI entrypoints and pipeline orchestration
+  - Lumen segmentation inference
+  - Bifurcation classifier inference
+  - Video/JSON/XML export utilities
+- Data and annotations:
+  - `data/`: source DICOM folders (`data/bifurcation`, `data/paul`)
+  - `evals/frame_bank_merged/`: canonical annotation bank
+  - `evals/splits/ivus_split_merged_600.json`: canonical train/val/test split
+- Models:
+  - `models/standalone/lumen/`: standalone lumen TF SavedModel
+  - `models/standalone/bifurcation/best_bifurcation_classifier.keras`: standalone bifurcation classifier
+  - `models/standalone/bifurcation/threshold.json`: selected inference threshold (from validation sweep)
+- Training and evaluation scripts:
+  - `scripts/finetune/bifurcation/`
+  - `scripts/finetune/lumen/`
+  - shared helpers: `scripts/finetune/shared/common.py`
+  - data tooling: `scripts/data/frame_bank.py`
+
+## Main Runtime Workflow
+
+### 1) Segment a DICOM and classify branching
+
+```bash
+python DeepIVUS.py segment data/paul/FILE00005.dcm
+```
+
+Outputs are written under `output/<timestamp>/` and include:
+
+- contours XML and JSONL
+- top-confidence JSONL
+- lumen overlay video
+- bifurcation predictions JSONL + summary JSON
+- overlay video with branch/non-branch flag
+
+Notes:
+
+- `--bifurcation-threshold` is optional.
+- If omitted, threshold is loaded from `threshold.json` beside the selected bifurcation model.
+
+### 2) Edit contour annotations in GUI
+
+```bash
+python DeepIVUS.py edit-annotations data/paul/FILE00005.dcm
+```
+
+## Bifurcation Model Workflow
+
+### 1) Sample new frames for manual labeling
+
+```bash
+python -u scripts/finetune/bifurcation/sample_new_bifurcation_frames.py
+```
+
+### 2) Label sampled frames in GUI
+
+```bash
+python -u scripts/finetune/bifurcation/annotate_bifurcation_samples.py
+```
+
+### 3) Merge labels into canonical frame bank
+
+```bash
+python -u scripts/finetune/bifurcation/merge_bifurcation_annotations.py
+```
+
+### 4) Create/update canonical split
+
+```bash
+python -u scripts/finetune/bifurcation/create_bifurcation_splits.py
+```
+
+### 5) Train bifurcation classifier
+
+```bash
+python -u scripts/finetune/bifurcation/train_bifurcation_classifier.py
+```
+
+### 6) Evaluate on test and select threshold from validation
+
+```bash
+python -u scripts/finetune/bifurcation/run_bifurcation_test_inference.py
+```
+
+This writes test metrics and persists selected threshold to:
+
+- `threshold.json` beside the evaluated classifier model file.
+
+## Lumen Model Workflow
+
+### 1) Identify lumen class index in SavedModel logits
+
+```bash
+python -u scripts/finetune/lumen/identify_lumen_class.py
+```
+
+### 2) Fine-tune lumen model
+
+```bash
+python -u scripts/finetune/lumen/finetune_lumen_from_saved_model.py \
+  --output-model-dir models/standalone/lumen
+```
+
+### 3) Evaluate lumen model on test split
+
+```bash
+python -u scripts/finetune/lumen/run_test_inference.py \
+  --model-dir models/standalone/lumen
+```
+
+### 4) Run single-DICOM lumen + bifurcation overlay inference
+
+```bash
+python -u scripts/finetune/lumen/run_single_dicom_inference.py \
+  --dicom-path data/paul/FILE00005.dcm
+```
+
+## Repository Structure
+
+- `DeepIVUS.py`: top-level CLI launcher
+- `deepivus/`: runtime package
+- `models/`: runtime models and threshold
+- `evals/`: canonical annotation bank and split
+- `scripts/`: training/eval/data utilities
+- `output/`: generated artifacts (runs, metrics, videos)
+
+## Environment
+
+- Python project config: `pyproject.toml`
+- Conda env file: `environment.yml`
+
+Install dependencies with your preferred toolchain (`poetry`, `pip`, or `conda`) using those files.

data/bifurcation/BS.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9344074612f7936d84732d8e831bc37c6e68ce200592a45028b6765931659d11
+size 32770958

data/bifurcation/FILE0000.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ff3a63757f3574f8aa138e6ddf0b69c3d0bd6b7acade47636b3d49ee224f9584
+size 30254548

data/bifurcation/FILE0001.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3860565d1bd2daeca152dd740e492815ba87bfd6f18a521a3e2f4844be2d4212
+size 253280

data/bifurcation/FILE0002.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f426d507eda872079a3bc6c3ff324b6ffd134b171aa3b4027155fb4bd4c763bf
+size 253278

data/bifurcation/FILE0003.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f714c5b35ca43fb06daecb5c3247ed6c8068da38946890a92fad97382677123c
+size 34254644

data/bifurcation/FILE0004.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7494a4ae42c498ac7ade0bfc021042fbedbaf54c46f5885c32e24a4478fb0c31
+size 28254496

data/bifurcation/FILE0005.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:01107332ec0e8f5e9ecac762e7f96917b52b2fc64b82acbd1f280b86db060e82
+size 21754318

data/bifurcation/FILE0006.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fbaf49c4ef9d64992f656b14dba55b088b14a05c76d0cd56543b496934b57217
+size 108756594

data/bifurcation/FILE0007.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59fbe148fab19df26bb8d718d93901a79ac894f1e08d77db7185341820b07110
+size 16004168

data/bifurcation/FILE0008.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a2f110098e932e85e28e3257c77633bd560f3cab30f46b2803f0d40e04ab3a72
+size 71255616

data/bifurcation/FILE0009.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f5e4fe16bbbd1defa4e88e739a325be632d460818a05b5d3a9853ad67d686035
+size 13004092

data/bifurcation/FILE0010.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2f608ec149cea275e98122d5b7795f9b00e492081c5971217f2eb9ad02275c8c
+size 58255278

data/bifurcation/FILE0011.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d7dff95c57f6ab3ee7b0058226b71f9bc74bc57aff5f868826adfe215a565c7c
+size 35004668

data/paul/FILE0000.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a1f11f0dfea1ef086da41d1386849761513c96393ab8b72c75be471f7887b48
+size 30566174

data/paul/FILE0001.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fae476f3c82dbf9b241807715d20f4dc1e625268304dca405297cf6d3afe1416
+size 9167550

data/paul/FILE0002.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd67e698ffdad8756801285a4c5a3cb10afa711b1b53a665c069c5d2c8e797f4
+size 10649688

data/paul/FILE0003.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ca807cb0b4d65dedf5d426103d9e478a82b96401931d517d306ee3a4181435e0
+size 11845072

data/paul/FILE0004.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f2b0c0be3fb1ff6920f59f31c25adbb239efbf91f221c383f7d13cf805895337
+size 19811870

data/paul/FILE0005.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:13fa61c40771c6867cb6fa2e4889e0044f99357448a682ff44483f338622b2b3
+size 28187200

data/paul/FILE0006.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:349a5c710fcf9b281e98df610c2231630b63260e1a81af0dbcae641796fad827
+size 34090280

data/paul/FILE0007.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:029d28d17cd97a38d63a17ef6cb7c9b1bdcfa1e2653b5cc31a0ba0601017d805
+size 25494378

data/paul/FILE0008.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3cbe7a3a036addc6be29435b0d2364dfa7b7a16b5107a8ec85b2edf78af65cbe
+size 23930322

data/paul/FILE0009.dcm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84db9e7f2df31266b9b46c03c95746aadf4086ecb8df34a4d8f42c85bc63ec1a
+size 28718644

deepivus/__init__.py

@@ -0,0 +1,5 @@
+"""DeepIVUS modular package."""
+
+__all__ = [
+    "cli",
+]

deepivus/analysis/__init__.py

@@ -0,0 +1,13 @@
+"""Analysis subpackage."""
+
+from .scoring import (
+    compute_oblongness_scores,
+    detect_online_bifurcation_signal,
+    detect_sustained_bifurcation_signal,
+)
+
+__all__ = [
+    "compute_oblongness_scores",
+    "detect_sustained_bifurcation_signal",
+    "detect_online_bifurcation_signal",
+]

deepivus/analysis/scoring.py

@@ -0,0 +1,162 @@
+"""Scoring and event-detection utilities for lumen shape stability."""
+
+from typing import Tuple
+
+import numpy as np
+
+
+def compute_oblongness_scores(lumen_masks: np.ndarray) -> np.ndarray:
+    """Compute per-frame oblongness score in [0, 1] from binary lumen masks."""
+    scores = np.zeros((lumen_masks.shape[0],), dtype=np.float32)
+    for idx in range(lumen_masks.shape[0]):
+        ys, xs = np.where(lumen_masks[idx] > 0)
+        if ys.size < 20:
+            scores[idx] = np.float32(0.0)
+            continue
+
+        x = xs.astype(np.float32)
+        y = ys.astype(np.float32)
+        x -= float(np.mean(x))
+        y -= float(np.mean(y))
+        cov = np.cov(np.vstack((x, y)))
+        eigvals = np.linalg.eigvalsh(cov)
+        eigvals = np.maximum(eigvals, 1e-6)
+        axis_ratio = float(np.sqrt(eigvals[-1] / eigvals[0]))
+        scores[idx] = np.float32(np.clip((axis_ratio - 1.0) / (axis_ratio + 1.0), 0.0, 1.0))
+    return scores
+
+
+def moving_average(x: np.ndarray, window: int) -> np.ndarray:
+    """Centered moving-average smoothing."""
+    if window <= 1:
+        return x.copy()
+    kernel = np.ones((window,), dtype=np.float32) / float(window)
+    pad = window // 2
+    x_pad = np.pad(x.astype(np.float32), (pad, pad), mode="edge")
+    return np.convolve(x_pad, kernel, mode="valid")
+
+
+def causal_moving_average(x: np.ndarray, window: int) -> np.ndarray:
+    """Past-only moving average for online detection."""
+    x = x.astype(np.float32)
+    if window <= 1:
+        return x.copy()
+    out = np.zeros_like(x, dtype=np.float32)
+    csum = np.cumsum(x, dtype=np.float32)
+    for idx in range(x.shape[0]):
+        start = max(0, idx - window + 1)
+        total = csum[idx] - (csum[start - 1] if start > 0 else 0.0)
+        out[idx] = total / float(idx - start + 1)
+    return out
+
+
+def keep_sustained_runs(flags: np.ndarray, min_run: int) -> np.ndarray:
+    """Keep only True runs with length >= ``min_run``."""
+    kept = np.zeros_like(flags, dtype=bool)
+    start = None
+    for idx, val in enumerate(flags):
+        if val and start is None:
+            start = idx
+        if (not val or idx == len(flags) - 1) and start is not None:
+            end = idx if not val else idx + 1
+            if (end - start) >= min_run:
+                kept[start:end] = True
+            start = None
+    return kept
+
+
+def detect_sustained_bifurcation_signal(oblong_scores: np.ndarray, fps: float) -> Tuple[np.ndarray, np.ndarray]:
+    """Detect sustained high-oblongness intervals and return (smoothed_scores, flags)."""
+    smooth_window = max(5, int(round(max(fps, 1.0) * 0.5)))
+    if smooth_window % 2 == 0:
+        smooth_window += 1
+    smoothed = moving_average(oblong_scores, smooth_window)
+
+    median = float(np.median(smoothed))
+    mad = float(np.median(np.abs(smoothed - median)))
+    robust_scale = max(1e-6, 1.4826 * mad)
+    robust_z = (smoothed - median) / robust_scale
+
+    candidate = (smoothed > 0.35) & (robust_z > 2.5)
+    min_run = max(5, int(round(max(fps, 1.0) * 0.4)))
+    sustained = keep_sustained_runs(candidate.astype(bool), min_run=min_run)
+    return smoothed.astype(np.float32), sustained
+
+
+def detect_online_bifurcation_signal(oblong_scores: np.ndarray, fps: float) -> Tuple[np.ndarray, np.ndarray]:
+    """Online bifurcation detector using only past information.
+
+    Algorithm:
+    - Causal smoothing (past-only moving average).
+    - Running robust baseline from a fixed history window.
+    - Incremental sustained-run confirmation (no future lookahead).
+    """
+    x = np.asarray(oblong_scores, dtype=np.float32)
+    if x.size == 0:
+        return x.copy(), np.zeros((0,), dtype=bool)
+
+    smooth_window = max(5, int(round(max(fps, 1.0) * 0.35)))
+    smoothed = causal_moving_average(x, smooth_window)
+
+    baseline_window = max(24, int(round(max(fps, 1.0) * 8.0)))
+    warmup = max(12, int(round(max(fps, 1.0) * 1.0)))
+    min_run = max(6, int(round(max(fps, 1.0) * 0.4)))
+
+    sustained = np.zeros((x.shape[0],), dtype=bool)
+    run_len = 0
+    misses_left = 0
+    active = False
+
+    # Causal slope signal helps detect onset before level becomes very high.
+    slope = np.zeros_like(smoothed, dtype=np.float32)
+    slope[1:] = smoothed[1:] - smoothed[:-1]
+
+    for idx in range(x.shape[0]):
+        hist_start = max(0, idx - baseline_window)
+        history = smoothed[hist_start:idx]  # past only
+        if history.size < warmup:
+            run_len = 0
+            misses_left = 0
+            continue
+
+        median = float(np.median(history))
+        mad = float(np.median(np.abs(history - median)))
+        robust_scale = max(1e-6, 1.4826 * mad)
+        robust_z = (float(smoothed[idx]) - median) / robust_scale
+
+        q90 = float(np.quantile(history, 0.9))
+        dyn_level = max(0.31, q90 + 0.05)
+
+        slope_hist = slope[hist_start:idx]
+        slope_median = float(np.median(slope_hist))
+        slope_mad = float(np.median(np.abs(slope_hist - slope_median)))
+        slope_scale = max(1e-6, 1.4826 * slope_mad)
+        slope_z = (float(slope[idx]) - slope_median) / slope_scale
+
+        level = float(smoothed[idx])
+        enter_candidate = (
+            (level >= dyn_level and robust_z > 1.95)
+            or (level >= 0.29 and robust_z > 1.3 and slope_z > 2.6)
+        )
+        continue_candidate = (
+            (level >= max(0.27, dyn_level - 0.02) and robust_z > 1.2)
+            or (level >= 0.25 and robust_z > 1.0 and slope_z > 1.8)
+        )
+        is_candidate = continue_candidate if active else enter_candidate
+
+        if is_candidate:
+            run_len += 1
+            misses_left = 1
+            active = True
+            if run_len >= min_run:
+                # Confirm sustained event using only history seen so far.
+                sustained[idx - min_run + 1 : idx + 1] = True
+        else:
+            # Allow a single miss so short dips do not break a sustained run.
+            if misses_left > 0 and run_len > 0:
+                misses_left -= 1
+            else:
+                run_len = 0
+                active = False
+
+    return smoothed.astype(np.float32), sustained

deepivus/cli.py

@@ -0,0 +1,138 @@
+"""CLI entrypoints for DeepIVUS."""
+
+import datetime
+import os
+from typing import Optional
+
+import click
+from deepivus.config import resolve_bifurcation_threshold
+
+
+@click.group()
+def cli() -> None:
+    """DeepIVUS CLI."""
+
+
+@cli.command("segment")
+@click.argument("dicom_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--output-prefix",
+    "-o",
+    default=None,
+    type=str,
+    help="Output path prefix (without extension). Defaults to output/<timestamp>/<input filename>.",
+)
+@click.option(
+    "--fps",
+    default=None,
+    type=float,
+    help="Overlay video FPS. Defaults to DICOM CineRate or 30.",
+)
+@click.option(
+    "--bifurcation-threshold",
+    default=None,
+    show_default=False,
+    type=click.FloatRange(min=0.0, max=1.0),
+    help="Threshold for bifurcation classifier labels. Defaults to threshold.json beside the selected bifurcation model.",
+)
+@click.option(
+    "--framewise/--no-framewise",
+    default=False,
+    show_default=True,
+    help="Run inference frame-by-frame (batch_size=1) to simulate realtime processing.",
+)
+def segment_cmd(
+    dicom_path: str,
+    output_prefix: Optional[str],
+    fps: Optional[float],
+    bifurcation_threshold: Optional[float],
+    framewise: bool,
+) -> None:
+    """Segment lumen and classify bifurcation for all frames."""
+    from .pipeline import segment_and_export
+
+    if output_prefix is None:
+        stem = os.path.splitext(os.path.basename(dicom_path))[0]
+        output_root = os.path.join(os.getcwd(), "output")
+        os.makedirs(output_root, exist_ok=True)
+
+        run_folder = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        output_dir = os.path.join(output_root, run_folder)
+        suffix = 1
+        while os.path.exists(output_dir):
+            output_dir = os.path.join(output_root, f"{run_folder}_{suffix}")
+            suffix += 1
+
+        os.makedirs(output_dir, exist_ok=True)
+        output_prefix = os.path.join(output_dir, stem)
+    else:
+        output_dir = os.path.dirname(os.path.abspath(output_prefix))
+        os.makedirs(output_dir, exist_ok=True)
+
+    if bifurcation_threshold is None:
+        bifurcation_threshold = resolve_bifurcation_threshold(default=0.5)
+
+    (
+        xml_path,
+        json_path,
+        top_conf_json_path,
+        video_path,
+        bif_overlay_video_path,
+        bif_json_path,
+        bif_summary_path,
+    ) = segment_and_export(
+        dicom_path,
+        output_prefix,
+        fps,
+        bifurcation_threshold,
+        framewise=framewise,
+    )
+
+    click.echo(f"Contours XML: {xml_path}")
+    click.echo(f"Contours JSONL: {json_path}")
+    click.echo(f"Top confidence JSONL: {top_conf_json_path}")
+    click.echo(f"Overlay video: {video_path}")
+    click.echo(f"Overlay video (with bifurcation flags): {bif_overlay_video_path}")
+    click.echo(f"Bifurcation predictions JSONL: {bif_json_path}")
+    click.echo(f"Bifurcation summary JSON: {bif_summary_path}")
+
+
+@cli.command("edit-annotations")
+@click.argument("dicom_path", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--annotations-path",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False),
+    help=(
+        "Base contour JSONL to edit. "
+        "Defaults to latest output/<timestamp>/<dicom_stem>_contours.jsonl."
+    ),
+)
+@click.option(
+    "--edits-path",
+    default=None,
+    type=click.Path(dir_okay=False),
+    help="Path for edited annotations JSONL. Defaults beside base file as *_edited_annotations.jsonl.",
+)
+@click.option(
+    "--output-root",
+    default="output",
+    show_default=True,
+    type=click.Path(file_okay=False),
+    help="Root folder containing pipeline outputs used for default annotation discovery.",
+)
+def edit_annotations_cmd(
+    dicom_path: str,
+    annotations_path: Optional[str],
+    edits_path: Optional[str],
+    output_root: str,
+) -> None:
+    """Open GUI editor to review and adjust contour coordinates frame-by-frame."""
+    from .gui import launch_annotation_editor
+
+    launch_annotation_editor(
+        dicom_path=dicom_path,
+        annotations_path=annotations_path,
+        edits_path=edits_path,
+        output_root=output_root,
+    )

deepivus/config.py

@@ -0,0 +1,95 @@
+"""Runtime configuration and model path resolution."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+MODELS_DIR = ROOT_DIR / "models"
+STANDALONE_MODELS_DIR = MODELS_DIR / "standalone"
+
+MULTITASK_DIR = MODELS_DIR / "multitask"
+MULTITASK_LUMEN_MODEL_DIR = MULTITASK_DIR / "lumen_multitask_base"
+MULTITASK_BIFURCATION_HEAD_PATH = MULTITASK_DIR / "bifurcation_head.keras"
+
+LUMEN_MODEL_DIR = STANDALONE_MODELS_DIR / "lumen"
+BIFURCATION_MODEL_PATH = STANDALONE_MODELS_DIR / "bifurcation" / "best_bifurcation_classifier.keras"
+BIFURCATION_THRESHOLD_PATH = STANDALONE_MODELS_DIR / "bifurcation" / "threshold.json"
+
+LEGACY_LUMEN_MODEL_DIRS = [
+    MODELS_DIR / "lumen",
+    ROOT_DIR / "model_finetuned_lumen",
+    ROOT_DIR / "model",
+]
+LEGACY_BIFURCATION_MODEL_PATHS = [
+    MODELS_DIR / "bifurcation" / "best_bifurcation_classifier.keras",
+    ROOT_DIR / "output" / "bifurcation_classifier" / "best_bifurcation_classifier.keras",
+]
+LEGACY_BIFURCATION_THRESHOLD_PATHS = [
+    MODELS_DIR / "bifurcation" / "threshold.json",
+]
+
+
+def resolve_lumen_model_dir() -> Path:
+    env_path = os.getenv("DEEPIVUS_LUMEN_MODEL_DIR")
+    if env_path:
+        return Path(env_path)
+    # Prefer multitask lumen base if available.
+    if MULTITASK_LUMEN_MODEL_DIR.exists():
+        return MULTITASK_LUMEN_MODEL_DIR
+    if LUMEN_MODEL_DIR.exists():
+        return LUMEN_MODEL_DIR
+    for path in LEGACY_LUMEN_MODEL_DIRS:
+        if path.exists():
+            return path
+    return LUMEN_MODEL_DIR
+
+
+def resolve_bifurcation_model_path() -> Path:
+    env_path = os.getenv("DEEPIVUS_BIF_MODEL_PATH")
+    if env_path:
+        return Path(env_path)
+    # Prefer multitask bifurcation head if available.
+    if MULTITASK_BIFURCATION_HEAD_PATH.exists():
+        return MULTITASK_BIFURCATION_HEAD_PATH
+    if BIFURCATION_MODEL_PATH.exists():
+        return BIFURCATION_MODEL_PATH
+    for path in LEGACY_BIFURCATION_MODEL_PATHS:
+        if path.exists():
+            return path
+    return BIFURCATION_MODEL_PATH
+
+
+def resolve_bifurcation_threshold_path(model_path: Path | None = None) -> Path:
+    env_path = os.getenv("DEEPIVUS_BIF_THRESHOLD_PATH")
+    if env_path:
+        return Path(env_path)
+    if model_path is None:
+        model_path = resolve_bifurcation_model_path()
+    return Path(model_path).parent / "threshold.json"
+
+
+def resolve_bifurcation_threshold(default: float = 0.5, model_path: Path | None = None) -> float:
+    primary = resolve_bifurcation_threshold_path(model_path=model_path)
+    candidate_paths = [primary, BIFURCATION_THRESHOLD_PATH, *LEGACY_BIFURCATION_THRESHOLD_PATHS]
+    seen: set[Path] = set()
+    for path in candidate_paths:
+        path = Path(path)
+        if path in seen:
+            continue
+        seen.add(path)
+        if not path.exists():
+            continue
+        try:
+            import json
+
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            value = payload.get("selected_threshold", payload.get("threshold", default))
+            value = float(value)
+            if 0.0 <= value <= 1.0:
+                return value
+        except Exception:
+            continue
+    return float(default)

deepivus/gui/__init__.py

@@ -0,0 +1,5 @@
+"""GUI helpers for annotation inspection and editing."""
+
+from .annotation_editor import launch_annotation_editor
+
+__all__ = ["launch_annotation_editor"]

deepivus/gui/annotation_editor.py

@@ -0,0 +1,428 @@
+"""Interactive GUI for editing per-frame IVUS contour annotations."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from glob import glob
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.lines import Line2D
+from matplotlib.widgets import Button, Slider
+
+from ..io.dicom import read_dicom
+
+
+@dataclass
+class FrameState:
+    """In-memory annotation state for one frame."""
+
+    frame: int
+    lumen_x: list[float]
+    lumen_y: list[float]
+    plaque_x: list[float]
+    plaque_y: list[float]
+    lumen_confidence: float | None
+    plaque_confidence: float | None
+    bifurcation: bool = False
+
+
+class AnnotationEditor:
+    """Matplotlib-based editor for contour annotations."""
+
+    def __init__(
+        self,
+        dicom_path: str,
+        annotations_path: str,
+        edits_path: str,
+    ) -> None:
+        self.dicom_path = dicom_path
+        self.annotations_path = annotations_path
+        self.edits_path = edits_path
+
+        _, images = read_dicom(dicom_path)
+        self.images = images
+
+        self.frame_states = self._load_base_annotations(annotations_path)
+        if len(self.frame_states) != images.shape[0]:
+            raise ValueError(
+                "Frame count mismatch between DICOM and annotations: "
+                f"{images.shape[0]} vs {len(self.frame_states)}"
+            )
+
+        self._load_existing_edits(edits_path)
+        self._ensure_edits_file_header()
+
+        self.current_frame = 0
+        self.drag_target: tuple[str, int] | None = None
+        self.drag_threshold_px = 10.0
+        self.frame_dirty = False
+
+        self.fig = None
+        self.ax_image = None
+        self.image_artist = None
+        self.lumen_line: Line2D | None = None
+        self.plaque_line: Line2D | None = None
+        self.lumen_points = None
+        self.plaque_points = None
+
+        self.slider: Slider | None = None
+        self.status_text = None
+        self.is_updating_slider = False
+
+    @staticmethod
+    def _safe_float(value: Any) -> float | None:
+        if value is None:
+            return None
+        try:
+            out = float(value)
+        except (TypeError, ValueError):
+            return None
+        if np.isnan(out):
+            return None
+        return out
+
+    def _load_base_annotations(self, path: str) -> list[FrameState]:
+        states: list[FrameState] = []
+        with open(path, "r", encoding="utf-8") as fp:
+            for raw in fp:
+                line = raw.strip()
+                if not line:
+                    continue
+                rec = json.loads(line)
+                if rec.get("record_type") != "frame":
+                    continue
+                states.append(
+                    FrameState(
+                        frame=int(rec["frame"]),
+                        lumen_x=[float(v) for v in rec.get("lumen", {}).get("x", [])],
+                        lumen_y=[float(v) for v in rec.get("lumen", {}).get("y", [])],
+                        plaque_x=[float(v) for v in rec.get("plaque", {}).get("x", [])],
+                        plaque_y=[float(v) for v in rec.get("plaque", {}).get("y", [])],
+                        lumen_confidence=self._safe_float(rec.get("lumen_confidence")),
+                        plaque_confidence=self._safe_float(rec.get("plaque_confidence")),
+                        bifurcation=bool(rec.get("bifurcation", False)),
+                    )
+                )
+
+        states.sort(key=lambda s: s.frame)
+        expected = list(range(len(states)))
+        actual = [s.frame for s in states]
+        if actual != expected:
+            raise ValueError(
+                "Base annotations must contain contiguous frame records in order "
+                f"(got first frames: {actual[:10]})"
+            )
+        return states
+
+    def _load_existing_edits(self, path: str) -> None:
+        if not os.path.exists(path):
+            return
+
+        latest: dict[int, dict[str, Any]] = {}
+        with open(path, "r", encoding="utf-8") as fp:
+            for raw in fp:
+                line = raw.strip()
+                if not line:
+                    continue
+                rec = json.loads(line)
+                if rec.get("record_type") != "frame_edit":
+                    continue
+                frame_idx = int(rec["frame"])
+                latest[frame_idx] = rec
+
+        for frame_idx, rec in latest.items():
+            if frame_idx < 0 or frame_idx >= len(self.frame_states):
+                continue
+            state = self.frame_states[frame_idx]
+            state.lumen_x = [float(v) for v in rec.get("lumen", {}).get("x", state.lumen_x)]
+            state.lumen_y = [float(v) for v in rec.get("lumen", {}).get("y", state.lumen_y)]
+            state.plaque_x = [float(v) for v in rec.get("plaque", {}).get("x", state.plaque_x)]
+            state.plaque_y = [float(v) for v in rec.get("plaque", {}).get("y", state.plaque_y)]
+            state.bifurcation = bool(rec.get("bifurcation", state.bifurcation))
+
+    def _ensure_edits_file_header(self) -> None:
+        os.makedirs(os.path.dirname(os.path.abspath(self.edits_path)), exist_ok=True)
+        if os.path.exists(self.edits_path):
+            return
+        meta = {
+            "record_type": "meta",
+            "created_at": datetime.now().isoformat(timespec="seconds"),
+            "dicom_path": os.path.abspath(self.dicom_path),
+            "base_annotations_path": os.path.abspath(self.annotations_path),
+            "format": "append_only_frame_edits",
+        }
+        with open(self.edits_path, "w", encoding="utf-8") as fp:
+            fp.write(json.dumps(meta) + "\n")
+
+    def _append_frame_edit(self, frame_idx: int, reason: str) -> None:
+        state = self.frame_states[frame_idx]
+        rec = {
+            "record_type": "frame_edit",
+            "saved_at": datetime.now().isoformat(timespec="seconds"),
+            "reason": reason,
+            "frame": frame_idx,
+            "bifurcation": state.bifurcation,
+            "lumen": {"x": state.lumen_x, "y": state.lumen_y},
+            "plaque": {"x": state.plaque_x, "y": state.plaque_y},
+            "lumen_confidence": state.lumen_confidence,
+            "plaque_confidence": state.plaque_confidence,
+        }
+
+        with open(self.edits_path, "a", encoding="utf-8") as fp:
+            fp.write(json.dumps(rec) + "\n")
+            fp.flush()
+            os.fsync(fp.fileno())
+
+        self.frame_dirty = False
+
+    def _build_ui(self) -> None:
+        self.fig = plt.figure(figsize=(13, 9))
+        self.fig.canvas.manager.set_window_title("DeepIVUS Annotation Editor")
+
+        self.ax_image = self.fig.add_axes([0.05, 0.22, 0.9, 0.74])
+        self.ax_image.set_title("DeepIVUS Annotation Editor", fontsize=14, weight="bold")
+        self.ax_image.set_axis_off()
+
+        slider_ax = self.fig.add_axes([0.12, 0.13, 0.76, 0.035])
+        self.slider = Slider(
+            ax=slider_ax,
+            label="Frame",
+            valmin=0,
+            valmax=len(self.frame_states) - 1,
+            valinit=0,
+            valstep=1,
+            color="#1f77b4",
+        )
+
+        prev_ax = self.fig.add_axes([0.12, 0.05, 0.1, 0.055])
+        next_ax = self.fig.add_axes([0.24, 0.05, 0.1, 0.055])
+        save_ax = self.fig.add_axes([0.42, 0.05, 0.14, 0.055])
+        bif_ax = self.fig.add_axes([0.72, 0.05, 0.16, 0.055])
+
+        self.prev_button = Button(prev_ax, "Prev Frame", color="#E0E0E0", hovercolor="#D0D0D0")
+        self.next_button = Button(next_ax, "Next Frame", color="#E0E0E0", hovercolor="#D0D0D0")
+        self.save_button = Button(save_ax, "Save Frame", color="#D6F5D6", hovercolor="#BFF0BF")
+        self.bif_button = Button(bif_ax, "Bifurcation: No", color="#F5D6D6", hovercolor="#F0BFBF")
+
+        self.status_text = self.fig.text(0.05, 0.18, "", fontsize=10)
+
+        self.slider.on_changed(self._on_slider)
+        self.prev_button.on_clicked(self._on_prev)
+        self.next_button.on_clicked(self._on_next)
+        self.save_button.on_clicked(self._on_save)
+        self.bif_button.on_clicked(self._on_toggle_bifurcation)
+
+        self.fig.canvas.mpl_connect("button_press_event", self._on_press)
+        self.fig.canvas.mpl_connect("motion_notify_event", self._on_motion)
+        self.fig.canvas.mpl_connect("button_release_event", self._on_release)
+        self.fig.canvas.mpl_connect("key_press_event", self._on_key)
+        self.fig.canvas.mpl_connect("close_event", self._on_close)
+
+    def _state(self) -> FrameState:
+        return self.frame_states[self.current_frame]
+
+    def _render_frame(self) -> None:
+        state = self._state()
+        image = self.images[self.current_frame]
+
+        if self.image_artist is None:
+            self.image_artist = self.ax_image.imshow(image, cmap="gray")
+            self.lumen_line = self.ax_image.plot([], [], color="#1db954", lw=2)[0]
+            self.plaque_line = self.ax_image.plot([], [], color="#ff5a5a", lw=2)[0]
+            self.lumen_points = self.ax_image.scatter([], [], c="#1db954", s=28, edgecolors="black", linewidths=0.4)
+            self.plaque_points = self.ax_image.scatter([], [], c="#ff5a5a", s=28, edgecolors="black", linewidths=0.4)
+        else:
+            self.image_artist.set_data(image)
+
+        lumen_x, lumen_y = state.lumen_x, state.lumen_y
+        plaque_x, plaque_y = state.plaque_x, state.plaque_y
+
+        self.lumen_line.set_data(lumen_x + lumen_x[:1], lumen_y + lumen_y[:1])
+        self.plaque_line.set_data(plaque_x + plaque_x[:1], plaque_y + plaque_y[:1])
+
+        lumen_offsets = np.c_[lumen_x, lumen_y] if lumen_x and lumen_y else np.empty((0, 2))
+        plaque_offsets = np.c_[plaque_x, plaque_y] if plaque_x and plaque_y else np.empty((0, 2))
+        self.lumen_points.set_offsets(lumen_offsets)
+        self.plaque_points.set_offsets(plaque_offsets)
+
+        bif_text = "Yes" if state.bifurcation else "No"
+        bif_color = "#D6F5D6" if state.bifurcation else "#F5D6D6"
+        self.bif_button.label.set_text(f"Bifurcation: {bif_text}")
+        self.bif_button.ax.set_facecolor(bif_color)
+
+        self.status_text.set_text(
+            f"Frame {self.current_frame + 1}/{len(self.frame_states)}    "
+            f"Lumen pts: {len(lumen_x)}    Plaque pts: {len(plaque_x)}    "
+            f"Autosave file: {os.path.basename(self.edits_path)}"
+        )
+        self.fig.canvas.draw_idle()
+
+    def _set_frame(self, frame_idx: int) -> None:
+        frame_idx = int(np.clip(frame_idx, 0, len(self.frame_states) - 1))
+        if frame_idx == self.current_frame:
+            return
+
+        if self.frame_dirty:
+            self._append_frame_edit(self.current_frame, reason="frame_change")
+
+        self.current_frame = frame_idx
+        self.is_updating_slider = True
+        self.slider.set_val(frame_idx)
+        self.is_updating_slider = False
+        self._render_frame()
+
+    def _nearest_point(self, x: float, y: float) -> tuple[str, int] | None:
+        state = self._state()
+
+        def best_idx(xs: list[float], ys: list[float]) -> tuple[int, float] | None:
+            if not xs:
+                return None
+            pts = np.column_stack((np.asarray(xs), np.asarray(ys)))
+            dist = np.linalg.norm(pts - np.asarray([x, y]), axis=1)
+            idx = int(np.argmin(dist))
+            return idx, float(dist[idx])
+
+        lumen = best_idx(state.lumen_x, state.lumen_y)
+        plaque = best_idx(state.plaque_x, state.plaque_y)
+
+        choice: tuple[str, int, float] | None = None
+        if lumen is not None:
+            choice = ("lumen", lumen[0], lumen[1])
+        if plaque is not None and (choice is None or plaque[1] < choice[2]):
+            choice = ("plaque", plaque[0], plaque[1])
+
+        if choice is None or choice[2] > self.drag_threshold_px:
+            return None
+        return choice[0], choice[1]
+
+    def _on_slider(self, val: float) -> None:
+        if self.is_updating_slider:
+            return
+        self._set_frame(int(val))
+
+    def _on_prev(self, _event: Any) -> None:
+        self._set_frame(self.current_frame - 1)
+
+    def _on_next(self, _event: Any) -> None:
+        self._set_frame(self.current_frame + 1)
+
+    def _on_save(self, _event: Any) -> None:
+        self._append_frame_edit(self.current_frame, reason="manual_save")
+        self._render_frame()
+
+    def _on_toggle_bifurcation(self, _event: Any) -> None:
+        state = self._state()
+        state.bifurcation = not state.bifurcation
+        self.frame_dirty = True
+        self._append_frame_edit(self.current_frame, reason="bifurcation_toggle")
+        self._render_frame()
+
+    def _on_key(self, event: Any) -> None:
+        if event.key in {"left", "a"}:
+            self._set_frame(self.current_frame - 1)
+        elif event.key in {"right", "d"}:
+            self._set_frame(self.current_frame + 1)
+        elif event.key == "s":
+            self._on_save(event)
+        elif event.key == "b":
+            self._on_toggle_bifurcation(event)
+
+    def _on_press(self, event: Any) -> None:
+        if event.inaxes != self.ax_image or event.button != 1:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+
+        hit = self._nearest_point(float(event.xdata), float(event.ydata))
+        self.drag_target = hit
+
+    def _on_motion(self, event: Any) -> None:
+        if self.drag_target is None:
+            return
+        if event.inaxes != self.ax_image or event.xdata is None or event.ydata is None:
+            return
+
+        state = self._state()
+        contour_name, idx = self.drag_target
+
+        h, w = self.images[self.current_frame].shape
+        x = float(np.clip(event.xdata, 0, w - 1))
+        y = float(np.clip(event.ydata, 0, h - 1))
+
+        if contour_name == "lumen":
+            state.lumen_x[idx] = x
+            state.lumen_y[idx] = y
+        else:
+            state.plaque_x[idx] = x
+            state.plaque_y[idx] = y
+
+        self.frame_dirty = True
+        self._render_frame()
+
+    def _on_release(self, _event: Any) -> None:
+        if self.drag_target is None:
+            return
+        self.drag_target = None
+        if self.frame_dirty:
+            self._append_frame_edit(self.current_frame, reason="point_drag")
+            self._render_frame()
+
+    def _on_close(self, _event: Any) -> None:
+        if self.frame_dirty:
+            self._append_frame_edit(self.current_frame, reason="window_close")
+
+    def show(self) -> None:
+        self._build_ui()
+        self._render_frame()
+        plt.show()
+
+
+def _default_annotations_path(dicom_path: str, output_root: str) -> str:
+    stem = os.path.splitext(os.path.basename(dicom_path))[0]
+    pattern = os.path.join(output_root, "*", f"{stem}_contours.jsonl")
+    matches = [p for p in glob(pattern) if os.path.isfile(p)]
+    if matches:
+        matches.sort(key=lambda p: os.path.getmtime(p), reverse=True)
+        return matches[0]
+
+    raise FileNotFoundError(
+        "No pipeline contour JSONL found for "
+        f"'{stem}'. Expected files like: {pattern}"
+    )
+
+
+def _default_edits_path(annotations_path: str) -> str:
+    if annotations_path.endswith("_contours.jsonl"):
+        return annotations_path.replace("_contours.jsonl", "_edited_annotations.jsonl")
+    root, _ = os.path.splitext(annotations_path)
+    return root + "_edited_annotations.jsonl"
+
+
+def launch_annotation_editor(
+    dicom_path: str,
+    annotations_path: str | None = None,
+    edits_path: str | None = None,
+    output_root: str = "output",
+) -> None:
+    """Launch interactive annotation GUI.
+
+    If ``annotations_path`` is not provided, the latest contours JSONL is
+    selected from ``output/<timestamp>/``.
+    """
+    if annotations_path is None:
+        annotations_path = _default_annotations_path(dicom_path, output_root)
+
+    if edits_path is None:
+        edits_path = _default_edits_path(annotations_path)
+
+    editor = AnnotationEditor(
+        dicom_path=dicom_path,
+        annotations_path=annotations_path,
+        edits_path=edits_path,
+    )
+    editor.show()