Metadata-Version: 2.4
Name: totalsegmentator-konfai
Version: 1.8.7
Summary: Fast and lightweight TotalSegmentator 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/totalsegmentator-konfai.svg?color=blue)](https://pypi.org/project/totalsegmentator-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)
[![CI](https://github.com/fideus-labs/KonfAI/actions/workflows/konfai_apps_ci.yml/badge.svg)](https://github.com/fideus-labs/KonfAI/actions/workflows/konfai_apps_ci.yml)
[![Paper](https://img.shields.io/badge/📌%20Paper-KonfAI-blue)](https://www.arxiv.org/abs/2508.09823)

# TotalSegmentator-KonfAI

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

---

## 🧩 Overview

**TotalSegmentator-KonfAI** is a lightweight **command-line interface (CLI)** for running **[TotalSegmentator](https://github.com/wasserth/TotalSegmentator)** models for **multi-organ medical image segmentation**, through the [KonfAI](https://github.com/fideus-labs/KonfAI) deep learning framework.

It provides **fast and efficient inference** for segmentation tasks, including on low-resource hardware. Pretrained models are automatically downloaded from [Hugging Face Hub](https://huggingface.co/VBoussot/TotalSegmentator-KonfAI).

---

## ⭐ Key Advantages

### 📦 Lightweight model distribution

- **~125 MB per model** 1.5 mm model
- 🔁 Compared to **~234 MB** per model for the original TotalSegmentator  
- **~66.2 MB** 3 mm models
- 🔁 Compared to **~135 MB** (original)

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

---

## ⚡ Efficient inference

### 🔬 Performance comparison

Same input, same weights (Datasets 291–295, 1.5 mm, 5-model `total`), same PyTorch build
(2.12.1, cu13.0), single **NVIDIA RTX PRO 5000 (24 GB)**, TotalSegmentator 2.18.0. Peak RAM =
process-tree resident set; peak VRAM = over baseline. Measured with
KonfAI's `benchmarks/perf/bench_apps.py` (2026-09-09).

| Case (voxels) | Tool | Time | Peak RAM | Peak VRAM |
|---|---|---|---|---|
| **S** (240 × 220 × 200) | **KonfAI** | **7.6 s** | **5.0 GB** | 12.3 GB |
| | Original | 29.9 s | 22.6 GB | 3.3 GB |
| **M** (249 × 246 × 246) | **KonfAI** | **17.7 s** | **5.2 GB** | 15.4 GB |
| | Original | 58.3 s | 25.2 GB | 7.1 GB |
| **L** (512 × 512 × 531) | **KonfAI** | **212 s** | **17.6 GB** | **10.6 GB** |
| | Original | 377 s | 47.9 GB | 23.1 GB |

### 📈 Key observations

- **1.8–3.9× faster** whole-body inference across sizes, **2.7–4.8× less host RAM**.
- KonfAI trades **more VRAM on small/medium cases** (larger patches, GPU accumulation)
  for the speed-up, while it stays inside a 24 GB card.
- On **large** cases the streaming reassembly **bounds VRAM** (10.6 GB) where the
  original nears the card limit (23.1 GB / 24 GB), so KonfAI is then lighter on **both**
  RAM and VRAM.

---

## 🧠 Features

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

## 🚀 Installation

From PyPI:
```bash
python -m pip install totalsegmentator-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/totalsegmentator
```

---

## ⚙️ 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. |
| `pipeline` | Segment, then evaluate in one command. |

Perform segmentation on an input volume:

```bash
totalsegmentator-konfai segment total -i path/to/image.nii.gz -o ./Output/
```

Evaluate against a reference, or run both at once:

```bash
totalsegmentator-konfai eval total -i image.nii.gz --gt reference.nii.gz -o ./Output/
totalsegmentator-konfai pipeline total -i image.nii.gz --gt reference.nii.gz --gpu 0
```

### Arguments

| Flag | Description | Default |
|------|--------------|----------|
| `TASK` | Model on Hugging Face (`total`, `total_mr`, `total-3mm`, `total_mr-3mm`), which determines what is predicted | *required* |
| `-i`, `--inputs` | Input medical image(s) or a dataset directory | *required* |
| `-o`, `--output` | Output directory | `./Output/` |
| `--models` | Explicit model identifiers/paths to ensemble (`segment` / `pipeline`) | *unset* |
| `--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` |

> **Note:** TotalSegmentator models do not expose an uncertainty workflow, so there is no `uncertainty` sub-command.

---

## 📖 Reference

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

- Wasserthal, J. *et al.* (2023).  
  **TotalSegmentator: Robust Segmentation of 104 Anatomic Structures in CT Images.**  
  *Radiology: Artificial Intelligence*, 5(5). https://doi.org/10.1148/ryai.230024

- Akinci D’Antonoli, T. *et al.* (2025).  
  **TotalSegmentator MRI: Robust Sequence-independent Segmentation of Multiple Anatomic Structures in MRI.**  
  *Radiology*, 314(2). https://doi.org/10.1148/radiol.241613

- 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 CT (295 × 259 × 219, 2 mm), patch `[96, 128, 160]`, 5-model ensemble (`total`), 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  | 2 | n/a | n/a |
| 16 GB | 4 | n/a | n/a |
| 24 GB | 4 | ~20 GB | **~42 s** |

The 5-model `total` head (117 classes) needs **~20 GB** for its forward, so the ensemble targets a **24 GB card**; on smaller cards use **`total-3mm`** (1 model, 3 mm). Its whole-volume accumulator is too large for the GPU, so reassembly runs on the host (~19 GB RAM). A larger batch saturates the card and *slows* inference. Inference scales with the case size.

---

## 🔗 Links

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

---
