README.md

---
language:
- en
metrics:
- accuracy
- recall
- f1
pipeline_tag: image-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

```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.