mrsegmentator-konfai 1.5.9

Fast and lightweight MRSegmentator CLI powered by the KonfAI framework.

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 models through the 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.

⭐ 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

Setup

• Input: real whole-body MR, 295 × 259 × 219 (2 mm)
• GPU: single NVIDIA RTX PRO 5000 (24 GB)

Tool (5-fold ensemble)	Time	Peak RAM	Peak VRAM
MRSegmentator-KonfAI	~27 s	~2 GB	~18 GB
Original MRSegmentator	~35 s	~11 GB	~5 GB

📈 Key observations

• Faster whole-body inference at equal accuracy
• ~5× lower system RAM — the accumulator stays on the GPU, not in host memory
• Byte-identical segmentation to the CPU reassembly path

---

🧠 Features

• ⚡ Fast inference powered by 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:

python -m pip install mrsegmentator-konfai

From source:

git clone https://github.com/vboussot/KonfAI.git
python -m pip install -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:

mrsegmentator-konfai segment -i path/to/input.nii.gz -o ./Output/

Evaluate against a reference, or run everything at once:

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

---

⚡ 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 auto-selects the batch size from your free GPU VRAM (vram_plan); 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	—
16 GB	8	~15 GB	—
24 GB	8	~22 GB	~27 s

On a 24 GB card the accumulator stays on the GPU, keeping system RAM ~2 GB 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
• 🤗 Model Hub: huggingface.co/VBoussot/MRSegmentator-KonfAI
• 📦 PyPI Package: pypi.org/project/mrsegmentator-konfai