Aditya2162/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.