Metadata-Version: 2.4
Name: mrsegmentator-konfai
Version: 1.8.7
Summary: Fast and lightweight MRSegmentator CLI powered by the KonfAI framework.
Author-email: Valentin Boussot <boussot.v@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/fideus-labs/KonfAI
Project-URL: Repository, https://github.com/fideus-labs/KonfAI
Project-URL: Issues, https://github.com/fideus-labs/KonfAI/issues
Project-URL: License, https://www.apache.org/licenses/LICENSE-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: konfai==1.8.7
Requires-Dist: konfai-apps==1.8.7
Dynamic: license-file
Dynamic: requires-dist

[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![PyPI version](https://img.shields.io/pypi/v/mrsegmentator-konfai.svg?color=blue)](https://pypi.org/project/mrsegmentator-konfai/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![CI](https://github.com/fideus-labs/KonfAI/actions/workflows/konfai_ci.yml/badge.svg)](https://github.com/fideus-labs/KonfAI/actions/workflows/konfai_ci.yml)
[![Paper](https://img.shields.io/badge/📌%20Paper-KonfAI-blue)](https://www.arxiv.org/abs/2508.09823)

# MRSegmentator-KonfAI 

**Fast and lightweight CLI for whole-body MRI segmentation using MRSegmentator models within the KonfAI framework.**

---

## 🧩 Overview

**MRSegmentator-KonfAI** is a lightweight **command-line interface (CLI)** for running **[MRSegmentator](https://github.com/hhaentze/MRSegmentator)** models through the [KonfAI](https://github.com/fideus-labs/KonfAI) deep learning framework.

It provides **fast and efficient inference** for whole-body MRI segmentation, including on low-resource hardware.  

Pretrained models are automatically downloaded from [Hugging Face Hub](https://huggingface.co/VBoussot/MRSegmentator-KonfAI).

## ⭐ Key Advantages

### 📦 Lightweight model distribution

- **~128 MB per model**, with up to **5 folds** available  
- Download **only the folds you need**  
- **Total size with 5 folds:** ~640 MB  
- 🔁 Compared to **~1.07 GB** for the original full MRSegmentator model distribution  

➡️ **Faster setup, smaller disk footprint**

---

## ⚡ Efficient inference

### 🔬 Performance comparison

Same input, the five folds ensembled on both sides (`-f 5`), same PyTorch build
(2.12.1, cu13.0), single **NVIDIA RTX PRO 5000 (24 GB)**, MRSegmentator 2.0.0. Peak RAM =
process-tree resident set; peak VRAM = over baseline. Measured with
`benchmarks/perf/bench_apps.py` (2026-09-09).

| Case (voxels) | Tool | Time | Peak RAM | Peak VRAM |
|---|---|---|---|---|
| **S** (248 × 246 × 141) | **KonfAI** | **15 s** | **5.2 GB** | 18.2 GB |
| | Original | 19 s | 7.2 GB | 3.0 GB |
| **M** (249 × 246 × 246) | **KonfAI** | **21 s** | **5.3 GB** | 16.3 GB |
| | Original | 24 s | 8.5 GB | 3.8 GB |
| **L** (512 × 512 × 531) | **KonfAI** | **86 s** | **6.9 GB** | 20.6 GB |
| | Original | 143 s | 37.4 GB | 14.9 GB |

### 📈 Key observations

- **1.1–1.7× faster**, **1.4–5.4× less host RAM**; the gap widens with the volume.
- The GPU-resident accumulator trades **more VRAM** for the speed and low host RAM,
  while streaming keeps it **bounded**: on the **large** case host RAM stays at
  **6.9 GB** where the original grows to **37.4 GB**.
- The default `-f 2` ensembles two folds and runs faster than the table.

---

## 🧠 Features

- ⚡ **Fast inference** powered by [KonfAI](https://github.com/fideus-labs/KonfAI)
- 🤗 **Automatic model download** from Hugging Face
- 🧩 **Multi-model ensembling**
- 🧠 **Supports evaluation workflows with reference data, and uncertainty estimation without reference**
- 🧾 **Multi-format compatibility:** supports all major medical image formats handled by ITK

---

## 🚀 Installation

From PyPI:
```bash
python -m pip install mrsegmentator-konfai
```

From source:
```bash
git clone https://github.com/fideus-labs/KonfAI.git
cd KonfAI
# konfai and konfai-apps must come from the same checkout: this app pins both to its own
# setuptools_scm version, which only exists on PyPI at a release tag.
python -m pip install -e . -e konfai-apps -e apps/mrsegmentator
```

---

## ⚙️ Usage

The CLI is organised into sub-commands, mirroring the KonfAI Apps operations:

| Sub-command | Purpose |
|---|---|
| `segment` | Run the segmentation (inference). |
| `eval` | Evaluate a segmentation against a reference. |
| `uncertainty` | Estimate uncertainty (fold-ensemble spread). |
| `pipeline` | Segment, then evaluate and estimate uncertainty in one command. |

Run segmentation on an MRI scan:
```bash
mrsegmentator-konfai segment -i path/to/input.nii.gz -o ./Output/
```

Evaluate against a reference, or run everything at once:
```bash
mrsegmentator-konfai eval -i input.nii.gz --gt reference.nii.gz -o ./Output/
mrsegmentator-konfai pipeline -i input.nii.gz --gt reference.nii.gz --gpu 0 -f 3 -uncertainty
```

### Arguments

| Flag | Description | Default |
|------|--------------|----------|
| `-i`, `--inputs` | Input MRI volume(s) or a dataset directory | *required* |
| `-o`, `--output` | Output directory | `./Output/` |
| `-f`, `--folds` | Number of model folds to ensemble, 1–5 (`segment` / `pipeline`) | `2` |
| `-uncertainty` | Also write the inference stack (`segment` / `pipeline`) | `False` |
| `--gt` | Reference segmentation(s): required by `eval`, optional in `pipeline` | *unset* |
| `--mask` | Evaluation mask(s) (`eval` / `pipeline`) | *unset* |
| `--gpu` | GPU id(s), e.g. `0` or `0 1` | CPU if unset |
| `--cpu` | Number of CPU worker processes | *unset* |
| `-q`, `--quiet` | Suppress console output | `False` |

---

## 📖 Reference

If you use **MRSegmentator-KonfAI** in your work, please cite the original MRSegmentator work in addition to this CLI tool.

- Häntze, H. *et al.* (2025).  
  **Segmenting Whole-Body MRI and CT for Multiorgan Anatomic Structure Delineation.**  
  *Radiology: Artificial Intelligence*, 7(6). https://doi.org/10.1148/ryai.240777

- Boussot, V., & Dillenseger, J.-L. (2025).  
  **KonfAI: A Modular and Fully Configurable Framework for Deep Learning in Medical Imaging**.  
  arXiv preprint [arXiv:2508.09823](https://arxiv.org/abs/2508.09823)

---

## ⚡ Performance & VRAM

Benchmarked on a single **NVIDIA RTX PRO 5000 (24 GB)** with a real whole-body MR (295 × 259 × 219, 2 mm), patch `[96, 128, 160]`, 5-fold ensemble, half precision (autocast). The app **measures its batch size on your GPU** (a forward of one patch, then of two, then the largest power of two that fits half of the free VRAM); override it in SlicerKonfAI (⚙ **Advanced**) or on the CLI with `--patch-size` / `--batch-size`.

| Free VRAM | Batch (auto) | Peak VRAM | Time / case |
|:--|:--|:--|:--|
| 8 GB  | 4 | ~8 GB  | n/a |
| 16 GB | 8 | ~15 GB | n/a |
| 24 GB | 8 | ~22 GB | **~27 s** |

On a 24 GB card the accumulator stays **on the GPU**, keeping host RAM low with a **byte-identical** result. The plan stops short of filling the card: a still-larger batch (12 → ~24 GB) saturates the allocator and *slows* inference ~2× without running faster. Inference scales with the case size.

---

## 🔗 Links

- 🧠 **Original MRSegmentator:** [github.com/hhaentze/MRSegmentator](https://github.com/hhaentze/MRSegmentator)  
- 🤗 **Model Hub:** [huggingface.co/VBoussot/MRSegmentator-KonfAI](https://huggingface.co/VBoussot/MRSegmentator-KonfAI)  
- 📦 **PyPI Package:** [pypi.org/project/mrsegmentator-konfai](https://pypi.org/project/mrsegmentator-konfai)


