ivus-segmentation

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

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

python DeepIVUS.py edit-annotations data/paul/FILE00005.dcm

Bifurcation Model Workflow

1) Sample new frames for manual labeling

python -u scripts/finetune/bifurcation/sample_new_bifurcation_frames.py

2) Label sampled frames in GUI

python -u scripts/finetune/bifurcation/annotate_bifurcation_samples.py

3) Merge labels into canonical frame bank

python -u scripts/finetune/bifurcation/merge_bifurcation_annotations.py

4) Create/update canonical split

python -u scripts/finetune/bifurcation/create_bifurcation_splits.py

5) Train bifurcation classifier

python -u scripts/finetune/bifurcation/train_bifurcation_classifier.py

6) Evaluate on test and select threshold from validation

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

python -u scripts/finetune/lumen/identify_lumen_class.py

2) Fine-tune lumen model

python -u scripts/finetune/lumen/finetune_lumen_from_saved_model.py \
  --output-model-dir models/standalone/lumen

3) Evaluate lumen model on test split

python -u scripts/finetune/lumen/run_test_inference.py \
  --model-dir models/standalone/lumen

4) Run single-DICOM lumen + bifurcation overlay inference

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.