IVUS-Segmentation

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

• contours XML and JSONL
• top-confidence JSONL
• lumen overlay video
• bifurcation predictions JSONL + summary JSON
• overlay video with branch/non-branch flag

• --bifurcation-threshold is optional.
• If omitted, threshold is loaded from threshold.json beside the selected bifurcation model.

2) Edit contour annotations in GUI

Bifurcation Model Workflow

1) Sample new frames for manual labeling

2) Label sampled frames in GUI

3) Merge labels into canonical frame bank

4) Create/update canonical split

5) Train bifurcation classifier

6) Evaluate on test and select threshold from validation

• threshold.json beside the evaluated classifier model file.

Lumen Model Workflow

1) Identify lumen class index in SavedModel logits

2) Fine-tune lumen model

3) Evaluate lumen model on test split

4) Run single-DICOM lumen + bifurcation overlay inference

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